| name | agent-design |
| description | Use when creating a new custom agent/subagent definition (.claude/agents/*.md), auditing or rewriting existing agent definitions, deciding whether a task deserves a dedicated agent vs general-purpose with a good prompt, choosing an agent's tools whitelist or model tier, or when delegated agents keep going off-scope, dumping full transcripts back, or overlapping each other's roles. |
🌐 English version · 繁體中文（正本 / canonical）
Agent 設計判準（agent-design）
定位：dispatching-subagents 管怎麼用 agent，本 skill 管怎麼造 agent。
核心認知：agent 定義是給弱模型的合約，不是履歷。「你是 15 年經驗的專家」一句就夠，
真正決定行為的是：負面邊界、工具白名單、輸出契約。
核心原則
- 預設不建新 agent：general-purpose + 派工三件套 + 對應 playbook skill 已覆蓋八成需求。
- 人設 ≤2 行，邊界才是本體：能力清單（「你會 A、B、C」）對行為幾乎無約束力；「你不做 X、做到 Y 為止」才有。
- 工具白名單是機器強制的邊界：建議型 agent 給 All tools＝把「希望它不亂改」放在最弱的紀律層。
- 沒有輸出契約的 agent 會把整個過程倒回主對話——每個 agent 必有 Output Format。
開工分流
| 情境 | 路徑 | 先讀 |
|---|
| 想建新 agent | 先過「該不該存在」三問，過了才寫 | references/design-criteria.md §1 |
| 審計/整修既有 agent | 逐個跑四件套檢查表 | references/design-criteria.md §2 |
| 選 tools / model | 查最小權限表與 tier 對應 | references/design-criteria.md §3–4 |
| 新 agent 上線前 | 逐條跑必查清單 | references/release-checklist.md |
「該不該存在」三問（全部否 → 不建，用 general-purpose）
- 這個 agent 的系統 prompt 是否帶來穩定的行為差異？（如審查者的對抗立場、驗證者的不信任預設——這種「立場」值得固化）
- 是否需要工具白名單限制它？（唯讀審查、禁改檔的建議者——需要機器強制就值得建）
- 是否高頻重複委派同型任務，每次手寫 prompt 成本高？
- ❌ 「Flutter 專家 agent」——知識型人設。知識已在 playbook skill 裡，general-purpose 被指示「先讀 flutter-dev-playbook」效果相同，多一個 agent 只是多一個選擇困難。
- ✅ 「code-reviewer agent」——對抗立場（不信任實作者）+ 唯讀白名單 + 高頻使用，三問全過。
紅線（絕對禁止）
- 禁止建議/審查型 agent 拿到 Edit/Write——它的產出是意見，能改檔案的意見遲早變成未經授權的改動。
- 禁止沒有 Output Format 的 agent 定義——回報格式缺失的代價由每一次委派支付。
- 禁止只有能力清單、零負面邊界的定義——那不是 agent，是慫恿。
- 測試類 agent 的定義裡必須寫死「禁止為了變綠改鬆斷言/skip」——這條紅線不寫進合約，弱模型在 CI 壓力下必犯。
- 禁止人設段落超過 2 行——多出來的字是 token 稅，不是能力。
失敗訊號（該回頭，不是重試）
| 徵兆 | 多半是 | 修法 |
|---|
| 兩個 agent 的 description 對同一任務都成立 | 定位踩線 | 合併，或寫互鎖條款（「X 移交給 Y」） |
| 委派結果總是倒回全過程流水帳 | 輸出契約缺失 | 補 Output Format + 回報合約 |
| agent 清單 >10 個、每次選擇都要想 | 建太多了 | 跑三問淘汰，知識型的降級為 playbook skill |
| agent 老是做超出請求的事 | 零負面邊界 | 補「不做什麼」≥3 條 |
references 索引
references/design-criteria.md — 三問詳解、四件套檢查表、tools 最小權限表、model tier、正反例對照。造/審 agent 前讀。references/release-checklist.md — 新 agent 上線前逐條必查。references/test-scenarios.md — 判準測驗集。不給執行中的模型讀。
