feat: add cli-ux-test skill for systematic CLI UX auditing (#13)

Multi-agent pipeline skill that builds, tests, and analyzes CLI UX
against clig.dev/POSIX/GNU principles. Validated across 4 iterations
with 100% pass rate on all assertions.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: minsoo-web

cli-ux-test/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: cli-ux-test
+description: CLI 도구의 UX를 체계적으로 테스트하고 개선 리포트를 생성하는 멀티 에이전트 파이프라인. 실제 CLI 명령을 실행하고, clig.dev/POSIX/GNU/12 Factor CLI Apps 원칙 기반으로 평가하여 심각도별 분류 리포트와 구체적 개선 제안을 도출합니다. Use when you want to audit CLI UX, test a command-line tool's usability, review CLI design quality, or generate a CLI improvement report. Also triggers on: "CLI 테스트", "UX 점검", "CLI 리뷰", "사용성 평가", "CLI UX audit", "커맨드라인 개선".
+---
+
+# CLI UX Test
+
+CLI 도구의 사용자 경험을 실제 실행 기반으로 평가하는 멀티 에이전트 파이프라인.
+
+## Pipeline
+
+```
+Build → Discover & Plan → Test(parallel) → Analysis & Advisory → Summary
+```
+
+## Phase 1: Build
+
+대상 프로젝트를 빌드한다.
+
+```bash
+cargo build --release 2>&1
+```
+
+빌드 성공 시 바이너리 경로(`target/release/<name>`)를 기록한다. 빌드 실패 시 에러를 사용자에게 보고하고 중단한다.
+
+## Phase 2: Discover & Plan
+
+CLI의 전체 표면적을 매핑하고 테스트 시나리오를 한 번에 생성한다. 별도 파일로 분리하지 않고 이 Phase의 결과로 시나리오까지 도출한다.
+
+### 2a. Surface Area 매핑
+
+아래를 모두 실행하고 결과를 수집한다:
+
+1. `<binary> --help` — 최상위 도움말, 서브커맨드 목록 파싱
+2. `<binary> --version` — 버전 출력 형식 확인
+3. 각 서브커맨드의 `--help` (재귀적으로 하위 서브커맨드까지)
+4. 소스 코드의 CLI 정의 파일 (clap derive, arg parser 등) 읽기 — 숨겨진 플래그, 환경변수 확인
+5. README, docs 디렉토리 — 문서화된 사용법 vs 실제 동작 비교
+
+수집한 정보를 바로 시나리오 생성에 활용한다. surface-map.md를 별도 생성하지 않아도 된다 — 최종 리포트의 부록에 CLI Surface Map 내용이 포함되면 충분하다.
+
+### 2b. 시나리오 생성
+
+수집한 표면적 정보를 기반으로 테스트 시나리오를 4개 카테고리로 생성한다.
+
+**Category A — Help & Discoverability**: 도움말 품질, 버전 출력, 오타 시 제안, 빈 실행 시 안내
+**Category B — Arguments & Error Handling**: 필수 인자 누락, 잘못된 값, 존재하지 않는 플래그, 종료 코드
+**Category C — Output & Formatting**: stdout/stderr 분리, 컬러 일관성, 성공/실패 메시지, 진행 표시
+**Category D — Edge Cases & Robustness**: 비-TTY, 빈 상태, 네트워크 실패, Ctrl+C, 동시 실행
+
+**Category E — Documentation Accuracy**는 CLI 실행이 아닌 소스-문서 비교이므로, Phase 4 Analysis에서 수행한다 (테스트 에이전트에 포함하지 않는다).
+
+각 시나리오를 다음 형식으로 기록:
+
+```json
+{
+  "id": "B-03",
+  "category": "B",
+  "name": "잘못된 enum 값",
+  "command": "<binary> --editor foo",
+  "expected": "유효한 값 목록을 포함한 에러 메시지",
+  "ux_criteria": ["error-message-quality", "suggest-valid-values"]
+}
+```
+
+카테고리별로 `scenarios/category-{a,b,c,d}.json`에 저장한다.
+
+**인터랙티브 기능 참고**: TUI, 프롬프트 등 인터랙티브 기능은 자동 테스트가 어려우므로, 비-TTY 폴백 동작과 시작/종료 동작만 시나리오에 포함한다. 인터랙티브 UX는 소스 코드 리뷰 기반으로 평가한다.
+
+## Phase 3: Test (Parallel Agents)
+
+`agents/ux-tester.md`를 읽고, 카테고리별로 ux-tester 에이전트를 **병렬 실행**한다.
+
+각 에이전트에게 전달할 정보:
+- `agents/ux-tester.md`의 전체 내용 (에이전트 역할과 평가 기준)
+- 바이너리 경로
+- 해당 카테고리의 시나리오 목록
+- CLI Surface Map (맥락 파악용)
+- 결과 저장 경로: `findings/category-{a,b,c,d}.json`
+
+에이전트 설정:
+- Agent tool 사용, `subagent_type: "oh-my-claudecode:qa-tester"`
+- `mode: "bypassPermissions"` (테스트 명령을 자동 실행하기 위해)
+
+4개 에이전트를 **한 번에 모두** 실행한다 (Agent tool 4개를 하나의 메시지에).
+
+모든 에이전트 완료 후 `findings/` 디렉토리의 결과를 확인한다.
+
+## Phase 4: Analysis & Advisory
+
+`agents/reporter.md`, `agents/cli-advisor.md`, `references/cli-ux-principles.md`를 읽고 **하나의 에이전트**를 실행한다.
+별도의 report.md와 advisory.md를 생성하지 않고, 분석과 제안을 하나의 흐름으로 통합한다.
+
+전달할 정보:
+- `agents/reporter.md`의 전체 내용 (심각도 분류, 패턴 식별 기준)
+- `agents/cli-advisor.md`의 전체 내용 (개선 제안 형식, 우선순위 매트릭스)
+- `references/cli-ux-principles.md`의 전체 내용
+- 모든 카테고리의 findings (Phase 3 결과)
+- Phase 2에서 수집한 CLI 표면적 정보
+- 프로젝트 소스 코드 루트 경로 (에이전트가 직접 소스를 읽어 구체적 제안을 할 수 있도록)
+- README.md 경로 (Category E 문서 정확성 검증용 — Analysis Phase에서 소스 코드와 대조)
+
+에이전트 설정:
+- `subagent_type: "oh-my-claudecode:architect"`, `model: "opus"`
+
+에이전트가 수행할 작업:
+1. **문서 정확성 검증 (Category E)**: README/docs의 경로·사용법·예시를 소스 코드와 대조한다. 이 작업은 소스를 이미 읽는 분석 단계에서 함께 수행하는 것이 효율적이므로 별도 테스트 에이전트를 사용하지 않는다. 검증 항목:
+   - 경로 검증: README의 파일/디렉토리 경로를 소스 코드의 경로 상수/함수와 대조
+   - 사용 예시 검증: README의 사용 예시를 실제 CLI 동작과 비교
+   - 옵션/플래그 검증: README에 언급된 옵션이 --help에도 있는지, 그 반대도 확인
+   - 환경변수 검증: README에 기술된 환경변수가 소스에서 실제로 사용되는지
+   문서 불일치는 사용자가 가장 먼저 만나는 혼란이므로 높은 심각도(Critical/Major)로 분류한다.
+2. findings를 통합하고 심각도를 분류한다 (reporter.md 기준)
+3. 시스템적 패턴과 근본 원인을 식별한다
+4. clig.dev 원칙 기반으로 평가한다
+5. 소스 코드를 읽고 구체적 개선 제안을 작성한다 (cli-advisor.md 기준)
+6. **Top 3 Quick Win**에는 before/after 코드 스니펫을 포함한다. 나머지 개선 제안은 Top 권장사항 테이블에 코드 없이 기재한다.
+
+결과를 바로 최종 리포트 템플릿에 맞춰 작성한다.
+
+## Phase 5: Summary Report
+
+모든 결과를 종합하여 최종 리포트를 생성한다. 아래 템플릿을 따른다:
+
+```markdown
+# CLI UX Test Report: <프로젝트명>
+
+**테스트 일시**: YYYY-MM-DD HH:MM
+**바이너리**: <path>
+**버전**: <version>
+
+## Executive Summary
+
+- 총 시나리오: N개 실행
+- 발견된 이슈: N개 (Critical: N, Major: N, Minor: N, Enhancement: N)
+- 주요 강점: (잘 된 점 2-3개)
+- 핵심 개선 영역: (가장 중요한 개선 2-3개)
+
+## Quick Wins (Top 3, 1시간 이내 구현 가능)
+
+가장 먼저 읽히는 위치에 배치한다. 영향도가 가장 큰 **3개**만 선별하여 before/after 코드 스니펫을 포함한다.
+리포트를 읽고 즉시 복사-붙여넣기로 적용할 수 있어야 한다. 나머지 개선 항목은 아래 "Top 개선 권장사항" 테이블에 코드 없이 기재한다.
+
+| # | 제목 | 예상 소요 | 변경 파일 | 설명 |
+|---|------|----------|----------|------|
+
+각 Quick Win 아래에 코드 변경 예시:
+```
+// Before (src/presets.rs:42)
+println!("Fetching preset themes...");
+
+// After
+eprintln!("Fetching preset themes...");
+```
+
+## 카테고리별 결과
+
+### A. Help & Discoverability
+| ID | 시나리오 | 결과 | 심각도 | 설명 |
+|----|---------|------|--------|------|
+
+### B. Arguments & Error Handling
+(같은 형식)
+
+### C. Output & Formatting
+(같은 형식)
+
+### D. Edge Cases & Robustness
+(같은 형식)
+
+### E. Documentation Accuracy
+| ID | 문서 위치 | 문서 내용 | 실제 동작 | 심각도 | 설명 |
+|----|----------|----------|----------|--------|------|
+
+## Top 개선 권장사항
+
+(impact x effort 기준 우선순위, advisory.md에서 발췌)
+
+| 순위 | 제목 | 심각도 | 영향도 | 구현 난이도 | 예상 소요 | 설명 |
+|------|------|--------|--------|------------|----------|------|
+
+## 원칙 준수 매트릭스
+
+| 원칙 (clig.dev) | 준수 | 비고 |
+|----------------|------|------|
+
+## Feature Matrix — 유사 CLI 도구 비교
+
+이 도구를 같은 카테고리의 잘 설계된 CLI 도구(ripgrep, gh, fd, bat, docker 등)와 기능별로 비교한다.
+격차가 큰 기능이 곧 개선 우선순위의 근거가 된다.
+
+| 기능 | 이 도구 | ripgrep | gh | fd/bat | 비고 |
+|------|---------|---------|-----|--------|------|
+| Shell completions | | | | | |
+| --json output | | | | | |
+| --quiet/--verbose | | | | | |
+| Color disable (NO_COLOR) | | | | | |
+| Help examples | | | | | |
+| (도구에 맞게 행 추가) | | | | | |
+
+## stdout/stderr Decision Map
+
+각 출력 유형이 어디로 가야 하는지, 현재 어디로 가고 있는지를 정리한다.
+stdout/stderr 혼재는 스크립트 사용성을 해치는 대표적 이슈이므로 별도 섹션으로 분석한다.
+
+| 출력 유형 | 올바른 채널 | 현재 채널 | 일치 | 비고 |
+|----------|-----------|----------|------|------|
+| 정상 결과 데이터 | stdout | | | |
+| 에러 메시지 | stderr | | | |
+| 진행 표시 | stderr | | | |
+| 경고 | stderr | | | |
+| 디버그 정보 | stderr | | | |
+
+## 인터랙티브 기능 소스 리뷰
+
+(자동 테스트 불가능했던 인터랙티브 기능에 대한 코드 리뷰 기반 평가)
+
+## 부록
+
+### CLI Surface Map
+(커맨드 트리, 플래그/옵션, 환경변수 — Phase 2에서 수집한 표면적 정보)
+
+### 실패/Partial 시나리오 상세 로그
+(fail 또는 partial로 평가된 시나리오만 상세 로그를 포함한다. pass 시나리오는 카테고리별 테이블에서 충분하므로 부록에 반복하지 않는다.)
+```
+
+리포트를 `cli-ux-report.md`에 저장하고 사용자에게 경로를 알려준다.
+
+## Workspace
+
+모든 중간/최종 산출물은 아래 구조로 저장한다:
+
+```
+<project>/.omc/reports/cli-ux-test/<timestamp>/
+├── scenarios/
+│   ├── category-a.json
+│   ├── category-b.json
+│   ├── category-c.json
+│   └── category-d.json
+├── findings/
+│   ├── category-a.json
+│   ├── category-b.json
+│   ├── category-c.json
+│   └── category-d.json
+└── cli-ux-report.md          ← 최종 리포트 (분석+제안 통합)
+```
+
+별도의 surface-map.md, report.md, advisory.md는 생성하지 않는다. 모든 내용이 최종 리포트에 통합된다.

cli-ux-test/agents/cli-advisor.md

@@ -0,0 +1,124 @@
+# CLI Advisor Agent
+
+CLI 설계 전문 지식을 바탕으로 구체적이고 실행 가능한 개선 제안을 도출하는 자문 에이전트.
+
+## 역할
+
+당신은 CLI 도구 설계 전문가입니다. clig.dev, POSIX, GNU, 12 Factor CLI Apps의 원칙을 깊이 이해하고 있으며, 수많은 CLI 도구(ripgrep, fd, bat, jq, gh, docker 등)의 설계를 분석해 본 경험이 있습니다. Reporter의 분석 리포트를 받아, 각 이슈에 대해 구체적이고 실행 가능한 개선 제안을 제공합니다.
+
+## 자문 절차
+
+### Step 1: 리포트와 소스 분석
+
+Reporter의 리포트를 읽고, 관련 소스 코드를 직접 확인한다. 소스를 읽어야 하는 이유:
+- 이슈의 근본 원인을 정확히 파악하기 위해
+- 현재 구현의 제약 조건을 이해하기 위해
+- 실현 가능한 제안을 하기 위해
+
+### Step 2: 원칙 기반 평가
+
+`references/cli-ux-principles.md`의 원칙을 기준으로 현재 구현을 평가한다. 단순히 "위반 여부"가 아니라 "해당 원칙이 이 도구에 얼마나 중요한가"를 함께 고려한다.
+
+모든 원칙이 모든 도구에 똑같이 적용되지는 않는다. 예를 들어:
+- 파이프라인 도구에는 composability가 핵심이지만, 인터랙티브 TUI 도구에는 덜 중요할 수 있다
+- 개발자 도구에는 verbose 출력이 유용하지만, 스크립트용 도구에는 조용한 기본값이 좋다
+
+### Step 3: 개선 제안 작성
+
+각 이슈(또는 패턴)에 대해 아래 형식으로 제안을 작성한다:
+
+```markdown
+### [제안 제목]
+
+**대상 이슈**: [관련 finding ID 목록]
+**심각도**: Critical/Major/Minor/Enhancement
+**영향도**: 높음/중간/낮음
+**구현 난이도**: 높음/중간/낮음
+**예상 소요**: [15분 / 30분 / 1시간 / 2-4시간 / 1일+ 등 구체적 시간]
+
+#### 현재 동작
+무엇이 문제인지 구체적으로 설명한다. 실제 출력 예시를 포함한다.
+
+#### 권장 동작
+어떻게 바뀌어야 하는지 구체적으로 설명한다. 이상적인 출력 예시를 포함한다.
+
+#### 구현 가이드
+소스 코드에서 어떤 파일의 어떤 부분을 어떻게 변경하면 되는지 설명한다.
+프레임워크(Clap 등)의 기능을 활용할 수 있는 경우 해당 API를 안내한다.
+
+#### 참조 사례
+같은 문제를 잘 해결한 다른 CLI 도구의 예시를 든다.
+
+#### 근거 원칙
+이 제안의 근거가 되는 CLI UX 원칙을 인용한다.
+```
+
+### Step 4: 우선순위 결정
+
+모든 제안을 아래 매트릭스로 우선순위를 정한다:
+
+```
+        높은 영향도     낮은 영향도
+쉬운    ★★★★★         ★★★
+구현    Quick Win       Nice to Have
+
+어려운  ★★★★          ★★
+구현    Strategic       Low Priority
+```
+
+Quick Win을 가장 먼저, Low Priority를 가장 나중에 배치한다.
+
+## 출력 형식
+
+`advisory.md`를 아래 구조로 작성한다:
+
+```markdown
+# CLI Design Advisory
+
+## 전체 평가
+
+도구의 전반적인 CLI 설계 성숙도를 한 문단으로 요약한다.
+강점과 개선 기회를 균형 있게 서술한다.
+
+## Top 3 Quick Wins (1시간 이내 구현 가능)
+
+리포트에서 가장 먼저 눈에 들어오는 위치. **영향도가 가장 큰 3개만** 선별한다. 각 항목에:
+- 예상 소요 시간 (15분/30분/1시간)
+- 변경 대상 파일과 함수
+- **before/after 코드 스니펫** — 실제 소스를 읽고 현재 코드와 변경 후 코드를 보여준다
+- 기대 효과
+
+이 섹션만 읽고도 즉시 복사-붙여넣기로 개선을 적용할 수 있어야 한다. 추상적 설명이 아니라 구체적 코드 변경이 핵심이다.
+나머지 개선 항목은 "우선순위별 개선 제안" 테이블에 코드 없이 기재한다 — 코드 스니펫 생성을 3개로 제한하여 분석 효율을 높인다.
+
+## 원칙 준수 매트릭스
+
+| 원칙 | 준수 | 근거 |
+|------|------|------|
+| Human-first design | ✅/⚠️/❌ | 구체적 근거 |
+| Composability | ... | ... |
+| ...
+
+## 우선순위별 개선 제안
+
+### Strategic (높은 영향, 어려운 구현)
+(제안 상세 — 각 항목에 예상 소요 시간 포함)
+
+### Nice to Have (낮은 영향, 쉬운 구현)
+(제안 상세)
+
+### Low Priority (낮은 영향, 어려운 구현)
+(제안 상세)
+
+## 벤치마크 비교
+
+비슷한 카테고리의 잘 설계된 CLI 도구와 비교하여, 어떤 부분에서 배울 수 있는지 정리한다.
+Feature Matrix 형식으로 기능별 유무를 한눈에 볼 수 있게 정리한다.
+```
+
+## 판단 원칙
+
+- 이론보다 실용성을 우선한다. "원칙적으로는 X여야 하지만 이 도구의 맥락에서는 Y가 더 적합하다"는 판단이 가능하다.
+- 코드 변경 제안은 구체적이어야 한다. "에러 핸들링을 개선하라"가 아니라 "src/main.rs의 42번째 줄에서 anyhow context를 추가하여 사용자에게 어떤 파일에서 문제가 발생했는지 알려주어라."
+- 도구의 정체성을 존중한다. 인터랙티브 TUI 도구를 무조건 파이프라인 친화적으로 만들라고 하지 않는다.
+- 점진적 개선을 권장한다. 한 번에 모든 것을 바꾸라고 하지 않고, 단계적으로 개선할 수 있는 로드맵을 제시한다.