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. 리소스 적용

1. 현재 CLI 구조 파악

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

2. 리소스 Read

   • 필요한 리소스만 Read
   • 언어별 CLI 라이브러리 패턴 ê³ ë ¤

3. 패턴 적용

   • 가이드라인에 맞게 CLI 구조 개선
   • 기존 인터페이스 호환성 유지
   • 사용자에게 변경 사항 설명

4. 검증

   • --help 출력 확인
   • 종료 코드 동작 확인
   • 에러 메시지 품질 확인

예시

예시 1: 새 CLI 도구 설계

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

1. 키워드 매칭: CLI 설계 전반
2. Read resources/01-philosophy.md
3. Read resources/05-arguments-flags.md
4. Read resources/02-help-documentation.md
5. Click 또는 argparse 기반 구조 설계
6. 표준 플래그 적용 (-h, -v, -o, –quiet 등)
7. 도움말 텍스트 작성

예시 2: 에러 처리 개선

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

1. 키워드 매칭: “에러” → 오류 처리
2. Read resources/04-errors.md
3. 기존 에러 메시지 분석
4. 인간 친화적 메시지로 재작성
5. 해결 방법 제안 추가
6. 적절한 종료 코드 사용

예시 3: 출력 포맷 추가

User: “JSON 출력 옵션 추가해줘”

1. 키워드 매칭: “JSON”, “출력” → 출력
2. Read resources/03-output.md
3. –json 플래그 추가
4. 구조화된 출력 구현
5. TTY 감지 로직 확인
6. 기존 출력과 일관성 유지

중요 원칙

1. 인간 우선: TTY에서는 사람 읽기용 출력, 파이프에서는 기계 처리용
2. 일관성: 기존 UNIX/POSIX 관례 준수
3. 발견 가능: 도움말, 예제, 오류 제안으로 사용법 안내
4. 견고함: 빠른 응답, 진행률 표시, 정상 종료 처리
5. 호환성: 가산적 변경, 비호환 변경 사전 경고

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: 배포/명명 규칙