Boris Cherny 的 Agent Harness 與 Loop 設計方法

01　結論先行

Boris 的核心不是「寫更厲害的 prompt」，而是把自己從逐輪操作員，提升成定義目標、邊界、驗證、停止條件與資源配置的人。

這套方法最適合「驗證便宜」的任務：CI 修復、auto-rebase、flaky test、migration、批次 refactor、效能 hill-climbing、回饋聚類與 repo audit。若成功無法被機器可靠判定，多跑 Agent 只會放大錯誤與審查債務。

02　身分與證據邊界

網路文章經常把 /loop、Ralph loop、/goal、Routines、Dynamic Workflows 與 Agent Teams 混稱為「loop」。本報告依觸發條件、停止條件與 orchestration holder 分開處理。

03　方法演進：從人工並行到程式化編排

04　Boris 的七個設計思維

05　可重建的 Agent Harness 架構

下面不是 Boris 公開的原始碼，而是把他的第一手描述、官方 Claude Code primitives 與現行文件組合後，得到的最小一致架構。

最關鍵的控制關係

人類：定義 Outcome + Guardrails + Exit Criteria + Budget
  ↓
Trigger：時間到、事件到、或上一輪結束
  ↓
Orchestrator：發現工作 → 分解 → fan-out → 聚合 → 交叉驗證
  ↓
Worker：在隔離環境執行，產生 commit / PR / report
  ↓
Verifier：依外部可觀測證據判定 PASS / RETRY / STOP
  ↺ 若 RETRY，帶著「失敗證據」進入下一輪

06　他使用 /loop 的方式

Boris 描述的是「讓 Claude 用 cron 在未來反覆執行一個 job」。他的實際案例都有低成本、可輪詢、可修復或可聚合的輸出。

現行 Claude Code 語法

# 固定每 5 分鐘執行
/loop 5m check whether CI passed and address any review comments

# 不指定間隔：Claude 每輪依狀態選擇 1 分鐘至 1 小時
/loop check the deploy and fix any issue you can verify

# 定時重跑一個可由模型自行呼叫的 Skill
/loop 20m /review-pr 1234

# 使用內建 maintenance prompt，或專案的 .claude/loop.md
/loop

# 查看／取消排程，可直接用自然語言
what scheduled tasks do I have?
cancel the deploy check job

/loop、/goal、Routines、Dynamic Workflows 的差異

07　「數百個 Sub-agent」到底如何成立

不是把數百個 agents 全部塞進同一個對話。現行 Dynamic Workflow 把 orchestration 寫成 plain JavaScript，讓中間結果存在 script variables；主對話只收到最後聚合結果。官方文件把這件事描述為「plan moved into code」。

export const meta = {
  name: 'audit-routes',
  description: 'Audit route handlers, verify findings, return one report'
}

const inventory = await agent('List every route handler.', {
  schema: routeListSchema
})

const findings = await pipeline(inventory.files, file =>
  agent(`Audit ${file}. Return structured evidence.`, { label: file })
)

const verified = await pipeline(findings.filter(Boolean), finding =>
  agent(`Independently challenge this finding: ${JSON.stringify(finding)}`)
)

return await agent(`Rank and deduplicate verified findings: ${JSON.stringify(verified)}`)

為什麼這種結構比「主 Agent 一直開 Sub-agent」穩定

• 決策狀態在程式裡：loop、branch、重試、schema validation 與聚合不必佔主模型 context。
• 每個 worker 只拿局部問題：減少 context 污染，也能使用結構化輸出。
• 品質模式可重複：maker → independent reviewer → synthesizer，不靠每次臨場想起。
• 可觀測：/workflows 顯示 phase、agent count、token、elapsed time，能 pause、resume、restart、kill。
• 可保存：成功的動態 script 可存進 .claude/workflows/，變成團隊共用 slash command。

08　Boris 方法的最小可重建藍圖

以下是從其公開方法推導出的 production-oriented 規格；不是宣稱為 Boris 私人設定的逐字複製。

A. Loop Contract

Objective: 保持指定 PR 可合併
Scope: 僅能修改該 PR branch；不得碰 production secrets
Discovery: 讀取 CI、review comments、merge conflict、branch freshness
Action: 一次只處理一個可重現 failure；建立最小修正
Verification: 對應 test + full required CI；列出 command 與 exit code
Stop: CI 全綠、無未處理 review、無 conflict；或連續兩輪無進展
Budget: 最多 12 輪／指定 token 或美元上限
Escalation: 權限不足、需求矛盾、production 風險時停止並留下報告
Artifact: commit、PR comment、執行證據、下一步

B. 三層工作分配

C. 控制面必要欄位

• 每個 run 有唯一 ID、來源 trigger、owner、repo、branch／worktree。
• worker 的 tool allowlist、denylist、sandbox 與 secrets scope 明確。
• 有 max turns、max budget、timeout、agent concurrency、total agent cap。
• 每輪記錄 input、tool calls、diff、tests、verdict、token、cost、terminal state。
• 成功、失敗、無進展、需人工、budget exhausted 分成不同終態。
• 寫入工作以 PR／commit 為輸出，不直接合併高風險變更。
• maker 與 verifier 的角色／context 分離；高風險驗證使用 deterministic checks。
• 每次模型升級重跑 ablation；移除已不再產生可測量增益的 instructions。

09　網路討論：支持、質疑與裁決

社群中最有價值的共同結論：存活下來的 unattended loops 通常是「check-shaped」——它們觀察、比較、修復、再次測量；不是把模糊願望丟給 Agent 後期待它無限自主。

10　限制、風險與適用邊界

六個常見失敗模式

1. 沒有真正的 exit condition：「讓 codebase 更好」會形成無限工作面。
2. 同一模型自產自評：worker 與 judge 共享盲點，容易把合理敘述誤當證據。
3. 共享 checkout：平行 agents 互相覆寫，最後成本轉移到 merge conflict。
4. 重試沒有新資訊：同 prompt、同 context、同工具反覆執行，只會穩定重現失敗。
5. token 沒有上限：fan-out × retry × evaluator 會快速乘法放大。
6. 人類喪失理解：大量未閱讀 code 形成 comprehension debt；出現事故時沒有人能快速判斷變更意圖。