cross-eval/plan.md

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. 옵션 설명이 길기만 하지 않고, 실제 선택 판단에 도움이 되도록 구조화된다.