cross-eval/UX_IMPROVEMENT_PLAN.md

cross-eval UX 개선 계획

사용자 안내 메시지, 에러 메시지, 도움말 텍스트 전반의 품질을 높여서 처음 쓰는 사람도 막히지 않고 파이프라인을 돌릴 수 있게 만든다.

---

1. CLI 도움말 텍스트 개선

1.1 cross-eval 메인 도움말

• 메인 description에 "어떤 문제를 해결하는 도구인지" 한 줄 요약 추가
  • 현재: "AI 코딩 에이전트의 결과물을 자동으로 검증하는 CLI 도구"
  • 개선: "AI 코딩 에이전트가 기획서대로 구현했는지 자동 교차 검증. 과최적화·누락·거짓 통과를 잡아냄"
• 서브커맨드별 한 줄 설명을 메인 help에 추가 (init/doctor/demo/run 각각)

1.2 cross-eval run 도움말

• epilog의 프리셋 테이블이 너무 길음 — "빠른 선택 가이드" 3줄 추가
  • 예: "처음이면 simple, 리뷰만 하려면 review-only, 코딩+리뷰+자동수정이면 coding-review-fix"
• --reasoning-effort 도움말에 별칭(extra-high, x-high 등) 명시
• --target 옵션이 실제로 프롬프트에 어떤 영향을 주는지 설명 추가
• --agentic 플래그 설명에 worktree 생성/정리 동작 요약 추가
• --min-iter 설명에 "왜 PASS인데 반복하는지" 용도 한 줄 추가
  • 예: "결과 안정성 확인용. 한 번 PASS가 우연이 아닌지 재검증"
• --dry-run 설명에 "에이전트 호출 없이 프롬프트만 미리보기" 명확히
• 에이전트 축약 규칙(claude → claude-coder 등) 예시와 함께 더 명확하게

1.3 cross-eval init 도움말

• --guided 옵션을 더 눈에 띄게 — "처음이면 --guided 추천" 문구
• 생성되는 파일 설명에 "각 파일을 어떻게 쓰는지" 한 줄씩 추가

1.4 cross-eval doctor 도움말

• 어떤 항목을 점검하는지 목록 미리 보여주기
• "인증 실패 시 어떻게 해야 하는지" 구체적 명령어 포함

1.5 cross-eval demo 도움말

• mock vs live 차이를 한 눈에 볼 수 있도록 비교 추가
• --escalate 옵션이 mock 전용인 점 강조

---

2. 에러 메시지 개선

2.1 필수 입력 누락

• --plan 없이 cross-eval run 실행 시 명확한 에러:
  • "기획서(plan)가 필요합니다. --plan plan.md 또는 .cross-eval/config.yaml의 inputs.plan에 지정하세요."
• config.yaml 없이 실행 시 기본값 사용 중임을 알리는 INFO 메시지 추가

2.2 에이전트 실패 메시지

• AUTH 실패 시 구체적 해결 명령어 제시
  • Claude: "claude login 으로 인증하세요"
  • Codex: "codex auth 로 인증하세요"
• USAGE_LIMIT 시 어떤 한도인지 힌트 (토큰? 요금?)
• EMPTY_DIFF 시 "에이전트가 파일을 수정하지 않았습니다" + 가능한 원인 목록
• WRITE_FAILURE 시 worktree 경로와 권한 상태 출력
• 에이전트 빈 출력(empty output) 시 "에이전트가 응답하지 않았습니다. 프롬프트가 너무 길거나 인증 만료일 수 있습니다" 등 원인 제안

2.3 설정 검증 에러

• 중복 step name 에러에 "어떤 phase의 어떤 step이 중복인지" 구체적으로
• 없는 에이전트 참조 시 "사용 가능한 에이전트: ..." 리스트 포함 (이미 있으나 확인)
• YAML 파싱 에러 시 라인 번호 포함

2.4 파일/경로 에러

• "File not found: {path}" → "파일을 찾을 수 없습니다: {path}\n 현재 디렉토리: {cwd}" 로 개선
• docs 디렉토리 비어있을 때 → "참고 문서 폴더가 비어있습니다: {path}\n .md, .txt 등 문서 파일을 넣어주세요"

---

3. 진행 상태 메시지 개선

3.1 파이프라인 실행 중

• 실행 시작 시 요약 배너 출력:

  ━━━ cross-eval ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Plan:      .cross-eval/plan.md
    Preset:    simple (코딩→리뷰→반복)
    Coder:     claude-coder
    Reviewer:  claude-reviewer
    Max iter:  3
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  

• 각 iteration 시작 시 "무엇을 하려는 단계인지" 한 줄 설명
  • 예: "Iteration 1/3 — Coder가 기획서 기반 초기 구현 중..."
  • 예: "Iteration 2/3 — 리뷰 피드백 반영해서 수정 중..."
• 타임아웃 시 경과 시간과 제한 시간 모두 출력

3.2 결과 요약

• 최종 결과에 소요 시간 추가
• FAIL 시 "마지막 리뷰에서 지적된 주요 이슈 N개" 간단 요약
• ESCALATE 시 사람이 봐야 할 이유 1~2줄 요약
• dry-run 종료 시 "이것은 미리보기입니다. 실제 실행하려면 --dry-run을 빼세요" 명시

3.3 Auto-escalation 안내

• auto-escalation 발동 시 "N회 연속 FAIL → 자동 에스컬레이션" 설명
• 어떤 조건에서 auto-escalation이 발동하는지 run 도움말에 언급

---

4. 첫 사용 경험(Onboarding) 개선

4.1 init 후 안내

• plan.md 템플릿에 실제 예시 포함 (현재 최소한의 구조만 있음)
  • "## 기능 요구사항" 아래 구체적 예시 한 개
• checklist.md 템플릿에 체크리스트 작성 가이드 + 예시 추가
• init 완료 후 "다음 단계" 안내를 더 구체적으로:
  • 현재: "1. plan.md에 기획서 작성"
  • 개선: "1. .cross-eval/plan.md를 열어 기획서를 작성하세요 (예: 구현할 기능, API 스펙, DB 스키마 등)"

4.2 doctor 개선

• 체크 통과 시 "준비 완료! cross-eval run --plan .cross-eval/plan.md 로 실행하세요" 안내
• 인증 실패 시 OS별 설치/인증 가이드 URL 포함

4.3 demo 개선

• demo 완료 후 "실제 프로젝트에서 시작하려면:" 안내 추가
• mock demo에서 각 단계가 뭘 하는 건지 주석 스타일로 설명

---

5. 용어 일관성

• "에이전트 이름" vs "에이전트 역할" 구분 통일
  • 이름: claude-coder, codex-reviewer (실제 실행 단위)
  • 역할: coder, reviewer, senior (논리적 역할)
• Verdict 표기 통일: 항상 대문자 PASS / FAIL / ESCALATE
• "프리셋" vs "파이프라인" 용어 정리
  • --preset은 "파이프라인 유형"으로 통일
• 한영 혼용 줄이기 — 한국어 모드에서 불필요한 영어 최소화
  • 단, PASS/FAIL/ESCALATE 같은 verdict은 영어 유지 (가독성)

---

6. 출력 디렉토리 구조 안내

• run 완료 시 출력 폴더 구조 요약 출력:

  Output: .cross-eval/output/
    ├── iter-1/          (각 반복의 에이전트 출력)
    ├── iter-2/
    └── final-report.md  (최종 리포트)
  

• report.md 상단에 "이 리포트 읽는 법" 간단 안내 추가

---

7. config.yaml 주석 개선

• 기본 생성되는 config.yaml에 각 섹션별 설명 주석 보강
• 자주 쓰는 설정 변경 예시를 주석으로 포함
  • 예: "# 리뷰어를 2개로 늘리려면: reviewer: [claude, codex]"
  • 예: "# 에이전트 모드로 실제 파일 수정: agentic: true"
• phase-based 파이프라인 커스텀 예시 주석 추가

---

우선순위

우선순위	항목	이유
P0	2.1 필수 입력 누락 에러	가장 자주 부딪히는 문제
P0	4.1 init 후 안내 + 템플릿	첫 사용에서 막히면 이탈
P0	3.1 실행 시작 요약 배너	뭐가 돌아가는지 알아야 함
P1	2.2 에이전트 실패 메시지	실패 시 뭘 해야 하는지 모름
P1	1.2 run 도움말 정리	옵션이 많아서 혼란
P1	5. 용어 일관성	혼동 줄이기
P2	3.2~3.3 결과/진행 메시지	있으면 좋지만 급하진 않음
P2	7. config.yaml 주석	파워 유저 편의
P2	6. 출력 구조 안내	한 번 보면 이해됨
P3	1.3~1.5 나머지 도움말	점진적 개선

---

테스트 방법

각 항목 수정 후:

1. 도움말 확인: cross-eval --help, cross-eval run --help 등
2. 에러 경로 확인: 일부러 잘못된 입력으로 실행 → 에러 메시지가 유용한지
3. 첫 사용 시뮬레이션: 빈 디렉토리에서 init → doctor → demo → run 풀 플로우
4. cross-eval 자체로 검증: 이 문서를 plan.md로 사용해 cross-eval run 실행