Claude Code Agent Harness 架構解析：從 /loop 到數千 Agents 的實作藍圖

AI
, , , ,
1

深入解析 Boris Cherny 的 Claude Code Agent Harness 架構，從 /loop 工作流、Docker 隔離、task lock 到數百個平行 agents 的擴展模型，一次掌握 agentic engineering 的完整實作藍圖與安全考量。

在 AI 代理（Agent）開發領域，如何設計一個可擴展、可維護的多代理架構，是許多工程團隊正面臨的挑戰。Boris Cherny 在 agentic engineering 領域的實作經驗，特別是 Claude Code Agent Harness 的設計思維，提供了一套值得參考的架構藍圖。

本文將深入解析 Boris Cherny 的 /loop 工作流、Anthropic 公開展示的 multi-agent harness 原型，以及兩者之間的關鍵差異，幫助你理解如何從單一 agent 擴展到數百甚至數千個平行 agents。

兩個容易混淆的概念

在深入探討之前，必須先釐清兩個常被混為一談的概念。

Boris Cherny 的 /loop 與 Routines 工作流

Boris Cherny 的 /loop 是一個個人化的開發工作流，核心思維是讓單一 agent 進入一個「永久迴圈」（permanent loop），持續執行任務、檢視結果、調整策略，直到任務完成。這種模式特別適合需要反覆迭代的開發任務。

Anthropic 的 Multi-Agent Harness 原型

另一方面，Anthropic 在公開場合展示的 multi-agent harness 原型，則是一個更完整的架構設計，包含：

  • Docker 容器隔離：每個 agent 在獨立環境中執行
  • Bare Git Repository：作為任務分發與結果回收的媒介
  • Task Lock 機制：確保每個任務只被一個 agent 執行
  • Agent Loop：持續輪詢新任務並回報結果
  • CI 驗證：自動化驗證 agent 的輸出品質

核心架構元件

Docker 隔離環境

每個 agent 在 Docker 容器中執行，確保：

  • 依賴套件不會互相衝突
  • 資源使用可被限制與監控
  • 執行環境可重現
  • 安全性隔離，防止惡意程式碼影響主機

Task Lock 與任務分配

Task lock 是確保任務不會被重複執行的關鍵機制。當一個 agent 取得任務後，會先鎖定該任務，完成後再解鎖。這在平行架構中至關重要，避免多個 agents 同時處理同一個任務。

Sub-Agent 的 Context Isolation

在大型架構中，每個 sub-agent 應該擁有獨立的 context，這意味著：

  • 每個 agent 只看到自己需要的資訊
  • 角色分工明確（例如：一個負責寫程式碼、一個負責寫測試、一個負責 code review）
  • 避免 context 過長導致的效能衰退

驗證器（Verifier）設計

驗證器是確保輸出品質的關鍵。在 Boris 的架構中，驗證器通常與 CI 整合，透過以下方式驗證 agent 的輸出：

  • 單元測試與整合測試
  • 靜態程式碼分析
  • 建置（Build）驗證
  • 人工審查（Human-in-the-loop）

從單一 Agent 到數千 Agents 的擴展模型

階段一：單一 Agent 的永久迴圈

一切從單一 agent 開始。這個 agent 進入一個無限迴圈，不斷地：

  1. 檢查是否有待辦任務
  2. 執行任務
  3. 驗證結果
  4. 提交結果
  5. 回到步驟 1

階段二：加入平行處理

當單一 agent 的處理速度成為瓶頸時，可以水平擴展多個 agents。此時需要：

  • 任務佇列（Task Queue）
  • 分散式鎖定（Distributed Lock）
  • 結果彙整機制

階段三：大規模編排

當規模來到數百至數千個 agents 時，需要更精細的設計：

  • 分層架構：主 agent 管理子 agents，子 agents 再管理更小的 agents
  • 容錯機制：單一 agent 失敗不影響整體任務
  • 資源調度：動態分配計算資源

實作藍圖

步驟一：定義任務邊界

明確界定哪些任務適合交給 agent 執行，哪些需要人工介入。不是所有任務都適合自動化。

步驟二：建立開發環境

# 建立專案目錄
mkdir agent-harness && cd agent-harness

# 初始化 Git 儲存庫
 git init --bare tasks.git

# 建立 Docker 映像檔
docker build -t agent-runner .

步驟三：實作 Agent Loop

核心的 agent loop 邏輯如下：

  1. 從任務佇列取得任務
  2. 取得 task lock
  3. 在 Docker 容器中執行 agent
  4. 收集輸出與日誌
  5. 執行驗證器
  6. 提交結果並釋放 lock

步驟四：建立 CI 管線

將驗證流程整合進 CI，確保每次變更都經過完整測試。

限制與安全風險

已知限制

  • Context 長度限制：即使有 context isolation，單一 agent 能處理的資訊量仍有上限
  • 成本控管：數百個 agents 同時執行，API 成本可能快速累積
  • 除錯困難：當架構複雜到一定程度，追蹤問題的難度呈指數成長

安全考量

  • 提示注入（Prompt Injection）：agent 可能被惡意輸入誘導執行非預期操作
  • 資源耗盡攻擊：惡意任務可能消耗大量計算資源
  • 資料外洩：確保 agent 不會將敏感資料寫入不該寫入的地方

建議的安全措施：

  • 最小權限原則：agent 只擁有完成任務所需的最小權限
  • 網路隔離：限制 agent 的網路存取
  • 稽核日誌：記錄所有 agent 的操作行為

結論

Boris Cherny 的 Claude Code Agent Harness 架構提供了一個從單一 agent 到大型多代理系統的完整演進路徑。核心思維在於：先以 /loop 建立單一 agent 的高效工作流，再透過 Docker 隔離、task lock、CI 驗證等機制，逐步擴展到數百甚至數千個平行 agents。

對於正在評估或導入 agentic engineering 的團隊，建議從小型專案開始，先熟悉單一 agent 的 loop 模式，再逐步導入平行架構。架構的複雜度應該跟隨實際需求成長，而非為了使用而使用。