使用手冊

方法拆解 · Agent Orchestration

Claude Code 代理編排方法拆解手冊

Boris Cherny（Claude Code 負責人）公開分享的代理編排方法：並行 agent 艦隊、Explore/Plan/Review sub-agent 架構、Stop hook 自主 loop、CLAUDE.md 制度記憶、MCP 工具控制，以及逐步複製此工作流的操作步驟。指令依官方文件查證。

Boris Cherny 是 Anthropic Claude Code 的負責人。他公開說明自己的工作方式：日常同時開 10–15 個 session，跨多個 git worktree 隔夜執行數百個背景 agent。本手冊將此方法拆成可操作的步驟：並行艦隊配置、sub-agent 架構設計、Stop hook 自主 loop、CLAUDE.md 制度記憶，以及 MCP 工具控制。指令依官方文件查證。

閱讀時間
8 分
更新日期
開啟原始報告
日常並行 Session
10–15
隔夜背景 Agent
100s+
內建 Sub-agent 類型
3
外部工具控制
MCP
本頁章節

01他到底在做什麼

從撰寫程式到編排 AI 工程隊

Boris Cherny 是 Claude Code 的建造者，也是其深度使用者。他公開表示已鮮少直接手寫程式，工作重心轉為編排與審查 AI agent：拆分任務、設定權限護欄、審查產出、將錯誤轉化為規則。

此方法基於 Claude Code 的三個核心原語：session（可並行、可跨裝置遙控）、sub-agent（在獨立 context 中執行研究或修改，僅回傳摘要），以及 memory / hooks / MCP（讓代理記住規則、自主完成任務、並操作外部工具）。掌握這三層即可依此方法建構自己的代理工作流。

  1. Explore

  2. Plan

  3. 並行執行

  4. Review / 測試

  5. 寫回 CLAUDE.md

「I have a Claude that prompts other Claudes.」（我有一個 Claude，專門指揮其他 Claude。）

— Boris Cherny，Head of Claude Code（公開分享）

02並行艦隊 · Parallel Sessions

日常10–15 個並行 Session，隔夜擴展至數百個背景 Agent

Cherny 公開說明他的工作規模：日常同時開 10–15 個 Claude Code session；遇到深度、長時間、可平行的任務，則擴展至跨多個 git worktree、隔夜執行數百個背景 agent。規模化的核心機制是 git worktree：讓每個 agent 在各自獨立的工作目錄與分支上執行，互不衝突。

bash
# 每個平行任務一個 worktree + 分支,互不干擾
git worktree add ../app-feature-a -b feature-a
git worktree add ../app-feature-b -b feature-b

# 在各自目錄開獨立 session
(cd ../app-feature-a && claude) &
(cd ../app-feature-b && claude) &

跨裝置遙控:手機接手終端機的 session

多 session 並行時，需要跨裝置監控。Cherny 在 /config 中啟用了「Enable Remote Control for all sessions」，並在 X 上說明了跨裝置搬移 session 的方式。兩個方向對應兩個指令：

bash
# 把「本機正在跑」的 session 推到手機 / 網頁去控制
/remote-control

# 把「雲端 / 手機」的 session 拉回本機終端機繼續
claude --teleport      # 或在對話中輸入 /teleport

03Sub-agent 架構

依任務類型委派具專屬工具權限的Sub-agent

面對複雜任務，Claude Code 將工作委派給 sub-agent。每個 sub-agent 在獨立的 context window 中執行，擁有各自的 system prompt、工具清單與權限模式，完成後僅將摘要回傳主對話。此架構有四項效益：不污染主 context、以工具白名單強制護欄、跨專案複用 agent 定義、對不需要高階模型的階段降級為較低成本的模型（如 Haiku）。Claude 依每個 sub-agent 的 description 欄位決定何時委派。

內建 Sub-agent模型 / 工具對應 Cherny 的「角色」
ExploreHaiku · 唯讀**探索代理。**掃描 codebase、查找檔案、理解脈絡。可指定 quick / medium / very thorough 三種徹底度。
Plan繼承主對話 · 唯讀**規劃代理。**在 plan mode 下先研究再提出工程方案，修改 code 前完成設計決策。
General-purpose繼承主對話 · 全工具**執行代理。**適用需同時探索與修改、多步驟、撰寫測試並迭代的複雜任務。

重要限制：sub-agent 不能再委派 sub-agent（無巢狀），此設計防止失控遞迴。大規模並行依賴多個獨立 session（背景 agent），而非無限巢狀。

自訂 sub-agent

對於重複性委派的工作類型，可將其封裝為自訂 sub-agent。使用 /agents 互動建立，或手動撰寫含 YAML frontmatter 的 Markdown 檔，存放至 ~/.claude/agents/（個人用，跨專案可用）或專案的 .claude/agents/。

markdown
# frontmatter 決定身分、派工時機、工具與模型
---
name: code-reviewer
description: 主動審查 diff,挑出正確性、可讀性與最佳實踐問題
tools: Read, Grep, Glob          # 唯讀護欄:不給 Write/Edit
model: sonnet
---
你是一位資深工程師。針對改動的檔案,逐項說明問題、
附上目前程式碼與改進版本,並標出風險等級。

04自主 Loop 與驗證

以 Stop Hook 與工具白名單實現無人值守自主 Loop

長時間無人值守任務的兩個前提：背景 agent 加上 hooks。核心做法是預先將代理需要的工具加入白名單，避免執行期跳出權限詢問。Stop hook 在代理嘗試結束時觸發，可在此檢查任務是否實際完成，未完成則讓代理繼續執行，形成自主 loop。

驗證由 Review 代理負責：自動撰寫測試、透過瀏覽器擴充實際操作 UI、執行並在出錯時迭代，直至測試全數通過。此驗證步驟使代理產出具備獨立驗證依據，而非僅依賴模型的自我判斷。

json
// 代理嘗試停止時觸發,可在此驗證/接手,避免半途而廢
{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command",
          "command": "npm test --silent || echo 'tests failing — keep going'" }
      ] }
    ]
  }
}

05制度記憶 · CLAUDE.md / AGENTS.md

將代理錯誤寫入 CLAUDE.md 作為永久規則

控制多個代理的行為並防止重複犯錯，Cherny 的團隊使用 CLAUDE.md（或 AGENTS.md）。機制直接：每當代理出錯，立即將修正規則寫入此檔案。此檔案在 repo 被讀取時自動載入，等同於為後續所有代理提供一份「本 codebase 的安全操作規則」，持續累積。

markdown
# Project rules for agents

## 資料庫
- 永遠用 repository 層,不要直接寫原生 SQL(會繞過稽核)。

## 測試
- 改任何 API 一定要更新 contract test,跑 `npm run test:contract`。

## 踩雷紀錄(每次出包就追加一條)
- 2026-05-xx:agent 曾在 prod migration 直接 DROP 欄位 → 一律先寫 reversible migration。

代理犯錯可以接受，同一個錯重犯兩次無法接受。修正寫進 CLAUDE.md，規則即時生效，後續代理不再重犯。

— Cherny 團隊的制度記憶做法

06工具控制 · MCP

透過 MCP 讓代理直接操作外部系統

Cherny 的代理透過 Model Context Protocol（MCP） 取得外部系統的操作權限，可接入公司工具鏈：從 BigQuery 查詢資料、在 Slack 搜尋訊息並發送更新、從 Sentry 擷取生產環境錯誤日誌。此機制使代理能夠閉環處理「查資料 → 修改 code → 通報結果」的跨系統任務。

bash
# 以 CLI 加一個 MCP server(例:Sentry)
claude mcp add sentry --transport http https://mcp.sentry.dev/mcp

# 之後代理就能在對話裡直接查 Sentry 錯誤、拉 BigQuery、發 Slack
/mcp                    # 檢視已連線的 MCP server 與工具

資料 · 01

BigQuery

拉數據

讓代理直接查詢資料倉儲，以實際數字佐證決策與報告。

協作 · 02

Slack

搜尋與通報

搜尋訊息脈絡，將進度或結果發回指定頻道，保持人與代理的資訊同步。

可觀測 · 03

Sentry

抓錯誤日誌

從生產環境擷取 error log，供代理據此定位並修復問題。

07完整實戰示例 · 情境演示

從單一任務到多 agent 接力完成的完整流程

以下為示意流程（說明指令與分工，非實測逐字稿）：將一個含 bug 的功能提交給 Claude Code，示範 Explore/Plan 委派、並行修復、自動驗證、跨裝置監控，以及最後將教訓寫回 CLAUDE.md 的完整迴圈。

~/app · claude code


$ You ›
  結帳頁偶發算錯運費,順便把折扣碼邏輯重構。盡量平行。


# [委派 Explore · very thorough · Haiku]
  # → 找到 shipping.ts、discount.ts 與 3 處共用的 price util
# [委派 Plan · plan mode]
claude: Claude(Plan)›
  運費 bug 來自 float 累加;折扣重構建議拆成獨立 module。
  建議開兩個 worktree 平行做,互不阻塞。


$ You › 照做。
# [git worktree add ../app-shipping -b fix-shipping]
# [git worktree add ../app-discount -b refactor-discount]
hl: agent A(fix-shipping) 改用整數分計算 → 寫 regression test
hl: agent B(refactor-discount) 抽出 discount module → 補單元測試


# [Review 代理:跑測試 + 用瀏覽器點過結帳流程]
claude: I SEE THE ISSUE — 折扣與運費同時套用時順序錯。修正並重驗 ✓


# [Stop hook:npm test → 全綠,允許停止]


$ You › /remote-control
# [出門通勤,改用手機盯兩個 worktree 的收尾與 PR]


$ You › 把這次的順序 bug 寫進 CLAUDE.md。
ok: 已追加規則:折扣與運費套用順序需先 freight 後 discount + 對應測試。
ok: PR ×2 已開,測試全綠。下次代理不會再犯同一個錯。

Explore 找脈絡，Plan 定方向，worktree 並行執行，Review 驗證，CLAUDE.md 記錄規則。此五步構成一輪完整的代理工作迴圈。

— Cherny 代理工作法的一輪

08先看清楚這些

使用前須知：自主執行仍需護欄與驗證

09自己照做 · Replicate It

五個步驟建立自己的代理工作流

**1. 啟用遠端控制。**在 /config 開啟「Enable Remote Control for all sessions」，使任何 session 均可透過 /remote-control 推送至手機，或以 claude --teleport 拉回終端機。

**2. 建立第一份 CLAUDE.md。**記錄專案的強制規則（資料庫存取方式、測試要求、命名規範、危險操作限制）。之後每次代理出錯，追加一條修正規則。

**3. 定義常用 sub-agent。**用 /agents 建立 code-reviewer 或 test-writer，存放於 ~/.claude/agents/，指定唯讀工具清單與較低成本的模型，並開啟持久記憶。

**4. 以 worktree 實現並行。**每個獨立任務建立一個 git worktree 與對應分支，先以 2–3 個 session 並行執行，確認無衝突後再擴大規模。

**5. 接入 MCP 並設定 Stop hook。**使用 claude mcp add 接入 Sentry / Slack / BigQuery 等工具，並設定 Stop hook 執行完成驗證，使代理能自主跑完完整迴圈。

延伸閱讀與來源

① 官方文件 · Create custom subagents：Explore/Plan、frontmatter、/agents。 ② 官方文件 · Remote Control / teleport：跨裝置遙控與傳送。 ③ Boris Cherny · X(@bcherny)：本人公開分享的 15 條技巧。 ④ The Pragmatic Engineer · Building Claude Code with Boris Cherny。

參考資料