--- name: auto-dev description: Automated development pipeline. Runs a completed Planning Work through Development and Validation phases end-to-end. model: sonnet effort: high --- # Auto-Dev 스킬 Work 파일과 Task 시스템을 통합하여 Development → Validation 파이프라인을 자동 실행합니다. --- ## Step 0: Work 컨텍스트 + Task 시스템 초기화 [건너뛰기 금지] ### 진입 확인 [건너뛰기 금지] Work ID가 제공된 경우, `planning-results.md` 존재 여부 확인: ```bash ls docs/works/active/W-XXX-*/planning-results.md 2>/dev/null \ || ls docs/works/idea/W-XXX-*/planning-results.md 2>/dev/null ``` - **파일 있음** → 계속 - **파일 없음** → "planning-results.md를 찾을 수 없습니다. `/plan-task W-XXX`를 먼저 실행하세요." 출력 후 중단 Work ID 없이 새 요청으로 진입한 경우 (`/auto-dev 로그인 기능 추가` 형식): - `work.sh new`로 Work 생성 후 → **즉시 `/plan-task W-XXX`로 위임** (planning-results.md 없이 Step 1 진행 금지) - 이는 `brainstorming → plan-task → auto-dev` 체인 준수를 위함 Fallback 모드(`docs/works/` 폴더 자체가 없는 경우)에서는 이 확인을 스킵합니다. ### Work ID가 제공된 경우 (예: `/auto-dev W-042`) 1. Work 파일 위치 탐색: `docs/works/idea/` 또는 `docs/works/active/` 2. `W-XXX-{slug}/W-XXX-{slug}.md` 와 `planning-results.md` 읽기 3. frontmatter `status`, `current_phase`, `phases_completed` 확인 **idea 상태면 자동 전환:** ```bash ./scripts/work.sh start W-042 # idea/ → active/ 이동, status: active, started_at 기록 ``` **current_phase에 따른 시작 위치:** | current_phase | 시작 위치 | | ------------- | --------------- | | `planning` | Step 1부터 전체 | | `development` | Step 2부터 재개 | | `validation` | Step 3부터 재개 | ### Work ID가 없는 경우 (예: `/auto-dev 로그인 기능 추가`) `docs/works/` 폴더 존재 여부 확인: - **존재하면** → `work.sh new`로 새 Work 생성 후 Step 1부터 진행: ```bash ./scripts/work.sh new "<요청 제목>" ``` - **없으면** → Step 4 fallback ### Task 시스템 초기화 [건너뛰기 금지] Work ID 확보 후 반드시 실행: 1. `ToolSearch("select:TaskCreate,TaskUpdate,TaskList")` — 스키마 fetch 2. `TaskList` 실행 → subject가 `[W-XXX]`로 시작하는 Task 있으면 상태 확인 후 재개 (재생성 스킵, W-XXX는 현재 Work ID) 3. Task 없으면 → Step 1: Development Tasks 생성으로 이동 --- ## Step 1: Development Tasks 생성 `planning-results.md`의 구현 계획 항목 분석 + **소스코드 직접 탐색**: 1. 구현 계획 항목 목록화 2. 코드베이스 직접 탐색 (에이전트 위임 아님): - 이미 구현된 파일/함수 확인 - 해당 항목은 ✅ 완료로 마킹 (Task 생성 스킵) 3. 미완료 항목만 TaskCreate: **분리 기준:** - 독립적으로 구현 가능한 항목 → 별도 Task (병렬 실행) - 다른 항목에 의존하는 항목 → `addBlockedBy` 설정 **Task 네이밍:** `[W-XXX][Dev] {구현 항목명}` **TaskCreate 시 모든 Task에 metadata 포함:** ```json { "work_id": "W-XXX", "phase": "development" } ``` **예시 구조:** ``` T-dev-1: [W-042][Dev] 데이터 모델 정의 ← 독립 (병렬) T-dev-2: [W-042][Dev] API 엔드포인트 구현 ← blockedBy: T-dev-1 T-dev-3: [W-042][Dev] 프론트엔드 컴포넌트 ← blockedBy: T-dev-1 T-dev-4: [W-042][Dev] 테스트 작성 ← blockedBy: T-dev-2, T-dev-3 ``` `progress.md` Task Map 생성/갱신 (description 컬럼 포함). --- ## Step 2: Development 실행 각 Task를 `implement-code` 에이전트에 위임 (isolation: worktree): **병렬 실행 원칙 (스케일별 — Spec 2 / W-006):** blockedBy 없는 Task가 2개 이상이면 동일 응답에서 동시 dispatch: ``` Agent(task_A) ─┐ Agent(task_B) ─┼─ 동일 응답에서 동시 dispatch Agent(task_C) ─┘ ``` **dispatch 전 파일 소유권 확인 (rules/parallel-worktree.md) [건너뛰기 금지]:** 병렬 안전은 병합 직렬화가 아니라 **dispatch 시점의 파일 분리**로 확보한다(메인은 서브에이전트의 ExitWorktree 타이밍을 직렬화할 수 없다). 따라서: 1. 병렬 청크의 수정 대상 파일이 disjoint한지 확인한다. disjoint하면 각 에이전트가 언제 복귀하든 트리 충돌이 없다. 2. 겹침을 피할 수 없으면 해당 청크들을 **순차 dispatch**로 강등한다(하나 dispatch → ExitWorktree까지 완료 확인 → 다음). 의존성 상류(공유 타입/유틸) 청크를 먼저. 3. 공유 파일(설정·배럴 export·라우트 등록부)은 병렬 청크에 배정하지 않고 마지막에 메인 세션이 단독 수정한다. **Worktree 복귀 (병렬 dispatch 후):** - 각 에이전트가 worktree 안 검증(린트+관련 테스트) 그린 후 **스스로** `ExitWorktree`로 복귀한다(각 에이전트 본문 "Worktree 복귀 프로토콜"). disjoint 전제가 지켜지면 동시 복귀도 안전하다. - 병합 충돌 발생 시(전제가 깨진 경우): 임의 해결 금지 → `git-workflow`에 위임해 충돌 파일/내용 보고 + NEED_USER_INPUT(ours/theirs/manual) 에스컬레이션. - 같은 지점 충돌 2회 반복 = 청크 분해 오류 → 남은 dispatch 중단, plan 단계로 돌아가 청크 경계(파일 소유권)를 재설계한다. **Large 라우팅:** Work `size: Large`이고 unblocked 병렬 청크가 **10개 이상**이면, 스킬 주도 dispatch는 main 컨텍스트에 부담이 큽니다. 이 경우 청크 목록을 정리해 사용자에게 네이티브 `ultracode`(dynamic workflow) 트리거를 안내하세요 (`ultracode`는 대화형 전용 — 스킬에서 자동 트리거 불가). 10개 미만이면 현행 dispatch. **Task 완료 시 매번 의무:** 1. `TaskUpdate(id, status="completed")` 2. `progress.md` Task Map: 해당 행 상태 ✅로 수정 3. `progress.md` Task 업데이트 로그에 완료 시각 기록 4. Work frontmatter `updated_at` 갱신 5. `TaskList`로 unblocked Task 확인 → 즉시 실행 **Durable executor 규율 (W-013 — 장기·다세션 실행):** - **미완 1항목/iteration**: 한 iteration은 checklist 미완 항목 **하나**만 목표로 한다 (한 번에 다수 항목을 "완료"로 몰아 찍지 않는다 — 검증 없는 일괄 통과 방지). - **verify 통과 전 passes 금지**: `checklist.json`의 `passes:true`는 오직 `./scripts/checklist.sh pass `가 항목의 `verify` 명령을 **실제 실행해 exit 0**일 때만 전환된다. 모델 판단으로 completed를 self-mark하지 않는다. - **상태 쓰기는 메인 세션 소유**: `checklist.json`·`progress.md` 쓰기는 **메인 세션**만 수행한다. worktree subagent는 코드만 변경하고 상태 파일은 건드리지 않는다 (`rules/parallel-worktree.md` 병합 충돌 해소 — 상태는 단일 writer). 모든 Dev Task 완료 후: ```bash ./scripts/work.sh next-phase W-042 # current_phase: development → validation # phases_completed에 development 추가 ``` --- ## Step 3: Validation Tasks 생성 및 실행 Dev 완료 직후 Validation을 3단계로 실행합니다: ``` T-spec (스펙 준수 확인, 단독 선행) ↓ 통과 후 T-review + T-security (병렬) ↓ 완료 후 T-merge (결과 통합) ``` ### T-spec: 스펙 준수 확인 (선행 실행) Task 생성: ``` T-spec: [W-XXX][Validation/C] 스펙 준수 확인 — blockedBy: 모든 Dev Tasks ``` TaskCreate 시 metadata: ```json { "work_id": "W-XXX", "phase": "validation" } ``` **T-spec 실행 내용:** 1. `planning-results.md`의 `## 구현 계획` 항목 목록화 2. 실제 변경된 코드(`git diff` 또는 worktree 변경 파일)와 대조: - 모든 항목 구현 확인 → T-review + T-security 병렬 실행으로 진행 - 누락/불일치 항목 발견 → **T-spec 실패 흐름** 실행 **T-spec 실패 흐름:** 1. 누락/불일치 항목 목록을 사용자에게 보고 2. 누락 항목에 대한 추가 Dev Task만 생성 (기존 완료 Task 유지) 3. 추가 Dev Task 완료 후 T-spec 재실행 4. **최대 2회 재시도** — 초과 시 사용자에게 판단 요청 후 파이프라인 중단 T-spec 통과 후 아래 T-review, T-security를 동시 생성 후 **병렬 실행**: ``` T-review: [W-042][Validation/A] 코드 리뷰 — blockedBy: T-spec T-security: [W-042][Validation/B] 보안 스캔 — blockedBy: T-spec ``` TaskCreate 시 metadata: ```json { "work_id": "W-XXX", "phase": "validation" } ``` **병렬 실행:** - `T-review` → `review-code` 에이전트 - `T-security` → `security-scan` 에이전트 두 Task 모두 완료 후 결과 통합 Task 생성: ``` T-merge: [W-042][Validation] 결과 통합 — blockedBy: T-review, T-security ``` ### Feedback ledger 캡처 (Spec 3 / W-007) [건너뛰기 금지] review-code/security-scan 결과에 **발견된 결함이 있으면(pass·fail 무관)** 각 결함을 정규화해 ledger에 upsert합니다. 같은 실수를 다음 작업에서 사전 차단하는 학습 루프입니다. ```bash # category ∈ {lint, security, architecture, test, convention} # severity ∈ {critical, high, medium, low} # (work.sh와 동일한 ./scripts 관례 — CLAUDE_PLUGIN_ROOT 의존 없음) ./scripts/feedback.sh upsert "<결함 요지>" ``` - 발견된 결함만 기록 (통과 시 회피 패턴은 노이즈라 기록 안 함) - ledger 로직(상한·중복제거·감쇠)은 헬퍼가 보장 — 직접 테이블 편집 금지 - 다음 세션 session-start가 상위 빈도 교훈을 `=== LESSONS ===`로 주입 ### T-merge 판정 기준 [건너뛰기 금지] #### Iron Law — 완료 주장 전 필수 실행 ``` 완료를 주장하기 전: 1. 어떤 명령이 이 주장을 증명하는가? 2. 지금 그 명령을 실행한다 (fresh run) 3. 출력 전체를 읽는다 4. 출력이 주장을 확인하는가? → NO: 실제 상태를 증거와 함께 보고 → YES: 증거와 함께 주장 명령을 실행하지 않고 완료를 주장하는 것은 오류다. ``` T-review, T-security 결과를 구조적으로 검증: - review-code `decision` 필드 == `ACCEPT` 인가? - review-code `critical_count` == 0, `high_count` == 0 인가? - security-scan 결과에 CRITICAL/HIGH == 0 인가? → 모두 충족 시에만 `T-merge` 실행 ("이슈 없음" 판정) → 하나라도 미충족 시 이슈 목록과 권고사항을 사용자에게 보고, 파이프라인 중단 `T-merge` 실행: 0. **[Guard]** 판정 기준 미충족 시: 미충족 항목 + 이슈 목록 + 권고사항을 사용자에게 보고하고 파이프라인을 중단한다. `TaskUpdate(T-merge, status="failed")`. 아래 단계를 실행하지 않는다. 1. **검증 마커 생성** — Stop hook 이중 검증 방지: ```bash python3 - <<'PY' # 지문 계산의 단일 소스 = stop-validator.py의 _worktree_state_hash(). # 과거엔 이 스니펫이 같은 로직을 복제했고(MUST MATCH 산문 계약), 예외절·타임아웃이 # 침묵 드리프트했다(재감사 R2/ATK-002) — 이제 훅 모듈을 직접 로드해 호출한다. import importlib.util, os, subprocess, tempfile root = subprocess.run(["git","rev-parse","--show-toplevel"], capture_output=True, text=True, timeout=10).stdout.strip() or os.getcwd() sv_path = os.path.join(root, "plugins/common/hooks/stop-validator.py") if not os.path.isfile(sv_path): # 플러그인 설치 환경 폴백 sv_path = os.path.join(os.environ.get("CLAUDE_PLUGIN_ROOT",""), "hooks/stop-validator.py") spec = importlib.util.spec_from_file_location("stop_validator", sv_path) sv = importlib.util.module_from_spec(spec); spec.loader.exec_module(sv) state = sv._worktree_state_hash() marker = str(sv.VALIDATED_MARKER) # 경로·키 계산도 훅과 단일 소스 d = os.path.dirname(marker) os.makedirs(d, mode=0o700, exist_ok=True) fd, tmp = tempfile.mkstemp(dir=d) with os.fdopen(fd, "w") as fh: fh.write(state) os.replace(tmp, marker) # rename은 심링크 자체를 교체(CWE-59) PY ``` > 마커에는 **검증 스코프 지문**(HEAD + 검증 대상 .py들의 내용 sha256)을 기록하고 > 사용자별 `$TMPDIR/claude-{uid}`(0700)에 둔다. Stop hook은 이름이 아니라 이 > 내용으로 판정한다. 지문/마커명 계산은 stop-validator 모듈 호출로 **물리적으로 > 단일 소스** — 복제 로직 드리프트가 원천 차단된다. 2. T-review, T-security 결과를 `review-results.md`에 통합 기록 3. `TaskUpdate(T-merge, status="completed")` + `TaskList`로 이번 Work의 잔존 in_progress/pending 태스크가 없는지 확인해 정리한다. (T-merge = 검증 **결과 통합** 태스크 — 브랜치 머지가 아니다. 머지 여부는 옵션 선택 후 Work status가 추적한다.) **반드시 사용자 보고(다음 단계)보다 먼저** — 단발 실행에선 보고 후 턴이 사용자 입력 대기로 끝나 마킹이 증발한다(태스크 잔존 버그의 근원). 배치 모드(Step 5)에선 턴이 안 끝나지만 마킹-우선 순서는 동일하게 적용한다. 마킹 규율의 SSOT는 `rules/definition-of-done.md#Task-마감-규율`. 4. 사용자에게 완료 보고 후 브랜치 처리 옵션 제시: ``` W-XXX Validation 통과. 다음 단계를 선택하세요: 1. 로컬 머지 (현재 브랜치 → main) 2. PR 생성 3. 코드 리뷰 먼저 (`/review`) 4. 브랜치 유지 (나중에 처리) ``` 옵션별 Work 상태 처리: - **옵션 1 (로컬 머지):** 머지 완료 후 `./scripts/work.sh complete W-XXX` 실행 - **옵션 2 (PR 생성):** `gh pr create` 후 Work 상태 active 유지 — PR 머지 확인 후 `work.sh complete` - **옵션 3 (코드 리뷰):** `/review` 실행 후 결과에 따라 옵션 1 또는 2 선택 - **옵션 4 (브랜치 유지):** Work 상태 active 유지, progress.md에 "Validation 통과" 메모 기록 --- ## Step 5: 배치 모드 — 자율 완주 (Spec 5 / W-009) [opt-in] 여러 Work가 계획되어 배치로 실행 요청된 경우(예: `/auto-dev W-005 W-006 W-007`, 또는 "계획한 Work 전부 진행"), **설계 게이트 통과 후에는 P0·완료·가드 전까지 멈추지 않고** 자율 완주합니다. (Loop Engineering — `rules/loop-engineering.md`) ``` 배치 드라이버 (검증된 Task 시스템 + 스킬 루프, 자체 데몬 없음): while (미완료 Work 존재): 1. 의존성(Depends on) 충족된 unblocked Work 선택 2. 해당 Work에 Step 0~3 (Development → Validation) 실행 3. validation 통과 → progress.md 래칫 → work.sh complete 4. 종료 가드 점검 → 다음 Work로 사람 확인 없이 전진 → 배치 완료 보고 ``` **종료 가드 (필수):** - P0 모호함 → 즉시 `AskUserQuestion`, 루프 탈출 - validation 실패가 continueOnBlock 재시도 후에도 잔존 → 보고 후 해당 Work 정지 - 동일 Work에서 진전 없는 반복(2회+) → 에스컬레이션 - 배치 전체 완료 → 종합 보고 **단발 실행**(`/auto-dev W-XXX` 단일)은 기존 동작 유지 — 배치 드라이버 미발동. --- ## Fallback: Work 시스템 없는 경우 `docs/works/` 폴더가 없거나 Work ID 없이 요청된 경우: Work 관련 작업(상태 전환, progress.md, decisions.md) 전부 생략하고 파이프라인만 실행: 1. **탐색**: 코드베이스 파악 (직접 탐색) 2. **계획**: 구현 계획 수립 (`plan-implementation` 에이전트) 3. **구현**: 코드 작성 (`implement-code` 에이전트, isolation: worktree) 4. **테스트**: 테스트 작성 (`write-tests` 에이전트) 5. **검증**: 코드 리뷰 + 보안 스캔 (병렬) 6. **보고**: 결과를 대화창에 출력 --- ## 참고 문서 | 문서 | 경로 | | ----------------- | ------------------------------------------------- | | Work 시스템 전체 | `plugins/common/skills/references/work-system.md` | | Planning 프로토콜 | `plugins/common/rules/planning-protocol.md` |