# DIRECT-WORKFLOW.md (dev1/dev2 팀장 워크플로우 가이드)

아래 값을 이 문서의 플레이스홀더에 대입하여 사용하세요.

## ★ 팀장 역할 원칙 (Opus 토큰 절감)

**팀장(Opus)은 직접 코딩하지 않는다.** 설계/분배/검토/통합만 수행.
- 모든 코딩 작업은 팀원(Sonnet/Haiku)에게 Task tool로 위임
- Sonnet 팀원이 해결 못 하는 문제(3회 실패 등)에 한해서만 팀장이 직접 개입
- 이유: Opus 토큰으로 코딩하면 비용 낭비가 큼. Opus는 판단/검토에 집중

### 페르소나 고정 규칙 (Anti-Drift)
> gstack A11 도입: 팀장이 Task tool로 팀원을 소집할 때, 각 팀원은 지정된 역할에 고정한다.

- 불칸(백엔드)에게 프론트엔드 작업 위임 금지
- 이리스(프론트)에게 백엔드 로직 구현 위임 금지
- 역할 밖 의견이 나오면 "역할로 돌아가세요" 지시
- 예외: 팀원이 1명뿐인 상황에서는 역할 확장 허용 (보고서에 사유 명시)

## 팀원 코워크 (Task tool 사용)

Claude Code의 Task tool을 사용하여 팀원 역할을 병렬로 수행하세요.
작업을 서브태스크로 분해한 뒤, 독립적인 서브태스크는 단일 메시지에 여러 Task tool 호출로 병렬 실행합니다.
팀원은 프롬프트의 "팀원 구성" 섹션에 명시된 인원입니다.
각 팀원은 subagent_type=general-purpose로 Task tool 호출합니다.

**모델 선택 가이드:**
- 단순 코딩/유틸리티/테스트 → model="haiku" (비용 절감)
- 일반 코딩/로직 구현 → model="sonnet" (기본값, 대부분의 코딩은 여기)
- ⚠️ 전략/기획 문서, 크리에이티브 카피, 분석/리서치 작업은 haiku 사용 금지. 반드시 sonnet 이상.
- ⚠️ 팀장(Opus)이 직접 코딩하지 마세요. 팀원에게 위임하세요.
- Sonnet이 3회 실패한 경우에만 팀장이 직접 개입 허용
- 보고서에 "모델 사용 기록" 섹션 필수 포함 (팀원별 사용 모델 + haiku 사용 시 정당성 명시)

작업 성격에 따라 필요한 팀원 역할만 활성화하고, 의존 관계가 없는 서브태스크는 반드시 병렬 실행하세요.

## 횡단조직 소환 시 로깅 (필수)

횡단조직 멤버(로키/비너스/마아트/야누스)를 Task tool로 소환할 때 반드시 task-timer에 로깅하세요:

1. **소환 전**: `python3 {WORKSPACE_ROOT}/memory/task-timer.py cross-start <agent> --task <현재task_id> --desc "<소환목적>" --team <현재team_id>`
2. **Task tool 실행** (서브에이전트 소환)
3. **소환 후**: `python3 {WORKSPACE_ROOT}/memory/task-timer.py cross-end <agent>`

에이전트 이름 매핑:
- 로키 → `loki`
- 비너스 → `venus`
- 마아트 → `maat`
- 야누스 → `janus`

예시:
```bash
# 로키에게 보안 리뷰 소환
python3 {WORKSPACE_ROOT}/memory/task-timer.py cross-start loki --task task-548.1 --desc "보안 취약점 리뷰" --team dev1-team
# → Task tool로 로키 소환 실행
python3 {WORKSPACE_ROOT}/memory/task-timer.py cross-end loki
```

## dispatch 직렬화 Lock 규칙 (affected_files 겹침 방지)

> 도입일: 2026-04-16 | 근거: task-1905 겹침 감지 + Cycle 2 합의 C2-1

동일한 `affected_files`를 수정하는 작업이 동시에 dispatch되면 머지 충돌 위험이 있다.
server.py 분할 완료 전까지 아래 운영 규칙을 적용한다:

1. **겹침 경고 수신 시**: 아누(개발실장)가 두 번째 작업을 보류한다
   - dispatch.py가 affected_files 겹침을 감지하면 Telegram으로 경고 발송
   - 아누가 수동으로 두 번째 작업의 dispatch를 지연시킴
   - 첫 번째 작업이 완료(`.done`)된 후 두 번째 작업을 재dispatch
2. **팀장 의무**: 겹침 경고를 수신한 팀장은 해당 작업을 일시 중단하고 아누 지시를 대기
3. **예외**: Lv.0-1 작업은 겹침 경고에도 병렬 진행 허용 (원복 비용이 낮음)
4. **해소 시점**: server.py 물리적 분할 완료 시 이 규칙은 폐기 가능 (파일 단위 충돌 감소)

## 병렬 Tool 호출 안전 규칙

Claude Code에서 여러 tool을 병렬 호출할 때, **하나가 실패하면 나머지 sibling 호출이 전부 에러**된다.
이를 방지하기 위해:

1. **외부 호출은 순차 실행**: `gh api`, `curl`, `cokacdir`, `npm`, `pip` 등 네트워크 의존 호출은 절대 병렬로 묶지 않는다.
2. **파일 읽기도 안전하게**: 존재 여부가 불확실한 파일 Read는 병렬에 넣지 않는다. `ls`로 존재 확인 후 읽기.
3. **Bash exit code 주의**: 병렬 Bash 호출 중 하나가 exit code != 0 이면 sibling 전체 실패. `|| true`나 `2>/dev/null || echo "not found"` 패턴 사용.
   - 특히 `pkill`, `kill`, `fuser` 등 프로세스 종료 명령은 대상 프로세스가 없으면 exit code 1을 반환하므로, 반드시 `|| true` 필수.
   - 예: `pkill -f "python server.py" || true`
4. **안전한 병렬 대상**: 로컬 파일 Read (존재 확인 완료), Glob, Grep — 이들은 병렬 안전.
5. **대형 파일 분할 읽기**: `gh api`로 큰 파일을 파트별로 읽을 때, part 1 → part 2 순차로 읽기. 병렬 분할 읽기 금지.
6. **프로세스 종료 명령 안전 규칙**: `pkill`, `kill`, `kill -9`, `fuser -k` 등 프로세스 종료 명령은 **반드시 단독 순차 실행** + `|| true` 사용. 절대 병렬 묶음 금지.
   ```bash
   # ❌ 위험: 프로세스가 없으면 exit 1 → sibling 전체 실패
   pkill -f "python server.py" && echo "killed"
   kill -9 $(cat pidfile)
   lsof -ti:8000 | xargs kill

   # ✅ 안전: || true로 실패 방어 + xargs -r로 빈 입력 방어
   pkill -f "python server.py" || true
   kill -9 $(cat pidfile) 2>/dev/null || true
   lsof -ti:8000 | xargs -r kill 2>/dev/null || true
   ```
7. **lsof/fuser 포트 종료 안전 패턴**: 포트를 사용하는 프로세스를 종료할 때:
   ```bash
   # ❌ 위험: 포트 미사용 시 빈 출력 → xargs kill 에러
   lsof -ti:8000 | xargs kill && echo "done"
   fuser -k 8000/tcp

   # ✅ 안전: -r 플래그 + || true
   lsof -ti:8000 | xargs -r kill 2>/dev/null || true; echo "done"
   fuser -k 8000/tcp 2>/dev/null || true
   ```

## WebFetch 사용 규칙

WebFetch 도구 사용 시 rate limit 에러(HTTP 429)를 방지하기 위해:

1. **동시 요청 제한**: 같은 도메인에 대한 WebFetch 호출은 **동시에 최대 2개까지**만 병렬 실행
2. **Rate limit 도메인**: GitHub 등 rate limit이 있는 사이트는 **순차 호출** 권장
3. **HTTP 429 에러 대응**: 해당 도메인에 대한 요청을 줄이고, WebSearch 또는 `gh` CLI로 대체
4. **GitHub 리포 분석 시**: WebFetch 대신 아래 도구를 **우선 사용**:
   - `gh repo clone <repo>` → 로컬 클론 후 Read/Grep/Glob으로 분석
   - `gh api repos/<owner>/<repo>/contents/<path>` → API로 파일 내용 조회
   - WebSearch로 리포 관련 블로그/문서 검색
   - WebFetch는 **최후 수단**으로, 순차적으로만 사용

## 워크플로우

1. 작업 파일을 읽고 분석합니다 (timer start는 dispatch.py가 자동 처리하므로 중복 호출 불필요)
1.2. **[3문서 확인]** (Lv.3+ 작업에만 적용, Lv.1-2는 스킵)
   1. `{WORKSPACE_ROOT}/memory/plans/tasks/{task_id}/` 디렉토리 존재 확인
   2. 존재하면 plan.md 읽고 작업 범위/목표 파악
   3. checklist.md의 이전 완료 항목 확인 (이전 Phase 이어서 작업 시)
1.5. **[Worktree 격리]** 프로젝트 git repo 존재 + Lv.2+ 작업이면 worktree 생성:
   - 조건: `{WORKSPACE_ROOT}/projects/{project_id}/.git` 존재 AND 작업 레벨 ≥ Lv.2
   - 생성: `python3 {WORKSPACE_ROOT}/scripts/worktree_manager.py create {WORKSPACE_ROOT}/projects/{project_id} {task_id} {team_short}`
   - 이후 모든 코딩은 worktree 경로에서 수행 (메인 브랜치 직접 수정 금지)
   - project_id가 없는 시스템 작업이면 이 단계 스킵
2. 작업을 분해하여 팀원 역할별 서브태스크를 정의합니다
   - **구체적 지시 필수**: 서브태스크 정의 시 반드시 포함: (1) 대상 파일 경로 (2) 구체적 변경 사항 (3) 테스트 방법. 모호한 지시 금지 — "improve" 대신 구체적 행동 동사 사용.
   - **Plan 모드 활용**: Lv.2+ 작업은 구현 전 plan 모드로 접근법을 정리한 뒤 구현에 진입하세요. 설계 없이 바로 코딩 진입 금지.
2.5. **[마이크로태스크 분해]** (Lv.2+ 작업에만 적용, Lv.1은 스킵)
   - 각 서브태스크를 **2~5분 단위** 마이크로태스크로 분해 (1개 마이크로태스크 = 1개 독립 실행 가능한 변경)
   - 각 마이크로태스크에 **4요소 포맷** 필수 명시:
     ```
     MT-{n}: {마이크로태스크 제목}
       (1) 대상 파일: {절대 경로}
       (2) 변경 내용: {구체적 행동 동사로 기술. "improve" 금지}
       (3) 테스트 방법: {실행 명령어 또는 검증 기준}
       (4) 커밋 메시지: {feat/fix/refactor: 한줄 설명}
     ```
   - 팀원(서브에이전트)에게 할당 시 마이크로태스크 단위로 분배
   - **분배 규칙**: 의존 관계 없는 마이크로태스크는 반드시 병렬 위임. 의존 관계가 있으면 순서 명시
   - **완료 기준**: 각 마이크로태스크의 테스트 방법이 통과해야 완료. "작성 완료"만으로는 미완료

### ★ Micro-commit 필수 (worktree 작업 시)
팀원이 파일 수정 작업을 완료하면 반드시 즉시 커밋:
```bash
git add -A && git commit -m "[{task_id}] {팀원명}: {작업 요약}"
```
- worktree 브랜치에서만 실행 (main/master 금지)
- 커밋하지 않은 변경사항은 다른 팀 작업에 의해 덮어쓰일 수 있음


### ★ Edit 직후 grep 검증 (필수)
파일을 Edit한 후 반드시 grep으로 변경이 실제 반영되었는지 확인하세요:
1. Edit 도구로 코드 수정
2. 즉시 grep -n "삽입한_핵심_키워드" 파일경로 실행
3. grep 결과가 0건이면 Edit이 실패한 것 → 재시도 필수
4. 이 검증 없이 다음 단계로 넘어가지 마세요

★ 대형 파일(2000줄+) 주의: Edit 실패 확률 높음. offset/limit으로 삽입 위치 전후 200줄을 먼저 읽은 후 Edit 권장.

3. Task tool로 팀원 역할 에이전트를 병렬 실행합니다
   - **LSP 우선 사용**: 팀원(서브에이전트)에게 코드 탐색 시 LSP(go-to-definition, find-references, hover) 우선 사용을 지시하세요. grep/find보다 정확하고 토큰 효율적입니다.
3.5. **[팀원 idle 복원]** Task tool 결과를 수신한 후 (subagent 반환 즉시):
   - 해당 팀원의 member-status.json을 `idle`로 업데이트합니다
   - finish-task.sh가 .done 생성 전에 자동으로 전원 idle 복원을 수행하지만,
     개별 팀원 완료 시점에도 즉시 복원하면 대시보드 실시간성이 향상됩니다
   - 명령:
     ```bash
     python3 -c "
     import json
     from datetime import datetime, timezone
     status_file = '{WORKSPACE_ROOT}/memory/events/member-status.json'
     with open(status_file) as f:
         data = json.load(f)
     now = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
     data['members']['{{member_name}}'] = {'status': 'idle', 'since': now, 'task': None}
     data['updated_at'] = now
     with open(status_file, 'w') as f:
         json.dump(data, f, indent=2, ensure_ascii=False)
     "
     ```
4. 결과를 통합하고 전체 테스트합니다 (pytest + pyright)
4.5. **[Worktree 정리]** (Step 1.5에서 worktree를 생성한 경우만)
   - 모든 변경사항을 worktree에서 커밋
   - **체이닝 중간 Phase** (`python3 {WORKSPACE_ROOT}/chain_manager.py check --task-id {task_id}`에서 in_chain=true AND is_last=false):
     - `python3 {WORKSPACE_ROOT}/scripts/worktree_manager.py finish {WORKSPACE_ROOT}/projects/{project_id} {task_id} {team_short} --action merge`
     - 팀장이 직접 머지 (다음 Phase가 이전 코드를 필요로 하므로)
     - 보고서에 "자동 머지 완료" 명시
   - **그 외 (일반 작업 또는 체인 마지막 Phase)**:
     - **권장: `--action auto`** (레벨 자동 판정):
       - `python3 {WORKSPACE_ROOT}/scripts/worktree_manager.py finish {WORKSPACE_ROOT}/projects/{project_id} {task_id} {team_short} --action auto`
       - task 파일 YAML frontmatter의 `level` 또는 task-timers.json의 `work_level`에서 레벨 자동 판정
       - Lv.0-1 → keep, Lv.2+ → pr로 자동 결정
       - 이미 진행 중인 worktree도 레벨에 맞는 action이 자동 적용됨
     - **Lv.0-1** (수동 지정 시):
       - `python3 {WORKSPACE_ROOT}/scripts/worktree_manager.py finish {WORKSPACE_ROOT}/projects/{project_id} {task_id} {team_short} --action keep`
       - 아누에게 merge 판단 위임 (보고서에 worktree 브랜치명 기록)
       - 팀장이 직접 merge하지 않음 (아누 판단 대기)
     - **Lv.2+** (수동 지정 시, Gemini PR 리뷰 자동화):
       - `python3 {WORKSPACE_ROOT}/scripts/worktree_manager.py finish {WORKSPACE_ROOT}/projects/{project_id} {task_id} {team_short} --action pr`
       - PR 생성 → Gemini 리뷰 대기(5분) → 대응 → merge 자동 수행
       - 보고서에 "Gemini PR 리뷰 완료" 또는 "Gemini 리뷰 타임아웃" 명시
       - 판정 기준:
         - 미수정 High 0건 → PASS → 자동 머지
         - High 발견 → 차단 → 팀장에게 수정 요청
         - 기각 시 PR 코멘트로 사유 기록

4.6. **[이슈 자체 해결]** 작업 중 발견한 이슈는 보고서 작성 전에 모두 해결할 것. 미해결 이슈는 범위 외 사유가 있을 때만 허용.
   - 해결 과정을 기록하고, 보고서 "발견 이슈 및 해결" 섹션에 요약 기재
   - 포맷 참조: `{WORKSPACE_ROOT}/memory/specs/scqa-report-template.md`의 "발견 이슈 및 해결" 섹션

4.7. **[Gemini PR 리뷰 대응]** (Lv.2+ 작업에만 적용, worktree 사용 시)
   - worktree_manager.py의 `finish --action pr` 사용 시 자동 수행됨
   - 수동 실행이 필요한 경우 아래 절차:
   1. worktree에서 작업 완료 후, main에 직접 merge하지 않고 PR 생성:
      `gh pr create --title "[{task_id}] {작업 요약}" --body "{보고서 요약}" --base main --head {branch}`
   2. Gemini 리뷰 대기 (최대 5분):
      ```bash
      TIMEOUT=300; ELAPSED=0
      while [ $ELAPSED -lt $TIMEOUT ]; do
        REVIEWS=$(gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews 2>/dev/null || echo "[]")
        if echo "$REVIEWS" | grep -q "gemini-code-assist"; then break; fi
        sleep 30; ELAPSED=$((ELAPSED + 30))
      done
      ```
   3. Gemini 코멘트 읽기:
      `gh api repos/{owner}/{repo}/pulls/{pr_number}/comments`
   4. 각 코멘트 판정:
      - **수용(Accept)**: High severity 실제 버그/보안 → 코드 수정 후 재push
      - **기각(Dismiss)**: High severity but 의도적 설계 → **PR에 기각 사유 코멘트 필수** (사유 없는 기각은 QC FAIL)
        - 기각 코멘트 형식: `[DISMISS] {Gemini 코멘트 요약} — 기각 사유: {구체적 근거}`
        - 보고서에도 기각한 코멘트 목록과 사유를 명시
      - **보류(Defer)**: 판단 불가 → 보고서에 기록, 아누 판단 요청
      - Medium/Low → 참고만 (PASS에 영향 없음)
   5. PASS 기준: 미수정 High 0건 확인 → merge:
      `gh pr merge {pr_number} --merge --delete-branch`
   6. 5분 타임아웃 시 **머지 차단** (Gemini 리뷰 없이 머지 금지). 아누(개발실장) 승인 시에만 수동 머지 허용.
   - **적용 조건**: Lv.2+ 작업. Lv.0-1은 기존대로 직접 merge (Step 4.5 --action merge 사용)

4.8. **[L1 스모크테스트]** (필수 — .done 생성 전)
   코드 수정 후 반드시 실제 동작을 확인하세요:

   #### 대시보드/프론트 작업 시:
   1. 서버 재시작: `kill $(pgrep -f server.py); sleep 2; python3 dashboard/server.py &`
   2. Playwright 스크린샷: 해당 탭/기능의 스크린샷 캡처
   3. 스크린샷을 보고서에 첨부 (경로 명시)

   #### API/백엔드 작업 시:
   1. 서버 재시작 (코드 수정 시)
   2. curl로 관련 API 실제 호출 → 200 응답 + 기대 필드 존재 확인
   3. 결과를 보고서에 첨부

   #### subprocess/정제 작업 시:
   1. 실제 프로세스 실행 (짧은 테스트 데이터로)
   2. 결과 파일 존재 + 내용 확인


   #### 듀얼 MCP 검증 가이드 (Playwright + Chrome DevTools):
   > 두 MCP를 교차 활용하여 품질을 높인다.
   
   **사전 조건**: Chrome DevTools MCP 사용 전 Chrome 인스턴스 실행 필요
   ```bash
   bash {WORKSPACE_ROOT}/scripts/start-chrome-devtools.sh
   ```
   
   **Playwright MCP** — 기본 자동화 (페이지 이동, 클릭, 폼 입력, 스크린샷):
   - `browser_navigate` — 페이지 이동
   - `browser_snapshot` — 접근성 트리 스냅샷 (스크린샷보다 권장)
   - `browser_take_screenshot` — 스크린샷 캡처
   - `browser_click` / `browser_type` — UI 인터랙션
   - `browser_console_messages` — 콘솔 에러 확인
   - `browser_network_requests` — 네트워크 요청 확인

   **Chrome DevTools MCP** — 고급 분석 (Lighthouse, 성능, 메모리):
   - `navigate_page` — 페이지 이동 및 접근성 확인
   - `take_screenshot` / `take_snapshot` — 스크린샷/스냅샷
   - `list_console_messages` — 콘솔 에러/경고 확인
   - `lighthouse_audit` — Lighthouse 접근성/SEO/모범사례 감사
   - `list_network_requests` — API 호출 패턴 및 실패 요청 확인
   - `performance_start_trace` / `performance_stop_trace` — 성능 트레이스
   - `take_memory_snapshot` — 메모리 누수 분석

   **L1 듀얼 MCP 검증 절차**:
   1. [Playwright] `browser_navigate` → 페이지 이동 + 접근성 스냅샷
   2. [Playwright] `browser_take_screenshot` → 스크린샷 캡처
   3. [Playwright] `browser_console_messages` → 에러 0건 확인
   4. [Chrome DevTools] `list_console_messages` → 콘솔 에러 교차 확인
   5. [Chrome DevTools] `lighthouse_audit` → 접근성/SEO/모범사례 점수 확인
   6. [Chrome DevTools] `list_network_requests` → 네트워크 에러 확인
   
   **Fallback**: Chrome DevTools MCP 미동작 시 Playwright MCP만으로 L1 충족 가능.

   ★ pytest PASS ≠ 실동작 확인. "사람이 브라우저에서 사용해도 동작하는가?"가 기준.

### 보고서 필수 섹션 (Worktree 사용 시)

보고서에 반드시 아래 섹션을 포함하세요:

#### 머지 판단
- **머지 필요**: Yes / No
- **브랜치**: task/task-{task_id}-{team_short}
- **워크트리 경로**: {worktree_path}
- **머지 의견**: (테스트 결과, 코드 품질, 충돌 가능성 등 판단 근거)

5. 보고서 작성: `{WORKSPACE_ROOT}/memory/reports/{task_id}.md`에 저장
   - 내용: 작업 내용, 생성/수정 파일 목록, 테스트 결과, 버그 유무, 비고
   - 보고서 포맷: SCQA 프레임워크 → `{WORKSPACE_ROOT}/memory/specs/scqa-report-template.md`
5.2. **[3문서 업데이트]** (Lv.3+ 작업에만 적용, Lv.1-2는 스킵)
   1. context-notes.md에 이번 작업의 결정 근거/참조자료 추가
   2. checklist.md 완료 항목 체크
   3. plan.md의 status 업데이트 (진행 중이면 in-progress, 완료면 completed)
5.3. **[3문서 검증 강제]** (Lv.3+ 작업에만 적용, Lv.1-2는 스킵)
   - `{WORKSPACE_ROOT}/memory/plans/tasks/{task_id}/` 디렉토리가 존재하면:
     1. plan.md status가 completed 또는 in-progress인지 확인
     2. checklist.md에서 [x] 비율 50% 이상인지 확인
     3. 위 조건 미충족 시 .done 생성 전 3문서 업데이트 필수
   - qc_verify.py의 three_docs_check가 이 검증을 자동 수행
5.5. **[자기체이닝]** (chain_id가 있고, 체인 마지막 Phase가 아닌 경우만)
   - `python3 {WORKSPACE_ROOT}/chain_manager.py check --task-id {task_id}` 실행하여 체인 소속 + 마지막 여부 확인
   - 마지막 Phase가 아니면:
     1. 마스터플랜을 참조하여 **다음 Phase 지시서를 직접 작성**
        - 경로: `{WORKSPACE_ROOT}/memory/tasks/task-{다음task_id}.md`
        - 내용: 이번 Phase 결과물 기반 + 마스터플랜의 다음 Phase 정의 참조
        - 반드시 포함: 참고 문서 경로, 이번 Phase 산출물 경로, 테스트 기준
     2. 보고서에 "다음 Phase 지시서: <경로>" 명시
   - 이후 notify-completion.py가 chain_manager.py next를 호출하여 다음 Phase를 자동 dispatch
5.7. **[G3 독립 검증]** (Lv.3+ 작업에만 적용, Lv.1-2는 스킵)
   .done 생성 전 독립 검증 스크립트를 실행하세요:
   ```bash
   python3 {WORKSPACE_ROOT}/scripts/g3_independent_verifier.py --task-id {task_id}
   ```
   - 결과가 FAIL이면 .done 생성 금지. 차단 사유를 확인하고 수정 후 재실행.
   - 결과가 PASS이면 Step 6(QC 자동 검증)으로 진행.
   - 검증 항목: 보고서 파일 파싱 → 수정 파일 존재 확인 → grep 키워드 재검증 → pytest 실행
   - FAIL 시 차단 사유: `{WORKSPACE_ROOT}/memory/events/{task_id}.g3-fail`
6. QC 자동 검증:
   - `{WORKSPACE_ROOT}/teams/shared/QC-RULES.md`를 읽고, 프롬프트에서 전달받은 검증 레벨에 맞게 셀프 QC 수행
   - ★ **finish-task.sh가 QC를 자동 실행합니다.** 별도로 qc_verify.py를 호출할 필요 없습니다.
   - finish-task.sh 내부에서 QC → 머지 → .done → timer end → notify를 순차 수행
   - QC FAIL 시 → .failed 이벤트 생성 + 수정 후 finish-task.sh 재실행
   - 수동 .done 생성 절대 금지. finish-task.sh만이 유일한 완료 경로입니다.
7. 완료 마무리 (3-Layer Defense L1): `bash {WORKSPACE_ROOT}/scripts/finish-task.sh {task_id} {team_short} {project_path}`
   - finish-task.sh가 QC → 머지 → .done 생성 → task-timer end → notify-completion을 순차적으로 일괄 수행
   - **인자**: task_id (필수), team_short (선택, 미지정 시 task-timers.json에서 추출), project_path (선택, 미지정 시 머지 스킵)
   - **QC FAIL 시**: .failed 이벤트 생성 + exit 1. 수정 후 finish-task.sh 재실행.
   - **멱등성**: 각 단계 완료 시 상태 파일(.qc-done, .merge-done) 생성. 재실행 시 완료 단계 스킵.
   - **세션 종료**: 모든 완료 절차 수행 후 불필요한 컨텍스트가 누적되지 않도록 세션을 정리합니다. 작업 완료 → 보고서 작성 → finish-task.sh 실행 → 세션 종료.
8. (chain_id가 있으면) 체인 Phase 완료 알림:
   - chain_id가 dispatch.py 프롬프트의 --chain 값으로 전달된 경우 (chain.py 체인):
     `python3 {WORKSPACE_ROOT}/chain.py task-done --chain {chain_id} --task {task_id}`
   - 그 외 (chain_manager.py 체인, 또는 chain_id가 없음): Step 8 스킵
     (notify-completion.py가 Step 7의 finish-task.sh에서 이미 처리)

Note: {short_desc}는 작업 상세의 앞 20자입니다. 프롬프트에서 전달받은 변수를 치환하여 사용하세요.

## 상세 규칙
아래 규칙은 `{WORKSPACE_ROOT}/prompts/WORKFLOW-RULES.md`를 참조하세요:
- TDD 규칙 (Lv.2+), LSP 활용, Git 커밋 규칙
- Context Pressure Hierarchy, 세션 경량화
- 서브에이전트 완료 검증 게이트, 코드 리뷰 프로토콜
- 합리화 방지, 에이전트 미팅 기록, 외부 서비스 테스트
- QC 재시도, 디자인 작업 제한

## 한정승인 × 게이트 상호작용

> 상세: `memory/specs/anu-guide.md` 섹션 7 참조

### 한정승인 유형별 게이트 통과 주체

- **나→아누 한정승인**: 게이트 통과 주체 = **아누**. Phase별 체이닝으로 G1→G2→G3 순차 통과.
- **X팀 한정승인**: 게이트 통과 주체 = **팀장**. 팀장이 G1/G2/G3를 자체 통과.

### 게이트 레벨 불변 원칙

- 게이트 레벨 = `dispatch --level` 값. **한정승인이라고 레벨이 낮아지지 않는다.**
- 예: Lv.3 작업의 한정승인 → G1/G2/G3 모두 Lv.3 기준 적용.
- 한정승인은 "누가 통과하는가"만 결정. "어떤 기준으로 통과하는가"는 불변.

### Codex 게이트 --workspace-root 옵션

- InsuRo, insuwiki 등 `/home/jay/workspace` 외부 프로젝트 작업 시 반드시 `--workspace-root` 지정
- 예시: `python3 scripts/codex_gate_check.py --task-id task-XXX --workspace-root /home/jay/projects/InsuRo`
- 미지정 시 task 파일의 `## 프로젝트` 섹션에서 자동 감지 (폴백: `/home/jay/workspace`)

## 작업 규칙

- 모든 코드는 {WORKSPACE_ROOT}/ 하위에 작성
- (project_id가 있으면) **프로젝트 격리**: 모든 코드는 {WORKSPACE_ROOT}/projects/{project_id}/ 하위에만 작성. 다른 프로젝트 디렉토리, 시스템 코드 수정 절대 금지.
- (project_id가 없으면) 이 작업은 시스템 작업입니다. 코드는 {WORKSPACE_ROOT}/teams/{team_short}/ 또는 작업에서 지시된 경로에 작성하세요. 다른 팀 디렉토리는 건드리지 마세요.
- 완료 후 반드시 task-timer.py end 호출
- **완료 전 반드시 이벤트 파일 생성**: {WORKSPACE_ROOT}/memory/events/{task_id}.done
- **완료 후 반드시 보고서 파일 저장**: {report_path}
  - 내용: 작업 내용, 생성/수정 파일 목록, 테스트 결과, 버그 유무, 비고
  - 아누(개발실장)가 이 파일을 읽고 판단합니다

## 섹션 5: 읽기/쓰기 에이전트 격리 (P1-2)

### 에이전트 유형 선택 기준

- **read 에이전트** (`--agent-type read`): 코드 읽기, 분석, 리뷰 작업. worktree 미생성. 파일 수정 없음.
- **write 에이전트** (`--agent-type write`): 코드 작성, 수정, 리팩토링 작업. worktree 생성. 파일 수정 있음.
- **불명확한 경우**: `write` (기본값). 안전한 쪽 선택.

### 주의사항
- `read` 에이전트는 worktree를 생성하지 않으므로 파일 write 시도 시 에러 발생
- `rw_isolation_enabled` 플래그가 `false`이면 `--agent-type` 인자는 무시되고 항상 `write` 동작
- 기능 플래그 상태는 `.claude/feature_flags.json` 에서 확인

## 섹션 6: Task 파일 구조 표준 (P3-10)

> 도입일: 2026-04-01 | 스펙 문서: `/home/jay/workspace/memory/specs/adk-impl-spec-10.md`

### 6.1 YAML Frontmatter 필수

모든 신규 task 파일은 YAML frontmatter를 포함해야 한다.

필수 필드:
- `task_id`: task 고유 ID (번호형: `"{번호}.{체인번호}"`, dispatch형: `"dispatch-{식별자}"`)
- `team`: 담당 팀 (값: 1팀/2팀/3팀/4팀/QC/전략/DA/오케스트레이터)
- `level`: 위임 레벨 (정수 1-4)
- `priority`: 우선순위 (값: P1/P2/P3/P4)
- `depends_on`: 선행 task_id 목록 (없으면 `[]`)
- `created_at`: 생성일 (ISO 8601)
- `deadline`: 데드라인 (ISO 8601 또는 `null`)

선택 필드: `status`, `dri`, `tags`, `spec_doc`

### 6.2 파일 네이밍 규칙

- 번호형 task: `task-{번호}.{체인번호}.md`
- dispatch 지시서: `dispatch-{식별자}.md`
- handoff 파일: `task-{번호}.{체인번호}-handoff-{n}.md`
- phase 계획: `task-{번호}.{체인번호}-phase-plan.md`

금지: 공백, 한글, 대문자, 특수문자(`:`, `?`, `*`) 포함 파일명

### 6.3 제약 조건

- YAML 블록은 파일 최상단 첫 줄에서 시작
- `task_id`는 파일명과 일치해야 함
- `depends_on`이 없는 경우 `[]` (null 금지)
- `deadline`이 없는 경우 `null` (빈 문자열 금지)