# Cross-Eval CLI 구현 계획

## Context

AI 에이전트 2개를 활용한 개발 워크플로우(기획→체크리스트→개발→리뷰→반복)에서 발생하는 **과최적화/오탐/누락** 문제를 잡기 위해, 에이전트 간 교차 검증 루프를 자동화하는 CLI 도구를 만든다. 현재 수동으로 2개 에이전트에 복붙하는 과정을 `cross-eval run` 한 줄로 대체한다.

## 핵심 설계 결정

**에이전트가 코드베이스를 직접 탐색한다** — `claude -p`는 non-interactive지만 내장 도구(Read, Glob, Grep)는 사용 가능. 파일 내용을 프롬프트에 전부 넣는 대신, 에이전트가 프로젝트 디렉토리에서 직접 파일을 탐색하도록 한다.
- Generator: `--permission-mode auto` (파일 읽기/쓰기 가능)
- Reviewer: `--permission-mode plan` (읽기 전용 탐색)
- subprocess의 `cwd`를 현재 작업 디렉토리로 설정
- 기본 실행 모드는 **direct mode**다. 즉 agentic coder도 현재 작업트리에서 직접 수정한다.
- `--worktree` 또는 `use_worktree: true`를 명시한 경우에만 isolated git worktree를 생성한다.

## 사용자 경험 (UX Flow)

```bash
# 1. 프로젝트 초기화
cd my-project
cross-eval init
# → cross-eval.yaml, plan.md, checklist.md 생성

# 2. plan.md, checklist.md 작성 후 실행
cross-eval run

# 3. 옵션들
cross-eval run --config custom.yaml --max-iter 5 --dry-run
cross-eval run --input plan=./docs/spec.md --input checklist=./docs/checks.md

# 4. 결과 확인
ls output/v1/ v2/ final-report.md
```

## 설정 파일 형식 (`cross-eval.yaml`)

```yaml
output_dir: output
use_worktree: false
max_iterations: 3

inputs:
  plan: plan.md
  checklist: checklist.md

agents:
  coder:
    command: claude
    args: ["-p", "--model", "sonnet", "--permission-mode", "auto"]
    system_prompt: "You are a senior software engineer. Follow the plan precisely."
  reviewer:
    command: claude
    args: ["-p", "--model", "opus", "--permission-mode", "plan"]
    system_prompt: "You are a meticulous code reviewer."

# 방법 1: 프리셋 사용 (사용자가 pipeline YAML 직접 작성할 필요 없음)
pipeline: preset:coding-plan-review   # "문서 기반 구현 → 코드/문서 리뷰 → 수정 → 재검증" (기본값)
# pipeline: preset:plan-review        # "구현 전 문서 리뷰 → 수정 → 재검증 반복"

# 방법 2: 직접 커스텀 (고급 사용자용)
# pipeline:
#   - name: coding
#     agent: coder
#     role: coding
#     prompt_template: "default:coding"
#     output_key: coding_output
#   - name: review
#     agent: reviewer
#     role: review
#     prompt_template: "default:review"
#     output_key: review_result
#     verdict: true
```

### 파이프라인 프리셋

| 프리셋 | 설명 | 자동 생성되는 steps |
|--------|------|-------------------|
| `plan-review` | 구현 전 문서 리뷰/수정/재검증 반복 | plan_review_* → aggregate_review → plan_fix → verify |
| `coding-plan-review` | 문서 기반 구현 후 코드/문서 리뷰/수정 반복 | initial_coding(coding) → coding_plan_review(review* → aggregate → coding_plan_fix → verify) |

프리셋은 내부적으로 적절한 pipeline steps + context_override를 자동 구성한다. agents에 정의된 순서대로 agent1, agent2가 배정된다. 프리셋이 불충분하면 직접 steps를 작성할 수 있다.

## 모듈 구조 및 구현 순서

```
cross_eval/
├── __init__.py       (exists)
├── models.py         # 1. 모든 데이터클래스
├── config.py         # 2. YAML 로딩 + 검증
├── prompts.py        # 3. 프롬프트 템플릿
├── agent.py          # 4. subprocess 에이전트 호출
├── pipeline.py       # 5. 핵심 반복 루프
├── report.py         # 6. 마크다운 리포트
└── cli.py            # 7. argparse (init, run)
```

### 모듈별 핵심 내용

**models.py** — 순환 참조 방지, 모든 데이터클래스 집중:
- `AgentConfig` (command, args, system_prompt, stdin_mode)
- `StepConfig` (name, agent, role, prompt_template, output_key, verdict, verdict_pattern, context_override)
- `PipelineConfig` (output_dir, use_worktree, max_iterations, inputs, agents, pipeline)
- `AgentResult` (output, exit_code, agent_name, step_name, duration_seconds)
- `IterationResult` (iteration, step_outputs, verdict, feedback)
- `PipelineResult` (iterations, final_verdict, total_duration)

**config.py** — YAML → PipelineConfig + 검증:
- step.agent가 agents에 정의되어 있는지
- output_key 중복 없는지
- input 파일 존재 여부
- verdict_pattern 유효한 정규식인지

**prompts.py** — 기본 프롬프트 2종 + 파이프라인 프리셋 정의:
- `default:coding` — "기획서에 명시된 것만 구현하라, 과최적화 금지" + plan/checklist/feedback + **"프로젝트 디렉토리의 기존 코드를 탐색하여 컨텍스트를 파악하라"** 지시
- `default:review` — 과최적화/오탐/누락 3기준 검토 + `VERDICT: PASS|FAIL` 출력 + **"프로젝트 디렉토리를 직접 탐색하여 코드를 검증하라"** 지시
- `{variable}` 플레이스홀더, 누락 시 `(no {key} provided)` 출력
- 사용자가 커스텀 .md 파일로 오버라이드 가능
- `PIPELINE_PRESETS` / `PHASED_PRESETS` dict: `plan-review`, `coding-plan-review` 프리셋별 StepConfig/PhaseConfig 정의

**agent.py** — `invoke_agent(agent_config, prompt, cwd)`:
- `cwd` 파라미터로 프로젝트 디렉토리 지정 → 에이전트가 해당 디렉토리에서 파일 탐색 가능
- `stdin_mode=false`: prompt를 마지막 인자로 전달
- `stdin_mode=true`: stdin으로 파이프 (긴 프롬프트용)
- command가 "claude"이고 system_prompt 있으면 `--system-prompt` 자동 주입
- timeout 600초, 비정상 종료 시 RuntimeError

**pipeline.py** — 핵심 루프:
```
for iteration 1..max_iterations:
  for step in pipeline:
    1. 템플릿 resolve → context 구성 (inputs + 이전 step 출력 + feedback)
    2. context_override 적용 (교차 리뷰용 변수 매핑)
    3. 에이전트 호출 (cwd=현재 작업 디렉토리)
    4. output_dir/v{i}/{step.name}.md 저장
    5. verdict step이면 PASS/FAIL 판정
  PASS면 종료, FAIL이면 review 결과를 feedback으로 다음 반복
final-report.md 생성
```

agentic 실행 경로는 두 모드가 있다.
- 기본: direct mode (`cwd`에서 직접 수정)
- opt-in: isolated worktree mode (`--worktree` 또는 `use_worktree: true`)

**report.py** — 최종 마크다운 리포트:
- 요약 테이블 (반복 횟수, 판정, 소요시간)
- 반복별 상세 (각 step 출력, 에이전트명, 소요시간)
- 최종 판정

**cli.py** — 서브커맨드:
- `cross-eval init [--dir .] [--preset coding-plan-review|plan-review]` — 스캐폴딩 (기존 파일 안 덮어씀)
- `cross-eval run [-c config] [--max-iter N] [--dry-run] [--output-dir path] [--input key=path ...] [--worktree]`
- `--input key=path`: config의 inputs 오버라이드/추가
- `--dry-run`: 에이전트 호출 없이 렌더링된 프롬프트만 출력
- `--worktree`: 기본 direct mode 대신 isolated git worktree에서 실행

## 수정할 파일 목록

| 파일 | 작업 |
|------|------|
| `cross_eval/__init__.py` | 이미 존재, 수정 없음 |
| `cross_eval/models.py` | **신규 생성** |
| `cross_eval/config.py` | **신규 생성** |
| `cross_eval/prompts.py` | **신규 생성** |
| `cross_eval/agent.py` | **신규 생성** |
| `cross_eval/pipeline.py` | **신규 생성** |
| `cross_eval/report.py` | **신규 생성** |
| `cross_eval/cli.py` | **신규 생성** |
| `pyproject.toml` | 이미 존재, 수정 없음 |

## 검증 방법

1. `pip install -e .` 로 로컬 설치
2. `cross-eval init` 로 스캐폴딩 확인 (3개 파일 생성)
3. `cross-eval run --dry-run` 로 프롬프트 렌더링 확인 (에이전트 호출 없이)
4. plan.md/checklist.md에 간단한 내용 넣고 `cross-eval run --max-iter 2` 로 실제 실행
5. `output/` 디렉토리에 v1/, final-report.md 생성 확인

`--dry-run` 은 미리보기 전용이며 실제 verdict가 PASS가 아니어도 프로세스 종료 코드는 `0`으로 처리한다.


  cross-eval run \
    --docs /Users/chungyeong/Desktop/Dev/new-alpha-foundry/plans/TO_CLICKHOUSE \
    --preset coding-plan-review \
    --coder claude \
    --reviewer codex \
    --reviewer codex \
    --reviewer codex \
    --senior codex \
    --coder-effort high \
    --reviewer-effort high \
    --senior-effort xhigh \
    --max-iter 10


cross-eval run --plan /Users/chungyeong/Desktop/Dev/cross-eval/UX_IMPROVEMENT_PLAN.md --coder claude --reviewer claude --senior claude --model sonnet --preset coding-plan-review --lang ko --max-iter 1