CLI Guidelines

clig.dev 기반의 CLI 설계 가이드라인과 베스트 프랙티스를 제공합니다.

핵심 철학:

• 인간 중심 설계: 사람이 주 사용자

• 상호 연동성: UNIX 관례 준수, 파이프 조합 가능

• 일관성: 기존 패턴 따라 직관성 확보

• 발견 용이성: 도움말, 예제, 오류 제안

• 공감: 사용자의 성공을 돕는 의도 표현

Instructions

워크플로우: 요청 분석 및 리소스 선택

사용자 요청을 분석하여 필요한 리소스만 선택적으로 로드합니다.

1. 키워드 매칭

철학/원칙 (resources/01-philosophy.md )

• "철학", "원칙", "principle"

• "설계", "design"

• "UX", "사용자 경험"

도움말/문서화 (resources/02-help-documentation.md )

• "help", "도움말", "--help"

• "man page", "문서"

• "usage", "사용법"

출력 (resources/03-output.md )

• "output", "출력"

• "색상", "color"

• "JSON", "포맷"

• "stdout", "stderr"

• "로그", "log"

오류 처리 (resources/04-errors.md )

• "error", "오류", "에러"

• "exit code", "종료 코드"

• "예외", "exception"

• "디버그", "debug"

인자/플래그 (resources/05-arguments-flags.md )

• "argument", "인자"

• "flag", "플래그", "옵션"

• "-v", "--verbose"

• "파라미터", "parameter"

상호작용 (resources/06-interactivity.md )

• "interactive", "대화형"

• "prompt", "프롬프트"

• "input", "입력"

• "TTY", "터미널"

• "확인", "confirm"

서브커맨드 (resources/07-subcommands.md )

• "subcommand", "서브커맨드"

• "command", "명령어"

• "verb noun", "noun verb"

견고성 (resources/08-robustness.md )

• "robust", "견고"

• "signal", "시그널"

• "Ctrl-C", "SIGINT"

• "timeout", "타임아웃"

• "진행률", "progress"

설정 (resources/09-configuration.md )

• "config", "설정"

• "environment", "환경변수"

• ".env", "XDG"

• "우선순위", "priority"

배포/명명 (resources/10-distribution.md )

• "배포", "distribution"

• "install", "설치"

• "이름", "naming"

• "바이너리", "binary"

2. 리소스 로딩 전략

단일 주제

• User: "플래그 네이밍 규칙이 뭐야?"

• → Read resources/05-arguments-flags.md

복합 요청

• User: "CLI 도구 처음부터 만들어줘"

• → Read resources/01-philosophy.md (철학)

• → Read resources/05-arguments-flags.md (인자/플래그)

• → Read resources/02-help-documentation.md (도움말)

• → 필요 시 추가 리소스

불명확한 요청

• User: "CLI 잘 만들고 싶어"

• → REFERENCE.md 확인하여 선택지 제시

3. 리소스 적용

현재 CLI 구조 파악

• 기존 CLI 코드 확인

• 사용 중인 CLI 라이브러리 확인 (Click, argparse, clap 등)

리소스 Read

• 필요한 리소스만 Read

• 언어별 CLI 라이브러리 패턴 고려

패턴 적용

• 가이드라인에 맞게 CLI 구조 개선

• 기존 인터페이스 호환성 유지

• 사용자에게 변경 사항 설명

검증

• --help 출력 확인

• 종료 코드 동작 확인

• 에러 메시지 품질 확인

예시

예시 1: 새 CLI 도구 설계

User: "Python으로 파일 변환 CLI 만들어줘"

• 키워드 매칭: CLI 설계 전반

• Read resources/01-philosophy.md

• Read resources/05-arguments-flags.md

• Read resources/02-help-documentation.md

• Click 또는 argparse 기반 구조 설계

• 표준 플래그 적용 (-h, -v, -o, --quiet 등)

• 도움말 텍스트 작성

예시 2: 에러 처리 개선

User: "CLI 에러 메시지가 불친절해"

• 키워드 매칭: "에러" → 오류 처리

• Read resources/04-errors.md

• 기존 에러 메시지 분석

• 인간 친화적 메시지로 재작성

• 해결 방법 제안 추가

• 적절한 종료 코드 사용

예시 3: 출력 포맷 추가

User: "JSON 출력 옵션 추가해줘"

• 키워드 매칭: "JSON", "출력" → 출력

• Read resources/03-output.md

• --json 플래그 추가

• 구조화된 출력 구현

• TTY 감지 로직 확인

• 기존 출력과 일관성 유지

중요 원칙

• 인간 우선: TTY에서는 사람 읽기용 출력, 파이프에서는 기계 처리용

• 일관성: 기존 UNIX/POSIX 관례 준수

• 발견 가능: 도움말, 예제, 오류 제안으로 사용법 안내

• 견고함: 빠른 응답, 진행률 표시, 정상 종료 처리

• 호환성: 가산적 변경, 비호환 변경 사전 경고

Technical Details

상세한 가이드라인은 각 리소스 파일 참조:

• REFERENCE.md : 리소스 전체 개요

• resources/01-philosophy.md : 설계 철학

• resources/02-help-documentation.md : 도움말 작성

• resources/03-output.md : 출력 가이드라인

• resources/04-errors.md : 오류 처리

• resources/05-arguments-flags.md : 인자와 플래그

• resources/06-interactivity.md : 대화형 인터페이스

• resources/07-subcommands.md : 서브커맨드 설계

• resources/08-robustness.md : 견고성/시그널 처리

• resources/09-configuration.md : 설정 관리

• resources/10-distribution.md : 배포/명명 규칙