本文根據 Claude Code 官方《Create custom subagents》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。測試員和調試員的提示詞是本站自己擬的示例。本站（bigolab.com）不是 Anthropic 官方網站。
適用於誰
- 已經看過 /guides/claude-code-subagents，知道子代理是什麼，但不知道具體怎麼寫的人；
- 想讓「跑測試、查報錯」這類輸出很囉嗦的工作留在獨立上下文裏，不污染主對話的人；
- 想給子代理加上硬性限制（比如只能讀數據庫）的人。
結論先說
- 子代理就是一個帶前置字段的 Markdown 文件，放在
.claude/agents/（當前項目）或~/.claude/agents/（你所有項目）。只有name和description是必填。 - description 決定會不會被自動調用：官方說 Claude 按它來判斷是否委派，加上「use proactively」這類措辭能促進自動調用。
- 權限靠 tools 收窄：只讀的角色只給
Read、Grep、Glob；官方寫明省略tools就繼承所有可用工具。 - 想攔截具體命令，用 hook 而不是 tools：官方明確說
disallowedTools: Bash(git push *)這種帶參數的寫法會把整個 Bash 去掉，要攔具體命令需要permissions.deny規則或 PreToolUse hook。 - 子代理用的是同一份額度：官方寫明子代理請求計入與主對話相同的用量限制，所以別建太多、別讓它們跑太久。
圖：本站根據 Claude Code 官方《Create custom subagents》 整理的示意圖
代碼審查員的寫法已經在 /guides/claude-code-subagents 裏給過，本文不重複，只補它沒有的角色。
一、測試員：test-runner
適用場景：跑完整測試輸出幾百行，你只想知道哪幾個失敗、為什麼。讓子代理去跑，只把摘要帶回主對話，這正是官方說子代理能「把冗長輸出留在主對話之外」的用法。
.claude/agents/test-runner.md：
markdown
---
name: test-runner
description: 運行測試並彙報結果。修改代碼後或用戶要求跑測試時主動使用（use proactively）。
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
---
你是測試執行員。被調用時：
1. 先用 Glob 和 Grep 找出與改動相關的測試文件
2. 運行相關測試（優先單個文件，其次全量），命令見項目的 CLAUDE.md
3. 只彙報：通過數、失敗數；每個失敗用例的名字、斷言資訊、最可能的原因
4. 不要修改任何文件，不要自己修復
輸出格式：先給一行總結，再列失敗項。幾點說明：
tools裏沒有Edit和Write，所以它只能跑命令和讀文件，改不了代碼，這個「不要修改」就有了硬保證；maxTurns: 15是官方字段，限制它最多走多少個回合，到上限時輸出會被標記為部分結果，可以繼續；model: sonnet用別名固定模型。官方給出的解析順序是：調用時傳入的別名、frontmatter 的model、環境變量CLAUDE_CODE_SUBAGENT_MODEL、最後才是主對話的模型。
二、調試員：debugger
調試員要能改代碼，所以不寫 tools，讓它繼承全部工具：
markdown
---
name: debugger
description: 排查報錯和測試失敗的專家。遇到異常、堆棧或失敗的測試時主動使用。
---
你是調試專家。被調用時：
1. 先復現問題：讀報錯訊息和堆棧，找到出錯位置
2. 提出最多三個可能的原因，逐個用代碼或日誌驗證
3. 找到根因後做最小改動修復，再重新運行相關測試確認
4. 彙報：根因是什麼、改了哪裏、如何驗證官方文檔裏有一個最簡的 debugger 示例用於 --agents 參數，只寫了說明和一句提示詞；上面這份更詳細的版本是本站擬的。什麼時候用它：問題需要「讀—猜—改—驗」反覆多輪，主對話的上下文不想被中間過程佔滿。如果只是想讓它給建議不改代碼，就改成只讀版本，見下一節。
三、只讀調研員
官方的 safe-researcher 示例原樣如下：
yaml
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---想「繼承全部工具但禁止寫文件」，官方給的另一種寫法是用黑名單：
yaml
---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---兩種寫法的區別：白名單 tools 只給你列的；黑名單 disallowedTools 是先從繼承的全部工具裏去掉，如果同一個工具在兩處都出現，會被去掉。MCP 工具也一樣，官方寫法是 disallowedTools: mcp__github 去掉某個 MCP 伺服器的全部工具。
四、只讀數據庫員：用 hook 攔截寫操作
只放行 SELECT，是官方《子代理》頁給出的完整示例。子代理只給 Bash，再掛一個 PreToolUse hook：
yaml
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---校驗腳本（需要用 chmod +x 設為可執行，官方說明 macOS 和 Linux 上必須如此）：
bash
#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0關鍵點：腳本以退出碼 2 結束並把原因寫到 stderr，就會阻止這次工具調用；退出碼 0 放行。frontmatter 裏的 hook 只在這個子代理運行期間生效；對於放在項目裏的子代理文件，官方還說明需要先接受工作區信任對話框，hook 才會運行。hook 的基礎見 /guides/claude-code-hooks。
五、怎麼調用它們
圖：本站根據 Claude Code 官方《Create custom subagents》 整理的示意圖
官方列了三種方式，由弱到強：
- 自然語言點名：例如「用 test-runner 子代理跑一下失敗的測試」，Claude 通常會委派；
- @ 提及：輸入
@選子代理，例如@"code-reviewer (agent)" 看一下認證相關的改動。你的整條消息仍然交給 Claude，由它來寫給子代理的任務提示； - 整個會話換成它：
claude --agent code-reviewer，主線程會採用該子代理的工具限制和模型；在.claude/settings.json裏寫"agent": "code-reviewer"可設為項目預設，命令行參數優先於設定。
現在的 /agents 命令只提醒你讓 Claude 創建或直接編輯目錄，交互向導只在 v2.1.197 及更早版本里有。
如果你想讓測試員和調試員聯動，不必自己寫調度邏輯：官方說明子代理預設可以再啟動子代理，最多往下三層，可用環境變量 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 調整，設為 1 則禁用嵌套。
常見問題
Q：子代理沒有被自動調用？
先看 description 是否寫清了觸發場景；再用「用 xxx 子代理……」明確點名試一次。名字以 name 字段為準，不是文件名。
Q：子代理 vs 技能 vs hook 怎麼選？
需要獨立上下文、隔離冗長輸出用子代理；固定流程用技能；硬性攔截用 hook，對比見 /guides/skill-vs-mcp-vs-subagent-vs-hook。
Q：會不會很費額度？
會。每個子代理都有自己的上下文窗口和調用，並計入同一份用量。需要更多額度可以了解 Claude Code 訂閱方案；同時給每個子代理設 maxTurns 和便宜的 model。
參考資料
- Claude Code 官方：Create custom subagents — https://code.claude.com/docs/en/sub-agents
0 條評論
還沒有評論，來搶沙發～