continue

DEVELOPMENT.md

@@ -10,6 +10,8 @@ AI 에이전트 2개를 활용한 개발 워크플로우(기획→체크리스
 - Generator: `--permission-mode auto` (파일 읽기/쓰기 가능)
 - Reviewer: `--permission-mode plan` (읽기 전용 탐색)
 - subprocess의 `cwd`를 현재 작업 디렉토리로 설정
+- 기본 실행 모드는 **direct mode**다. 즉 agentic coder도 현재 작업트리에서 직접 수정한다.
+- `--worktree` 또는 `use_worktree: true`를 명시한 경우에만 isolated git worktree를 생성한다.
 
 ## 사용자 경험 (UX Flow)
 
@@ -34,6 +36,7 @@ ls output/v1/ v2/ final-report.md
 
 ```yaml
 output_dir: output
+use_worktree: false
 max_iterations: 3
 
 inputs:
@@ -51,10 +54,8 @@ agents:
     system_prompt: "You are a meticulous code reviewer."
 
 # 방법 1: 프리셋 사용 (사용자가 pipeline YAML 직접 작성할 필요 없음)
-pipeline: preset:simple          # "A 생성 → B 리뷰" (기본값)
-# pipeline: preset:cross-review  # "둘 다 생성 → 서로 리뷰"
-# pipeline: preset:plan-review   # "구현 전 문서 리뷰 → 수정 → 재검증 반복"
-# pipeline: preset:coding-review-fix  # "초기 코딩 1회 → 리뷰/수정 반복"
+pipeline: preset:coding-plan-review   # "문서 기반 구현 → 코드/문서 리뷰 → 수정 → 재검증" (기본값)
+# pipeline: preset:plan-review        # "구현 전 문서 리뷰 → 수정 → 재검증 반복"
 
 # 방법 2: 직접 커스텀 (고급 사용자용)
 # pipeline:
@@ -75,10 +76,8 @@ pipeline: preset:simple          # "A 생성 → B 리뷰" (기본값)
 
 | 프리셋 | 설명 | 자동 생성되는 steps |
 |--------|------|-------------------|
-| `simple` | A 코딩 → B 리뷰 | coding(agent1) → review(agent2) |
-| `cross-review` | 둘 다 코딩, 서로 리뷰 | coding_a → coding_b → review_of_b(agent_a) → review_of_a(agent_b) |
 | `plan-review` | 구현 전 문서 리뷰/수정/재검증 반복 | plan_review_* → aggregate_review → plan_fix → verify |
-| `coding-review-fix` | 초기 코딩 후 리뷰/수정 반복 | initial_coding(coding) → review_fix(review* → aggregate → coding → verify) |
+| `coding-plan-review` | 문서 기반 구현 후 코드/문서 리뷰/수정 반복 | initial_coding(coding) → coding_plan_review(review* → aggregate → coding_plan_fix → verify) |
 
 프리셋은 내부적으로 적절한 pipeline steps + context_override를 자동 구성한다. agents에 정의된 순서대로 agent1, agent2가 배정된다. 프리셋이 불충분하면 직접 steps를 작성할 수 있다.
 
@@ -101,7 +100,7 @@ cross_eval/
 **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, max_iterations, inputs, agents, pipeline)
+- `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)
@@ -117,7 +116,7 @@ cross_eval/
 - `default:review` — 과최적화/오탐/누락 3기준 검토 + `VERDICT: PASS|FAIL` 출력 + **"프로젝트 디렉토리를 직접 탐색하여 코드를 검증하라"** 지시
 - `{variable}` 플레이스홀더, 누락 시 `(no {key} provided)` 출력
 - 사용자가 커스텀 .md 파일로 오버라이드 가능
-- `PIPELINE_PRESETS` dict: `simple`, `cross-review`, `plan-review` 등 프리셋별 StepConfig 리스트 정의
+- `PIPELINE_PRESETS` / `PHASED_PRESETS` dict: `plan-review`, `coding-plan-review` 프리셋별 StepConfig/PhaseConfig 정의
 
 **agent.py** — `invoke_agent(agent_config, prompt, cwd)`:
 - `cwd` 파라미터로 프로젝트 디렉토리 지정 → 에이전트가 해당 디렉토리에서 파일 탐색 가능
@@ -139,16 +138,21 @@ for iteration 1..max_iterations:
 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 simple|cross-review|plan-review]` — 스캐폴딩 (기존 파일 안 덮어씀)
-- `cross-eval run [-c config] [--max-iter N] [--dry-run] [--output-dir path] [--input key=path ...]`
+- `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에서 실행
 
 ## 수정할 파일 목록
 
@@ -172,10 +176,12 @@ final-report.md 생성
 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-review-fix \
+    --preset coding-plan-review \
     --coder claude \
     --reviewer codex \
     --reviewer codex \
@@ -187,4 +193,4 @@ final-report.md 생성
     --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-review-fix --lang ko --max-iter 1
+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