Claude Code Custom Agent 完整指南：打造會思考的自動化角色

Custom Agent 是 Claude Code 最強大的升級。當你有一個複雜角色需要跨多個任務重複執行，且這個角色需要自行決策、規劃方法時，Custom Agent 比 Skill 更合適。本篇教你如何定義 Agent 角色、撰寫 systemPrompt、配置工具存取權限、建立記憶庫，以及用 4 個真實案例驗證整個過程。

何時升級到 Custom Agent？判斷標準

Custom Agent 適合「需要自主規劃和決策的角色」。以下判斷標準會幫你決定：

1. 跨任務的相同角色：同一個人（代碼審查員、測試工程師、架構師）在 3+ 個不同項目中重複出現
2. 自主決策：Agent 不只執行流程，還要判斷「下一步該怎麼做」
3. 記憶需求：Agent 需要記住過去的決策、學到的東西，應用到新情況
4. 工具組合：Agent 需要整合多個工具（代碼庫、測試框架、API 等）來完成任務

Custom Agent 文件結構

每個 Custom Agent 放在 ~/.claude/agents/{agent-name}/ 目錄下。基本結構：

~/.claude/agents/code-reviewer/
├── AGENT.md           # Agent 定義 + systemPrompt
├── memory.md          # 記憶庫（可選）
└── tools.json         # 工具存取權限配置

AGENT.md：定義角色和 systemPrompt

---
name: code-reviewer
description: Autonomous code review agent for pull requests
type: reviewer
model: opus
---

# Code Reviewer Agent

## 角色定義

你是一個專業的代碼審查員。你的職責是：

1. **檢查代碼品質**
   - 遵循 SOLID 原則
   - 命名清晰、邏輯簡潔
   - 錯誤處理完整

2. **驗證測試覆蓋**
   - 新功能必須有測試
   - 邊界情況涵蓋
   - 整合測試通過

3. **安全審查**
   - 無 SQL injection
   - 無認證繞過
   - 敏感數據妥善處理

4. **性能檢查**
   - 無 N+1 查詢
   - 無無限迴圈
   - 資源洩漏防護

## 決策矩陣

| 問題類型 | 優先級 | 行動 |
|---------|--------|------|
| 安全漏洞 | 🔴 必須 | 要求修正後才能合併 |
| 測試缺失 | 🔴 必須 | 要求添加測試 |
| 性能問題 | 🟠 重要 | 提出改進建議 |
| 風格違規 | 🟡 可選 | 提醒但允許合併 |
| 最佳實踐 | 🟡 可選 | 提供建議供參考 |

## 記憶需求

- 記住本專案的命名習慣、架構模式、測試框架
- 記住「上次我們學到的教訓」（例：某個模式導致的問題）
- 記住團隊的標準和偏好

工具存取權限配置

在 tools.json 中定義 Agent 可以使用哪些工具：

{
  "tool_permissions": [
    {
      "tool": "bash",
      "allow_patterns": [
        "git diff",
        "git log",
        "npm test",
        "npm run lint",
        "pytest --cov"
      ],
      "deny_patterns": [
        "rm -rf",
        "git push",
        "git reset --hard"
      ]
    },
    {
      "tool": "read",
      "allow_patterns": [
        "src/**/*.{js,ts,py}",
        "tests/**/*",
        ".env.example"
      ],
      "deny_patterns": [
        ".env",
        "**/*.key",
        "**/*secret*"
      ]
    },
    {
      "tool": "github_api",
      "allow_patterns": [
        "get /repos/{owner}/{repo}/pulls/{number}",
        "get /repos/{owner}/{repo}/statuses/{sha}",
        "post /repos/{owner}/{repo}/pulls/{number}/reviews"
      ]
    }
  ]
}

記憶庫建立

Agent 可以建立 memory.md 來記住重要信息：

# Code Reviewer Memory

## 專案風格

### 命名習慣
- Classes: PascalCase (UserService, PaymentProcessor)
- Functions: camelCase (getUserById, processPayment)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_TIMEOUT)
- Private: _prefixWithUnderscore

### 架構模式
- Controllers → Services → Repositories → Models
- 所有對外接口必須有 DTO
- 所有 API 端點必須有速率限制

## 常見問題歷史

### 問題 1：N+1 查詢（2024-Q1）
- **症狀**：查詢 100 個用戶導致 101 次數據庫查詢
- **根本原因**：使用 ORM lazy-loading
- **修復**：改用 join() 或 select_related()
- **檢查清單**：审查所有 ORM 查詢，確認無 lazy-loading

### 問題 2：未驗證的文件上傳（2024-Q2）
- **症狀**：用戶可以上傳任何文件類型，導致 RCE
- **根本原因**：只檢查 MIME type，未檢查內容
- **修復**：改用簽名驗證 + 沙箱掃描
- **檢查清單**：所有上傳必須經過簽名驗證

## 測試框架習慣

- 單元測試：pytest + fixtures
- 整合測試：docker-compose 環境 + pytest
- E2E 測試：Selenium/Cypress
- 覆蓋要求：≥ 80%

Custom Agent 的 4 個真實案例

案例 1：代碼審查 Agent（API 專案）

背景：團隊有 3 個項目（API、Web、Mobile），每個都有不同的 PR 進度。需要一個一致的審查標準。

Agent 定義：

• 🎯 角色：代碼審查員
• 🧠 記憶：每個專案的風格習慣 + 常見錯誤歷史
• 🛠️ 工具：git diff、GitHub API、pytest、代碼分析工具
• 📊 輸出：結構化審查評論 + 安全/測試/性能 3 個評分

結果：每個 PR 審查時間從 30 分鐘降到 5 分鐘，且審查一致性提升 95%。

案例 2：測試工程師 Agent（跨項目自動化測試）

背景：4 個項目的整合測試環境不一致。需要 Agent 自行判斷各項目的測試框架、設置環境、執行測試。

Agent 定義：

• 🎯 角色：自動化測試工程師
• 🧠 記憶：每個專案的測試框架 + 已知的不穩定測試 + 環境配置
• 🛠️ 工具：docker、bash、pytest/jest/mocha、GitHub Actions API
• 📊 輸出：測試覆蓋率報告 + 失敗分析 + 根本原因建議

結果：測試失敗不再是「為什麼失敗」而是「根本原因是什麼」，故障排除時間減少 70%。

案例 3：架構審查 Agent（系統設計諮詢）

背景：新功能設計前需要架構審查，確保不會導致後期的重構。Agent 需要理解當前系統架構，提出可維護的設計。

Agent 定義：

• 🎯 角色：系統架構師
• 🧠 記憶：當前系統架構圖 + 設計決策歷史 + 技術債清單
• 🛠️ 工具：代碼庫讀取、設計圖工具、數據庫架構查詢
• 📊 輸出：設計評估 + 風險分析 + 備選方案 (3 個等級)

結果：早期抓出設計問題，後期重構時間減少 80%。

案例 4：數據管道 Agent（ETL 自動化）

背景：多個數據源的 ETL 流程不一致。Agent 需要自行偵測數據異常、調度管道、驗證結果。

Agent 定義：

• 🎯 角色：數據工程師
• 🧠 記憶：各數據源的架構 + 已知異常情況 + 修復歷史
• 🛠️ 工具：SQL、數據庫連接、bash、監控 API
• 📊 輸出：管道執行日誌 + 數據品質評分 + 異常告警

結果：數據異常檢測從手工變自動，平均 MTTR（故障排除時間）從 4 小時降到 15 分鐘。

systemPrompt 撰寫技巧

好的 systemPrompt 是 Custom Agent 的靈魂。以下技巧會幫你寫出高效的 prompt：

結構 1：身份 + 職責 + 決策矩陣

你是 [角色名稱]。你的職責是：
1. [主要職責 1]
2. [主要職責 2]
3. [主要職責 3]

決策矩陣：
| 情況 | 優先級 | 行動 |
|------|--------|------|
| [情況 A] | 🔴 必須 | [你應該做 X] |
| [情況 B] | 🟠 重要 | [你應該做 Y] |

你的記憶：[Agent 應該記住的東西]
你的工具：[你可以使用的工具列表]

結構 2：決策樹（if-then 邏輯）

當遇到 [情況] 時：
- 如果 [條件 A]，則 [行動 A]
- 如果 [條件 B]，則 [行動 B]
- 否則 [默認行動]

例子：
當審查代碼時：
- 如果 [發現 SQL injection 漏洞]，則 [標記為 🔴 必須修正]
- 如果 [測試覆蓋 < 80%]，則 [標記為 🟠 要求添加測試]
- 如果 [風格不一致但邏輯正確]，則 [提出建議但允許合併]

結構 3：輸出格式定義

你的輸出應該遵循以下格式：

## [任務] 報告

### 摘要
[一句話總結]

### 發現
- 🔴 [必須項 1]
- 🟠 [重要項 2]
- 🟡 [可選項 3]

### 建議
1. [短期改進]
2. [中期改進]
3. [長期改進]

### 審查評分
| 維度 | 評分 | 說明 |
|------|------|------|
| 安全性 | 8/10 | [說明] |
| 測試 | 7/10 | [說明] |
| 性能 | 9/10 | [說明] |

何時停止改進 Agent，考慮 Agent Team？

當你有多個 Agent 需要協作時，考慮 Agent Team：

• 單一 Agent：「代碼審查員」審查所有 PR
• Agent Team：「代碼審查員」+ 「測試工程師」+ 「性能分析師」協作審查 PR

Agent Team 可以並行工作、互相驗證、降低單點失敗風險。但複雜度也提升了。

總結

Custom Agent 是「會思考的角色」。它不只執行流程，還能根據上下文自主決策、應用記憶、整合多個工具。如果你發現自己需要「一個人」來重複執行複雜工作，就該考慮 Custom Agent 了。

下一步：識別你的第一個重複角色。寫出清晰的 systemPrompt，配置工具權限，建立記憶庫。測試一個完整工作流，驗證 Agent 的決策品質。從簡單開始，逐步改進。