사용자: "일해라"
    ↓
[메인 Claude (Sonnet)]  ← 오케스트레이터
    ├─ planner-opus-4_6      → 핸드오프 텍스트 반환
    │      └─ 메인이 handoff.md 저장
    ├─ implementer-sonnet    → handoff.md 읽고 구현
    └─ (finish) Preflight → reviewer-opus-4_6
           → git diff · verdict / findings
           → not ready 시 review_findings.md 저장 후 implementer 재스폰(1회)

사용자 최종 승인 후
    └─ 메인: finish_approval → commit / push / MCP PR

세 에이전트 모두 Agent 도구로 스폰된다. 메인은 라우팅·확인 게이트·상태 파일 쓰기와 커밋/푸시를 담당한다.

1. 1

   Agent 도구 호출 시 model 파라미터

   Agent(subagent_type="...", model="opus")
2. 2

   .claude/agents/{name}.md frontmatter

   model: claude-opus-4-6 ← 이 프로젝트가 쓰는 방식
3. 3

   프로젝트 settings.json

   .claude/settings.json
4. 4

   회사 원격 정책

   ~/.claude/remote-settings.json → model: "sonnet"
5. 5

   Claude Code 기본값

   현재 Sonnet 계열

서브에이전트의 모델은 frontmatter가 고정한다. 메인 오케스트레이터 기본값(remote-settings.json의 sonnet 등)과 독립이다.

💡 planner가 실수로 파일을 수정하거나, reviewer가 코드를 바꾸는 사고를 도구 레벨에서 원천 차단한다.

Preflight(브랜치·금지경로·tsc·lint)로 Opus 리뷰어 스폰 자체를 아끼는 구간이 있다.

파일 읽기와 코드 작성이 반복되는 고볼륨 구간이 Sonnet으로 가고, 판단만 하는 저볼륨 구간이 Opus로 간다. 단순 태스크는 Light pickup으로 planner·reviewer Opus 호출을 줄일 수 있다.

💡 표준 경로는 함수 하나를 찾기 위해 파일 전체를 컨텍스트에 올린다. Serena는 심볼 트리에서 위치를 파악한 뒤 그 함수 본문만 읽어 파일 크기와 무관하게 토큰이 낮다. planner가 Opus로 실행되는 구조에서는 이 차이가 비용에 직접 기여한다. 2026-04-30: planner 에이전트에 심볼 검색 시 Grep 금지 하드 규칙을 두어 Serena 우회 남용을 줄였다.

Claude Code 기본 기능이므로 외부 라이브러리나 별도 인프라는 불필요하다.

💡 막는 훅이 아니라 검증 리마인더를 주입한다. 플래그는 pickup 시작 시 삭제되어 새 작업마다 다시 1회 주입된다.

{
  "repo": "/.../neo",
  "branch_type": "feature",
  "work_item": "68900",
  "approved_at": 1745100000,
  "expires_at": 1745103600
}

{
  "repo": "/.../neo",
  "branch": "product/hqn/feature/68900",
  "work_item": "68900",
  "approved_at": 1745110000,
  "expires_at": 1745117200
}

💡 시작 토큰은 짧게(1h), 완료 토큰은 길게(2h) — 작업 성격에 맞춘 TTL

$ git checkout -b product/hqn/feature/68900
        │
        ▼  Bash 훅 실행 (hqn_guard_shell.py)
┌───────────────────────────────────────────────┐
│ ① 브랜치명 패턴 일치                    ✓  │
│ ② compound 아님 (&&/;/||/개행)        ✓  │
│ ③ 현재 브랜치 = product/hqn/main        ✓  │
│ ④ 워킹트리 clean                         ✓  │
│ ⑤ HEAD == origin/product/hqn/main       ✓  │
│ ⑥ start_approval 토큰 유효 + 일치       ✓  │
└───────────────────────────────────────────────┘
        ▼
   → 허용 · 브랜치 생성

💡 한 단계라도 실패하면 즉시 deny — compound command 차단으로 "검증 건너뛰고 생성"을 원천 봉쇄한다.

2026-04-30 반영: guard 훅 3종은 예외 시 deny(fail-safe), 컨텍스트 주입 훅만 fail-open. MCP ADO 경로는 hqn_guard_mcp_ado.py로 CLI와 동일한 토큰 검증이 적용됨.