CLI Help Layers: 도움말 계층형 설계 가이드
AI-First CLI의 명령줄 상호작용 및 문서 체계를 위한 설계 지침입니다. 핵심 독자: 인간 개발자 + LLM/Agent.
세 가지 설계 철학
- 점진적 공개: usage → help → man, 정보 밀도가 계층별로 증가하며, agent는 대부분의 시나리오에서 처음 두 계층만 필요로 합니다.
- 예제가 곧 표준: tldr에서 차용한 방식으로, 각 계층의 문서는 실행 가능한 예제를 기준점으로 삼습니다.
- 구조화 우선: 고정된 구분자와 형식 규칙을 통해 LLM이 제로샷 추출을 쉽게 할 수 있도록 합니다.
네 계층 정보 구조
| 트리거 방식 | 계층 | 적용 범위 | 내용 |
|---|---|---|---|
| 명령어 인자 없음 | @USAGE | 80% | BRIEF + SYNTAX + 3-5 EXAMPLES |
-h / --help | @HELP | 95% | OPTIONS 표 + ENUMS + COMMON ERRORS |
하위 명령어 --help | @HELP sub | 98% | 고유 옵션 + INHERITED OPTIONS + TEMPLATE |
--man | @MAN | 100% | SCHEMA + EXIT CODES + ALL ERRORS + CAVEATS |
구조화된 마크
@USAGE <path> / @HELP <path> / @MAN <path> → 계층 식별자
BRIEF: / SYNTAX: / OPTIONS: / ENUMS: / EXAMPLES: / ERRORS: → 블록 레이블
# [RECOMMENDED] / [TEMPLATE] / [PIPELINE] / [ADVANCED] → 예제 레이블
Agent가 사용할 정규식: ^@(USAGE|HELP|MAN)\s+(.+)$, 블록: ^([A-Z ]+):$
워크플로
CLI 도움말 문서를 설계하거나 검토할 때:
- 명령어 구조 결정 →
references/architecture.md참조 (명명 규칙, 명사-동사 구성) - Usage 작성 →
references/usage-spec.md참조 (템플릿 + 예제 선정 원칙) - Help 작성 →
references/help-spec.md참조 (OPTIONS 표 + 열거형 + 하위 명령어 Help) - Man 작성 →
references/man-spec.md참조 (SCHEMA + EXIT CODES + 전체 오류 코드) - 오류 메시지 설계 →
references/error-design.md참조 (오류 코드 인코딩 + 각 계층 임베딩 전략) - Agent 친화성 최적화 →
references/agent-friendly.md참조 (문체 스타일 + 마크 시스템 + 공개 절차) - 대조 확인 →
references/checklist.md참조 (5차원 체크리스트) - 전체 예제 참조 →
references/example-feishu-doc.md참조 (feishu doc 명령어 패밀리의 세 계층 전체 실습)
적용 범위
다음에는 이 스킬을 사용하지 마십시오:
- CLI 도구의 실제 코드 구현 (문서 설계만 담당)
- 비명령줄 API 문서 설계
- 기존 CLI 도구의 실행 및 디버깅