continue

plan.md

@@ -0,0 +1,47 @@
+# cross-eval CLI 사용성 리팩토링
+
+## 목표
+`cross-eval`의 CLI 사용 경험을 리팩토링하여, 사용자가 각 옵션의 의미를 빠르게 이해하고 목적에 맞는 옵션 조합을 쉽게 선택할 수 있도록 만든다.
+
+## 배경
+현재 `cross-eval`은 `init`, `run`, `demo`, `doctor` 등 주요 커맨드와 다양한 옵션을 제공하지만, 처음 사용하는 사용자가 어떤 상황에서 어떤 옵션을 써야 하는지 한눈에 이해하기 어렵다. 특히 `run`의 preset, agent 조합, config 기반 실행과 직접 옵션 기반 실행의 관계가 복잡하게 느껴질 수 있다.
+
+## 요구사항
+1. CLI 도움말 또는 온보딩 문구를 리팩토링해 초보 사용자도 주요 흐름을 빠르게 이해할 수 있어야 한다.
+2. 사용자가 대표적인 사용 시나리오별로 적절한 옵션 조합을 쉽게 찾을 수 있어야 한다.
+3. `run` 커맨드의 주요 옵션들(preset, coder/reviewer/senior, config, output 관련)의 역할이 더 명확하게 드러나야 한다.
+4. `init` 이후 사용자가 다음에 무엇을 해야 하는지 자연스럽게 이어지도록 안내해야 한다.
+5. 기존 기능은 유지해야 하며, 동작 방식 자체를 바꾸기보다 설명 구조와 사용 흐름을 개선하는 데 집중해야 한다.
+
+## 사용자 시나리오
+1. 처음 설치한 사용자가 `cross-eval init` 후 무엇을 해야 하는지 알고 싶다.
+2. 사용자가 `run`을 실행하려는데 `--preset`별 차이를 빠르게 비교하고 싶다.
+3. 사용자가 `claude`, `codex`, `senior` 조합을 어떤 상황에서 쓰는지 예시와 함께 이해하고 싶다.
+4. 사용자가 config 기반 실행과 CLI 옵션 기반 실행 중 무엇을 써야 할지 판단하고 싶다.
+5. 사용자가 실행 결과가 어디에 저장되는지, 어떤 식으로 확인하는지 알고 싶다.
+
+## 제약조건
+- 기존 CLI 명령 이름과 핵심 옵션 이름은 유지한다.
+- 기존 파이프라인 동작 로직은 불필요하게 수정하지 않는다.
+- 기능 추가보다 안내 구조, 도움말 문구, 예시, 설명 흐름 개선에 집중한다.
+- 문서는 한국어 사용자 기준으로 이해하기 쉽게 유지하되, 기존 프로젝트 톤과 구조를 해치지 않는다.
+
+## 범위
+### 포함
+- `argparse` help/description/epilog 문구 개선
+- `init` 후 다음 단계 안내 문구 개선
+- `run` 사용 예시 정리 및 대표 조합 예시 보강
+- preset/agent/config/output 개념 설명 재구성
+- 필요 시 README 또는 온보딩 문구 일부 정리
+
+### 제외
+- 새로운 preset 추가
+- 새로운 CLI 옵션 추가
+- 파이프라인 실행 알고리즘 변경
+- 에이전트 호출 방식 자체 변경
+
+## 성공 기준
+1. `--help`만 읽어도 기본 사용 흐름이 명확하다.
+2. 사용자가 대표 시나리오별 실행 예시를 바로 복사해 쓸 수 있다.
+3. `init → 작성 → doctor → run → output 확인` 흐름이 자연스럽게 연결된다.
+4. 옵션 설명이 길기만 하지 않고, 실제 선택 판단에 도움이 되도록 구조화된다.