Claude Code 自訂 Agent 完整教學 — 用 Markdown 打造你的專屬 AI 團隊

你在公司裡遇到一個問題，不會直接叫全公司的人一起來看。你會找特定的人——資料庫有問題找 DBA、API 設計要討論找架構師、程式碼寫完找資深工程師 review。每個人有自己的專長、自己的看事情的角度、自己負責的範圍。

Claude Code 的自訂 Agent 就是同一件事。你用一份 Markdown 檔案定義一個 AI 隊友——它擅長什麼、能用什麼工具、遇到什麼情況該叫它出場。之後 Claude Code 會自動判斷什麼時候把任務委派給它。

不是「讓 AI 扮演某個角色」那種表演。是真的把工作拆開，讓不同的 agent 負責不同的事。

一份 Agent 檔案長什麼樣子

打開 ~/.claude/agents/ 隨便看一個檔案，結構很簡單：

---
name: code-reviewer
description: "程式碼品質審查。寫完 code 後自動觸發，檢查命名、錯誤處理、效能、安全。"
tools: Read, Bash
model: sonnet
---

你是一位資深工程師，專門做 code review。

## 審查重點
- 命名是否清楚表達意圖
- 錯誤處理是否完整
- 有沒有 N+1 查詢或效能問題
- 有沒有安全漏洞（SQL injection、XSS、硬編碼的 secret）

## 輸出格式
- CRITICAL：必須修才能合併
- HIGH：強烈建議修
- MEDIUM：有空再處理
- LOW：風格偏好，不阻擋合併

先看整體架構，再逐檔案檢查。不要只挑毛病——好的設計也要指出來。

三塊東西。YAML frontmatter 控制 agent 的設定。下面的 Markdown 是 agent 的 system prompt——它拿到任務後的行為指南。中間的 --- 分隔線隔開設定和內容。

這跟寫一份工作職缺描述的邏輯一模一樣。Frontmatter 是 job spec（這個職位叫什麼、歸哪個部門、能碰哪些系統）。Body 是 onboarding 手冊（你進來之後該怎麼做事）。

放在哪裡

兩個位置，用途不同。

**~/.claude/agents/**——全域 agent。不管你開哪個專案都能用。適合通用型的角色：code-reviewer、security-reviewer、database-architect。你在任何專案裡都可能需要這些人。

**.claude/agents/**——專案級 agent。只在這個 repo 裡生效。適合跟特定專案綁定的角色：比如一個「前端 component 規範檢查員」只對你的 React 專案有意義，放在專案目錄下就好。

專案級的好處是可以 commit 進 git。你的團隊 git pull 之後就自動有同一套 agent——不需要每個人手動設定。

Frontmatter 的每一個欄位

YAML frontmatter 裡的欄位不多，但每一個都影響 agent 的行為。

name（必填）

Agent 的識別名稱。Claude Code 在決定要不要把任務委派給某個 agent 時，會看 name 和 description。

1	name: tdd-guide

description（必填）

一句話說明這個 agent 幹嘛、什麼時候該用它。這句話很關鍵——Claude Code 讀這句話來決定「眼前這個任務要不要找這個 agent」。寫得越精準，觸發越準確。

1	description: "測試驅動開發引導。新功能或 bug fix 時自動觸發。強制先寫測試再寫實作。"

壞的 description："幫忙寫測試"。太模糊，Claude Code 不知道什麼時候該找它。

好的 description："測試驅動開發引導。新功能或 bug fix 時自動觸發，強制 RED-GREEN-REFACTOR 流程，驗證覆蓋率 80%+。" 夠具體，觸發條件明確。

model（選填）

指定這個 agent 跑哪個模型。不指定就繼承主 session 的模型。

1
2
3

model: sonnet    # Claude Sonnet 4.6
model: opus      # Claude Opus 4.7
model: haiku     # Claude Haiku 4.5

怎麼選？一個粗略但實用的原則：

haiku：高頻、輕量的任務。格式檢查、簡單查詢、跑 lint。便宜，快。

sonnet：大多數開發任務。code review、refactoring、一般的 coding。性價比最好。

opus：需要深度推理的場景。架構設計、複雜 debug、跨系統分析。最強但最貴。

一個 code-reviewer 不需要 Opus 級別的推理——Sonnet 就夠了。但一個 architecture-designer 在分析微服務邊界時，Opus 的深度推理能力差別很大。

tools（選填）

限制 agent 能用的工具。不指定就是全部工具都能用。

1	tools: Read, Bash

為什麼要限制？因為不是每個 agent 都需要寫檔案的能力。一個 code-reviewer 只需要讀程式碼（Read）和跑測試（Bash），不應該有 Write 和 Edit。限制工具範圍等於限制 agent 的行動範圍——跟給員工設定系統權限是同一件事。

常見的工具：Read、Write、Edit、Bash、WebSearch、WebFetch。

disallowedTools（選填）

反過來，列出不能用的工具。跟 tools 互斥——設了 tools 就不用設這個。

1	disallowedTools: Write, Edit

適合「什麼都能做，但就是不能碰某幾樣」的場景。

maxTurns（選填）

Agent 最多跑幾輪對話。防止 agent 跑到失控。

1	maxTurns: 15

不設的話預設值通常夠用。但如果你有一個會做大量搜尋的 research agent，設一個上限是好習慣。

permissionMode（選填）

控制 agent 的權限模式。

1 2	permissionMode: bypassPermissions # 不詢問直接執行 permissionMode: default # 遵循一般權限規則

bypassPermissions 要小心用——它讓 agent 跳過所有確認提示。只有在你完全信任 agent 的行為範圍時才開。

實戰：從零建一個 Security Reviewer Agent

不用看別人的範例，從頭寫一個。

需求：每次 commit 前自動掃描安全問題——硬編碼的 secret、SQL injection、XSS、不安全的依賴。

---
name: security-reviewer
description: "安全審查。commit 前或 PR 前自動觸發，掃描硬編碼 secret、SQL injection、XSS、不安全依賴。"
tools: Read, Bash
model: sonnet
maxTurns: 20
---

你是一位應用程式安全工程師。每次被召喚時，執行以下掃描：

## 掃描清單

### 1. 硬編碼 Secret
- grep 搜尋 API key、token、password 的 pattern
- 檢查 .env 檔案是否在 .gitignore 裡
- 掃描設定檔是否有明文密碼

### 2. 注入攻擊
- SQL 查詢是否使用參數化
- 使用者輸入是否經過消毒再用於 HTML 輸出
- 命令列呼叫是否有 shell injection 風險

### 3. 認證與授權
- API endpoint 是否有 auth middleware
- 敏感操作是否檢查權限
- Session/Token 的生命週期設定

### 4. 依賴安全
- 執行 npm audit / pip-audit / mvn dependency-check
- 標記有已知 CVE 的依賴

## 輸出格式

每個發現用以下格式：

**[CRITICAL/HIGH/MEDIUM/LOW]** 檔案:行號
- 問題：具體描述
- 風險：攻擊者可以怎麼利用
- 修復：建議做法

掃描完後輸出總結：X 個 CRITICAL、Y 個 HIGH、Z 個 MEDIUM。
CRITICAL 和 HIGH 必須修復才能繼續。

存成 ~/.claude/agents/security-reviewer.md。完成。

下次你在 Claude Code 裡寫完程式碼，它會自動判斷——「這是新 code，應該跑安全檢查」——然後把任務委派給 security-reviewer。你不需要手動觸發任何東西。

Agent vs Skill：什麼時候用哪個

Claude Code 有兩種「可擴充的能力」：Agent 和 Skill。它們的觸發方式和用途不一樣。

Agent（自動觸發）：Claude Code 在處理任務時，自動判斷「需要某個專業角色」，把工作委派出去。你不用做任何事——它自己決定什麼時候叫誰。Agent 有自己的 context、自己的模型、自己的工具限制。

Skill（手動觸發）：你在終端機裡輸入 /skill-name，明確告訴 Claude Code「用這個技能」。Skill 的內容會被載入到當前 session，不是獨立的 context。

類比：Agent 像是公司裡的部門——有事自動找他們。Skill 像是 SOP 手冊——你翻開它來照著做。

什麼時候用 Agent：

需要獨立 context（不受主 session 的 token 限制）
需要限制工具和模型
希望自動觸發，不用手動介入

什麼時候用 Skill：

需要在當前 session 裡執行（共享 context）
步驟式的工作流程（部署、發布、審查流程）
需要跟使用者互動確認

進階：團隊組合

一個好的 agent 團隊不是每個人都最強，是分工清楚。

以下是一個中型專案的 agent 配置範例：

Agent	模型	工具	觸發時機
`code-reviewer`	sonnet	Read, Bash	寫完 code 後
`security-reviewer`	sonnet	Read, Bash	commit 前
`tdd-guide`	sonnet	Read, Write, Edit, Bash	新功能開發
`backend-architect`	opus	Read, Write, Edit, Bash	架構設計
`database-architect`	opus	Read, Write, Edit, Bash	DB schema 決策
`doc-updater`	haiku	Read, Write, Edit	文件更新

注意模型的分配。日常任務（review、測試）用 Sonnet 就夠了，不用每個 agent 都開 Opus。架構決策需要深度推理才上 Opus。文件更新是簡單任務，Haiku 就搞定，還省 token。

這跟公司請人的邏輯一樣——不是每個職位都需要請 Staff Engineer。匹配任務複雜度和角色能力，才是聰明的花法。

寫好 System Prompt 的三個原則

Agent 檔案下半段的 Markdown body 就是 system prompt。這段文字決定了 agent 拿到任務後會怎麼做事。

第一，具體勝過抽象。「仔細檢查程式碼品質」是廢話。「檢查所有 catch block 是否只是 swallow error 而沒有 log」是指令。

第二，給輸出格式。Agent 回報的結果會被 Claude Code 主 session 讀取。格式一致才容易被理解和處理。CRITICAL/HIGH/MEDIUM/LOW 分級是一個被驗證過很好用的 pattern。

第三，設邊界。告訴 agent 什麼不做跟告訴它什麼做一樣重要。Code reviewer 不應該順手改 code——它的職責是指出問題，不是修復問題。Security reviewer 不應該自己改設定——它指出風險，由人決定怎麼處理。

除錯：Agent 沒被觸發？

寫完 agent 但 Claude Code 都不叫它出場？檢查這幾件事：

description 太模糊。Claude Code 靠 description 判斷觸發時機。如果你的 description 是 "幫忙做事" 那它永遠不會被觸發，因為 Claude Code 不知道什麼情況算「做事」。

檔案位置錯了。全域 agent 放 ~/.claude/agents/，專案級放 .claude/agents/（專案根目錄下）。放錯位置就讀不到。

YAML 格式錯誤。Frontmatter 的縮排和引號要正確。description 值有特殊字元（冒號、引號）的時候要用雙引號包起來。

model 名稱打錯。只接受 sonnet、opus、haiku。打成模型全名（像 claude-sonnet-4-6）不一定能解析。

從這裡開始

如果你從來沒用過自訂 Agent，從一個開始就好。

建議第一個做 code-reviewer。理由很簡單——你每天都在寫 code，每天都需要 review。弄一個 code-reviewer agent，讓它在你寫完 code 後自動跑一遍。用兩三天之後你會開始注意到：它每次都抓到什麼、漏掉什麼、什麼建議是有用的、什麼是噪音。

根據這些觀察去調整 system prompt。把它常抓到的好東西加強，把噪音的部分收窄。

然後再加第二個、第三個。不要一次搞十個——每加一個 agent 都需要觀察和調整。就像帶新人一樣，一次帶太多誰都帶不好。

整套自訂 Agent 的核心就是一份 Markdown 檔案。不需要學新語言、不需要裝額外的套件、不需要設定任何 server。你會寫 Markdown，你就會組 AI 團隊。

真正困難的不是寫 agent——是想清楚你的工作流程裡，哪些環節可以獨立出來交給一個專門的角色。這個思考過程本身，比任何工具都值錢。

參考來源：Create custom subagents — Claude Code Docs
參考來源：Claude Code Agents & Subagents Complete Guide — SkillsPlayground