Sub-agent Context Boundary 與 Agent Role Taxonomy
Context
背景
yibi-mvp 的 .claude/agents/ 目錄中定義了 4 個 reviewer agent：
api-contract-reviewer：比對 Pydantic schema 與 Flutter freezed modelcelery-task-reviewer：審查 Celery task 的 idempotency / serializationflutter-reviewer：審查 Flutter Clean Architecture 與 widget 效能security-reviewer：審計 JWT / auth / MQTT / Celery 輸入驗證
觀察到的問題
- 無 role taxonomy：4 個 agent 全部是「reviewer」角色，沒有 planner / implementer / verifier 的分工定義。未來新增 agent 時，無法從文件中得知「這個 agent 應該有 Write 權限嗎？」
- 無 path-scope 明文：agent 的
description文字有觸發情境描述，但沒有機器可讀的 path-scope 欄位。這讓「什麼 path 改動應該觸發哪個 agent」靠人工記憶，無法自動化。 - 無 handoff protocol：當一個 agent 完成工作後，下一個 agent 是誰？reviewer → (修改後) → 誰 verify？這條 chain 沒有文件。
- 與 ADR-0006 的關聯：ADR-0006 定義了「五尺度約束」，其中「中尺度約束」對應「Sub-agent 職責（讓 AI 活在合適的 Context 中）」。ADR-0006 沒有展開這個層級的設計，本 ADR 補足。
Decision
結論：建立 agent role taxonomy、path-scope 欄位規範、handoff protocol，以 .claude/rules/agent-routing.md 作為執行文件。
一、Agent Role Taxonomy（四種角色）
| Role | 職責 | Tools 權限 | 典型動作 |
|---|---|---|---|
reviewer | 審查程式碼品質、合約一致性、安全性 | 只讀（Glob / Grep / LS / Read） | 比對差異、報告問題 |
planner | 分析需求、設計實作方案、拆解 task | 只讀（可 WebFetch） | 輸出 plan、task list |
implementer | 執行實作、修改程式碼、寫測試 | 讀寫（含 Edit / Write / Bash） | 修改檔案、執行測試 |
verifier | 驗證實作是否符合 spec / contract | 只讀（含 Bash 執行測試） | 跑測試、比對 spec |
既有 4 個 agent 全屬 reviewer 角色（僅 Read-only tools，不修改程式碼）。
二、Path-Scope 欄位規範
每個 agent frontmatter 加 scope 欄位（YAML list of glob patterns），明確定義哪些路徑改動應考慮觸發此 agent：
---
name: <agent-name>
role: reviewer | planner | implementer | verifier
scope:
- path/pattern/**/*.ext
handoff_to: [] # agent names (empty if terminal)
---scope 是觸發建議（非強制 CI rule），用途：
- 讓
/reviewskill 決定「這次改動需要召喚哪些 reviewer」 - 讓新成員閱讀文件時快速理解「我改了 mobile 的 dart 檔，應該觸發 flutter-reviewer」
三、Handoff Protocol
reviewer 類 agent 不需要 handoff（都是終止節點，回報後由人類決定是否修改）。
未來若新增 verifier 或 implementer agent，handoff 設計如下：
主 session
├── (before PR) planner agent → plan
├── (during impl) implementer agent → code changes
├── (after PR) reviewer agents（並行）
│ ├── api-contract-reviewer
│ ├── flutter-reviewer
│ ├── security-reviewer
│ └── celery-task-reviewer（若有 backend 改動）
└── (after fix) verifier agent → 確認 reviewer 問題已修復reviewer 的 handoff_to: []（空列表）= 終止節點，直接回報。
四、既有 4 個 Agent 的 Scope 定義
| Agent | Role | Scope |
|---|---|---|
| api-contract-reviewer | reviewer | mobile/lib/**/*.dart, backend/src/application/schemas/**/*.py, backend/src/presentation/api/**/*.py |
| celery-task-reviewer | reviewer | backend/src/infrastructure/workers/**/*.py |
| flutter-reviewer | reviewer | mobile/lib/**/*.dart |
| security-reviewer | reviewer | backend/src/**/*.py, mobile/lib/core/storage/**/*.dart, mobile/lib/core/network/**/*.dart, mobile/lib/features/auth/**/*.dart |
Alternatives Considered
-
完全不文件化，靠 description 字串：現狀。問題是無法程式化讀取 scope，新成員要讀完 description 才知道何時觸發。
-
用 path-scoped rule 取代 agent frontmatter：考慮過。但 path-scoped rule 是給「持續約束（CLAUDE.md 指令）」用的，agent metadata 屬於「agent 自描述」，放在 agent 定義本身更合適。
-
用 CI 強制觸發（GitHub Actions path filter）：未來可補充，但目前 agent 召喚是 session-level 決策，CI-level 強制超出本 ADR 範圍。
Consequences
好：
- 新增 agent 時有明確的 template（frontmatter + 四種角色定義）
/reviewskill 可以讀 scope 欄位決定觸發哪些 reviewer，而非依賴硬編碼清單- 補上了 ADR-0006 「中尺度約束」層級的具體落地
壞 / 代償：
- 既有 4 個 agent 需要補 role / scope / handoff_to 欄位（1 次性改動，低成本）
- scope 是 glob pattern，需要人工維護（改 monorepo 路徑時記得更新）
中性：
- Role taxonomy 目前只用到
reviewer，其他三個角色是為未來設計空間預留定義 - handoff_to 全為空列表，未來新增 verifier agent 時再填寫