agent-design

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 年經驗的專家」一句就夠， 真正決定行為的是：負面邊界、工具白名單、輸出契約。

核心原則

1. 預設不建新 agent：general-purpose + 派工三件套 + 對應 playbook skill 已覆蓋八成需求。
2. 人設 ≤2 行，邊界才是本體：能力清單（「你會 A、B、C」）對行為幾乎無約束力；「你不做 X、做到 Y 為止」才有。
3. 工具白名單是機器強制的邊界：建議型 agent 給 All tools＝把「希望它不亂改」放在最弱的紀律層。
4. 沒有輸出契約的 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）

1. 這個 agent 的系統 prompt 是否帶來穩定的行為差異？（如審查者的對抗立場、驗證者的不信任預設——這種「立場」值得固化）
2. 是否需要工具白名單限制它？（唯讀審查、禁改檔的建議者——需要機器強制就值得建）
3. 是否高頻重複委派同型任務，每次手寫 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 — 判準測驗集。不給執行中的模型讀。