打造自己的 subagent：從設定檔到四個設計心法

上一篇我們搞懂了 subagent 的原理：獨立 context 做事、只回傳摘要。內建的幾款夠用來探索與規劃，但真正的威力在自訂：一個懂你們團隊審查標準的程式碼審查員、一個照你格式寫測試的測試員，這些都能做成 subagent，而且做一次全隊共用。

這篇分兩段：前半段把 subagent 建起來、看懂設定檔每一個欄位；後半段講四個設計心法，這是「能動的 subagent」跟「好用的 subagent」之間的差距。

最快的起手式：/agents 指令

在 Claude Code 裡輸入 /agents，就會打開 subagent 的管理介面，選「建立新的 agent」。第一個問題是層級：專案層級只在目前專案可用，適合跟專案綁定的角色；使用者層級跨所有專案，適合你個人的通用助手。

接著可以手寫設定，但更推薦的做法是讓 Claude 幫你生成：描述你想要這個 subagent 做什麼，它會產出名稱、description 跟 system prompt 的初稿，你再修。過程中還會讓你挑工具（讀取類、編輯類、執行類、MCP 工具等）、選模型（haiku 快而輕、sonnet 均衡、opus 適合複雜分析，或 inherit 跟著主對話），最後選一個代表色方便在畫面上辨認。

看懂設定檔

建立完成後，設定檔會存成一個 markdown 檔，通常在專案的 .claude/agents 資料夾裡。長這樣：

---
name: code-quality-reviewer
description: Use this agent when you need to review recently
  written or modified code for quality, security, and best
  practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality
assurance, security best practices, and adherence to project
standards. Your role is to thoroughly examine recently written
or modified code and identify issues.

• name：唯一識別名，之後可以直接點名它來做事。
• description：控制 Claude 什麼時候啟用它，必須寫成單行，可以放使用情境範例。
• tools：它拿得到的工具清單，隨時可以回來改。
• model：sonnet、opus、haiku 或 inherit。
• frontmatter 底下的內文，就是這個 subagent 的 system prompt：它該關注什麼、怎麼分析、怎麼回報。

四個設計心法

設定檔看得懂之後，接下來是「能動」與「好用」的分水嶺。一個設計不良的 subagent 會亂逛、跑太久、或交回主對話用不了的答案，修正的方法其實就四件事：把 description 寫具體、定義輸出格式、要求回報障礙、限縮工具權限。一個一個看。

心法一：description 決定它收到什麼指令

很多人不知道：主 agent 委派任務時，會參考 description 來撰寫任務說明。description 寫得籠統，subagent 收到的指令就籠統，例如只有一句「去看看目前的修改」；如果你在 description 裡寫明「必須明確告訴這個 agent 要審查哪些檔案」，主 agent 就會把實際的檔案清單寫進任務裡。想要 subagent 收到什麼樣的指令，就把要求寫進 description。

心法二：定義輸出格式

這是單一最有效的改善：在 system prompt 裡定義回報格式。好處有兩個：格式的每一節填完，subagent 就知道自己做完了，有自然的停止點；反之沒有輸出格式的 subagent 很難判斷「研究夠了沒」，常常跑過頭。以審查員為例，可以要求它依「總結、重大問題、主要問題、次要問題、建議、是否可合併」六節回報。

心法三：要求回報障礙

subagent 工作中常會發現一些寶貴情報：某個指令要加特定參數才能跑、某個相依套件有問題、環境有什麼怪癖。這些如果沒寫進摘要，主對話就得自己重新踩一次坑。解法很直接：在輸出格式裡加一節「遭遇的障礙」，明確要求它回報繞路解法、特殊參數與環境問題。

心法四：只給必要的工具

工具給得越少，副作用越少，角色也越清楚。原則是照任務的本質給：

測試你的 subagent

建好之後實際測一輪：改幾行程式，請 Claude 審查，看 subagent 有沒有被啟用、回報是不是照你定的格式。沒被自動觸發，九成的原因在 description：補上更具體的情境範例與觸發字眼，Claude 就越知道什麼時候該把工作交給它。想更主動一點，可以在 description 裡寫 proactively，請 Claude 在大改動之後主動建議執行。

小結

回頭看，一個好的 subagent 其實就是一份寫得好的工作說明書：description 讓對的任務找上它、也讓它收到具體的指令；輸出格式給它終點線；障礙回報讓經驗留得下來；工具清單畫出它的活動範圍。四件事各自都很簡單，合起來就是「派得出去、收得回來」的可靠分工。

從你最常重複委派的那種任務開始做第一個，用兩三輪實戰把它調順，你的 Claude Code 就多了一位長期隊友。