# cross-eval

AI 에이전트 간 교차 검증을 자동화하는 CLI 도구.

기획서와 체크리스트를 기반으로 "코딩 → 리뷰 → 피드백 → 재코딩" 루프를 자동으로 돌려서,
**과최적화 / 오탐 / 누락** 문제를 잡아냅니다.

## 설치

```bash
# 1. 저장소 클론
git clone <repository-url>
cd cross-eval

# 2. 설치 (editable 모드 — 코드 수정 시 재설치 불필요)
pip3 install -e .
```

설치 후 터미널 어디서든 `cross-eval` 명령어를 사용할 수 있습니다.

```bash
cross-eval --version
```

### 요구사항

- Python 3.9+
- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) 설치 및 인증 완료

## 사용법

### 1. 프로젝트 초기화

```bash
cd my-project
cross-eval init
```

`.cross-eval/` 폴더 안에 `config.yaml`, `plan-sample.md`, `checklist-sample.md`가 생성됩니다.

### 2. 기획서 작성

샘플 파일을 복사하여 기획서와 체크리스트를 작성합니다.

```bash
cp .cross-eval/plan-sample.md .cross-eval/plan.md
cp .cross-eval/checklist-sample.md .cross-eval/checklist.md
# plan.md, checklist.md 편집
```

### 3. 실행

```bash
# 기본 실행 (현재 작업트리 direct mode, 최대 3회 반복)
cross-eval run

# 프롬프트만 확인 (에이전트 호출 없이, 비용 절약)
cross-eval run --dry-run

# 격리된 git worktree에서 실행하고 싶을 때만 명시
cross-eval run --worktree

# 최대 반복 횟수 변경
cross-eval run --max-iter 5

# 입력 파일 오버라이드
cross-eval run --input plan=./docs/spec.md

# 설정 파일 지정
cross-eval run --config .cross-eval/config.yaml
```

### 4. 결과 확인

```
output/
├── v1/
│   ├── coding.md      # 에이전트 코딩 결과
│   └── review.md      # 에이전트 리뷰 결과
├── v2/
│   ├── coding.md
│   └── review.md
└── final-report.md    # 전체 요약 리포트
```

기본값은 **direct mode**다. 즉 `cross-eval`은 현재 작업트리에서 직접 파일을 읽고 수정한다.
별도 격리 실행이 필요할 때만 `--worktree`를 붙여 isolated git worktree를 사용한다.

## 설정 (`.cross-eval/config.yaml`)

```yaml
output_dir: output
max_iterations: 3
language: ko              # ko 또는 en (프롬프트 템플릿 언어)

inputs:
  plan: plan.md           # config.yaml 기준 상대경로
  checklist: checklist.md

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

pipeline: preset:coding-plan-review
use_worktree: false        # 기본값. true면 isolated worktree 사용
```

실행 중에 `config.yaml`을 수정하면 다음 반복부터 자동으로 반영됩니다.

### 파이프라인 프리셋

| 프리셋 | 설명 |
|--------|------|
| `plan-review` | 구현 전 기획서/체크리스트/참고문서를 검토하고 문서를 수정한 뒤 재검증까지 반복 |
| `coding-plan-review` | 입력 문서를 바탕으로 코드를 구현하고, 코드와 문서를 함께 리뷰/수정/재검증 반복 |

두 프리셋은 역할만 다르고, 대부분의 CLI 옵션은 동일하게 동작한다. 예를 들어 `--plan`, `--checklist`, `--docs`, `--coder`, `--reviewer`, `--senior`, `--max-iter`, `--dry-run`, `--worktree`는 둘 다 같은 방식으로 사용할 수 있다.

```bash
# 초기화 옵션
cross-eval init --preset coding-plan-review  # 구현 + 코드/문서 리뷰 프리셋
cross-eval init --preset plan-review         # 문서 리뷰/수정/재검증 프리셋
cross-eval init --lang en               # 영어 템플릿
```

`cross-eval run --dry-run` 은 프롬프트와 파이프라인 구성을 미리보기만 하며, 실제 판정이 PASS가 아니어도 종료 코드는 `0`이다.