Claude Code Subagents 教學：組一支 AI 小隊，一個寫、一個審

叫 Claude Code 寫完功能，再問它「有沒有問題」，它常常說「沒問題」。自己寫的東西，自己審最容易放水。這篇把工作拆給兩個 subagent（子代理）：一個負責寫，一個只能看、不能改，專門挑毛病。你只要說一句話，它們就會接力做完，最後把審查結果交給你。

快速回答 subagent（子代理）是有自己名字、規則和工具清單的小幫手，存成 .claude/agents/ 裡的 Markdown 檔。請 Claude Code 建兩個：game-builder 負責加功能，game-reviewer 只能讀檔和跑 node test.js，負責審查。新建後先重開 Claude Code，再說「用 game-builder 加功能，做完交給 game-reviewer 審查」，它們就會接力。2026-10-23 用 Claude Code 2.1.309 實測，金色食物功能 1 分 18 秒做完，審查找出 1 個中等問題。

做完這篇，你會有

• 小遊戲專案的兩個 subagent：game-builder（寫）和 game-reviewer（審）
• 用一句話讓它們接力：一個做完功能，另一個接著審查
• 看過審查報告，請寫的那個修好，再請審的那個複審

開始之前要準備：

• 前幾篇的 snake-game 資料夾，裡面有 test.js（/goal 那篇寫的）
• Node.js：在終端機輸入 node -v 有版本號就好

兩個 subagent 的分工

審查的那個拿不到改檔工具，所以只能指出問題，不能自己偷偷改掉。

步驟 1：一句話建好兩個 subagent

在遊戲資料夾啟動 Claude Code，輸入：

幫我在這個專案建立兩個 subagent，存在 .claude/agents/：一個叫 game-builder，負責替貪食蛇加新功能、可以改檔案；一個叫 game-reviewer，只能讀檔和跑 node test.js，不能改任何檔案，負責審查改動，回報要列出問題和嚴重程度。

它在 .claude/agents/ 建了兩個檔案。每個檔案開頭是設定，下面是給這個 subagent 的工作說明。下面是 game-reviewer.md 開頭的結構，hook 的實際程式用「……」省略了，不能直接貼上使用：

---
name: game-reviewer
description: 審查貪食蛇專案的改動，只讀檔和執行 node test.js，不修改任何檔案……
tools: Read, Grep, Glob, Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "……不是 node test.js 就擋下……"
---

# game-reviewer：貪食蛇程式碼審查員
你負責審查這個貪食蛇專案的改動，只找問題，不修問題……

• name 和 description 一定要有。Claude Code 看 description 決定什麼時候找它。
• tools 列出它能用的工具。這裡拿掉了 Edit 和 Write，再搭配下面的 hook，把 Bash 限制成只能跑 node test.js。
• 它還自己加了一個 hook：像執行指令前的檢查哨，只讓 node test.js 通過，其他指令都擋下（hook 在 Hooks 那篇教過）。

步驟 2：重開 Claude Code，讓它認得新成員

如果 .claude/agents/ 是剛剛才建的，這次對話還不認得它們。輸入 /exit 離開，再輸入 claude 重開。

輸入 /agents 會看到一段說明：建立 subagent 的精靈已經拿掉了，改成請 Claude 幫你建，或直接改檔案。

畫面上列的兩個位置，就是 subagent 檔案可以放的地方。確認專案的 .claude/agents/ 裡有兩個檔案，就可以進下一步。

步驟 3：一句話讓它們接力

輸入：

用 game-builder 加一個功能：每吃 5 個食物，就出現一顆金色食物，吃到加 3 分，5 秒內沒吃到就消失。做完交給 game-reviewer 審查，把審查結果告訴我。

畫面上會出現 game-builder(實作金色食物功能)，代表工作交出去了。subagent 預設在背景做事，下方的清單會列出誰正在工作。

輸入 /tasks 可以看所有正在跑的 subagent。等審查做完，主對話會把結果整理給你：

這次找到的中等問題是：遊戲專案用來新增配色的 /new-skin 指令，產生的配色範本沒有金色食物的顏色。功能本身能動，測試也全過。這種問題靠「自己寫、自己檢查」很容易漏掉。

步驟 4：請寫的修，請審的複審

輸入：

請 game-builder 修那個「中」的問題，修完再請 game-reviewer 複審一次，用表格告訴我結果。

剩下的輕微問題要不要修，由你決定。想修就再說一次「請 game-builder 修掉」。

換你做

替你自己的專案想一組「一個做、一個查」的分工，請 Claude Code 建成 subagent。例如：

• 一個寫網站文案，一個只檢查錯字和語氣
• 一個改 CSS，一個只負責在手機尺寸檢查畫面

說清楚三件事：叫什麼名字、負責什麼、能用哪些工具。

常見卡關

• 出現 Agent type 'game-builder' not found：.claude/agents/ 是這次對話開始後才建的，Claude Code 還沒載入。輸入 /exit 再重開就好。實測時，Claude 會先用通用的 subagent 照著檔案內容代做，但工具限制不一定會生效，建議重開再跑一次。

• 它沒有交給 subagent，自己做完了：在指令裡寫明名字，例如「用 game-builder……」。也可以輸入 @，從清單選 subagent。
• 審查員把檔案改掉了：先確認新建後有重開 Claude Code，用的真的是 game-reviewer。再打開它的設定檔：tools 沒有 Edit、Write，hook 也有把 Bash 限制成只能跑 node test.js。
• 用量比平常多：每個 subagent 有自己的對話，各自算用量。小改動直接跟主對話說就好。

你做到了

• 用一句話建好兩個 subagent，一個能改檔、一個只能讀
• 一句話讓它們接力，金色食物功能做完就自動送審
• 看懂審查報告，請寫的修、審的複審

常見問題

subagent 和直接跟 Claude Code 說有什麼不同？

subagent 有自己的對話記憶、規則和工具清單，做完只把結果交回主對話，中間讀了哪些檔案不會塞滿主對話。審查這種「換一雙眼睛看」的工作，交給它特別合適。

可以讓所有專案都用同一個 subagent 嗎？

可以，把 subagent 的設定檔放在 ~/.claude/agents/，所有專案都能用。放在專案的 .claude/agents/ 就只有這個專案能用。

要自己寫 subagent 檔案嗎？

不用，直接請 Claude Code 建就好。想調整分工，改檔案裡的工作說明；想調整它能用哪些工具，改 tools 那一行。

下一步

• Claude Code Hooks 教學：每次改完自動檢查，改壞了當場擋下：審查員的「只能跑測試」就是用 hook 鎖的。
• Claude Code /goal 教學：設好完成條件，讓它自己做到完：test.js 是在這篇寫的。

參考資料

• Anthropic, Create custom subagents（Claude Code 文件，.claude/agents/ 與 ~/.claude/agents/、必填的 name 與 description、tools、frontmatter hooks、/agents、重開才找得到、背景執行與 /tasks、@ 指定） https://code.claude.com/docs/en/sub-agents