使用 Claude 進行 Agent 框架工程：從單一 Agent 到自我優化系統的 14 個步驟指南。

每個人都在談論循環。幾乎沒有人在談論循環運行在什麼之上。9 成的開發者都在預設的 Harness 上運行 Claude Code，沒有規則、沒有子 Agent、沒有掛鉤、沒有記憶。

然後他們納悶為什麼他們的循環產出垃圾。真相很簡單：循環的好壞取決於它底層的 Harness。這是一份打造 Harness 的 14 步驟路線圖——從單一 Agent 到一個能自我改進的系統。

追蹤我的 Substack 以獲取最新的 AI Alpha：

movez.substack.com

循環工程——建立一個系統來定時提示你的 Agent——本月份獲得了所有關注。但撰寫了關於循環長文的 Addy Osmani，卻細心地指出了其底層的關鍵：

「循環工程位於 Harness 的上一個樓層。Harness 是單一 Agent 運行的環境。循環就是 Harness，但它按計時器運行、產生輔助角色、並自我餵養。」

Harness 工程就是設計那個環境：模型、工具、權限、上下文、記憶。

這是個不那麼光鮮的層面——但正是它決定了上層的一切是否能正常運作。一個好的循環配上一個糟糕的 Harness，只是一個快速地大規模產出垃圾的方式。

14 個步驟。3 個層級。一切其他東西的基礎。

第一部分 · Harness 是什麼

01. Harness 是單一 Agent 運行的環境。

剝去術語，一個 Harness 就是四樣東西：模型負責思考、工具它可以接觸、權限這些工具的設定、以及上下文它每次運行開始時讀取的內容。

這就是整個表面。其他的一切——子 Agent、掛鉤、記憶——都是塑造這四者之一的方式。

Harness 比人們想像中更重要的原因：Agent 是一個 while True 循環，它選擇一個工具、執行它、查看結果、然後決定下一步行動。

Harness 定義了存在哪些工具、Agent 被允許做什麼、以及它在開始時知道什麼。 同樣的模型，不同的 Harness，完全不同的 Agent。

02. 整個 Harness 都住在一個資料夾裡：.claude/

所有塑造你的 Agent 的元素都位於專案根目錄的一個單一目錄中。學會這個佈局，你就能一眼看懂任何人的 Harness：

1.claude/
2├─ CLAUDE.md          # 固定事實——每次工作階段都讀取
3├─ settings.json      # 權限、模型、掛鉤
4├─ .mcp.json          # 外部工具連接
5├─ rules/             # 路徑範圍行為
6│  ├─ tests.md
7│  └─ python-types.md
8├─ agents/            # 子 Agent 定義（每行約 30 行）
9│  ├─ reviewer.md
10│  └─ eval-runner.md
11├─ skills/            # 可重複使用的工作流程
12│  └─ pr-checklist/
13│     └─ SKILL.md
14└─ agent-memory/      # 在運行之間保留的內容
15   └─ STATE.md

區分一個整潔的 Harness 和一個混亂的 Harness 的一條規則是：保持它足夠小，讓你為每個檔案的存在都能解釋理由。 如果你說不出一個 rule、hook 或 subagent 是做什麼用的，就刪掉它。

03. Harness 與循環與系統。三個樓層，不要混為一談。

大多數「我的 Agent 設定一團糟」的問題來自混淆這三個樓層。把它們分清楚：

• Harness 是一個 Agent 所在的運行時。靜態設定：模型、工具、權限、上下文。本議題。
• 循環 會按計時器提示 Agent、產生輔助角色、自我餵養。它在 Harness 之上 運行。
• 自我改進系統 是一個循環加上能夠複合的記憶——每次運行都讓下一次運行更銳利。

實際的版本：將固定事實放在上下文裡，強制規則放在掛鉤裡，程序放在技能裡，隔離放在子 Agent 裡。

把這些東西攪在一起——把強制規則放進 CLAUDE.md、用程序讓上下文膨脹——是不一致且成本高昂的 Agent 的根本原因。

04. 預設的 Harness。開箱即用的東西。

安裝 Claude Code，打開一個資料夾，你已經有了一個 Harness——只是一個空的。預設設定給你一個能幹的模型、內建工具（讀取、寫入、bash、搜尋）、以及所有風險操作的批准提示。沒有專案上下文、沒有自訂子 Agent、沒有記憶。

對於一次性任務，預設設定沒問題。對於你做超過一次的任何事情，預設設定會讓 Agent 每次工作階段都從頭推導你的專案、對安全操作要求批准、然後在你關閉終端機時忘記一切。

接下來的十個步驟是關於縮小這個差距。

05. CLAUDE.md：固定事實，保持簡短。

CLAUDE.md 在每次工作階段開始時被讀取。這是 Agent 對你專案的固定知識——慣例、架構、「我們不這樣做是因為那次事件」。

最常見的單一錯誤：讓它變成一個巨大的程序文件，導致每次工作階段都膨脹。

每天運行這個的實務人員的規則是：將主記憶體文件保持在約 500 個 token 以下。 固定事實放在這裡。

多步驟程序放在技能裡（步驟 8）。路徑特定的行為放在 rules/ 檔案中，範圍限定在它們適用的地方。如果 CLAUDE.md 的某個部分已經變成了一個程序而不是事實，它就屬於其他地方。

大聲朗讀你的 CLAUDE.md。每一行都應該是一個

事實

Agent 在每個工作階段都需要的事實（「我們用 pnpm，不是 npm」）。如果一行是

程序

（「要新增功能，首先……」），就把它移到技能裡。

如果它是一個資料夾的規則，就把它移到 rules/ 裡。

06. settings.json：權限和模型，設定一次就夠了。

預設的 Harness 會在每次風險操作前詢問。當你在看的時候這沒錯，但當你不在看的時候就錯了。settings.json 是你預先批准安全的東西、拒絕危險的東西、以及選擇運行哪個模型的地方。

1{
2  "model": "claude-sonnet-4-6",
3  "permissions": {
4    "autoApprove": [
5      "Read(*)", "Grep(*)",
6      "Bash(npm test)", "Bash(git status)"
7    ],
8    "deny": [
9      "Bash(rm -rf*)", "Bash(git push*)",
10      "Edit(.env*)", "Edit(secrets/*)"
11    ]
12  }
13}

測試哪些可以自動批准的標準：如果這搞砸了，撤銷它有多難？ 容易撤銷 → 自動批准。

難以撤銷（強制推送、刪除檔案、觸碰密碼）→ 一律拒絕或提示。如果你記錄了它，中間地帶也可以自動批准。

07. 子 Agent：為髒活準備的獨立上下文。

子 Agent 是從主 Agent 啟動的獨立 Claude 工作階段——它有自己的上下文視窗、自己的工具清單。重點不在於為了平行而平行。而是將噪音隔離在主上下文之外。

一個需要讀取 40 個檔案的研究任務、需要新觀點的審查環節、會產生大量日誌的評估運行——這些都應該放在子 Agent 中，這樣它們就不會污染主線程。

GIF

任何 Harness 中最有價值的子 Agent 是檢查主 Agent 所做工作的那個。模型審查自己的輸出對自己太寬容了；

一個擁有全新上下文視窗的獨立審查者會捕捉到寫作者說服自己接受的錯誤。這就是讓 Harness 之上的每個循環都值得信賴的「寫作者 vs 檢查者」分工。

08. 技能：Agent 重複使用的程序。

技能是一個 SKILL.md 檔案，Agent 會執行它——要么當你用 /skill-name 呼叫它時，要么當任務與其描述匹配時自動執行。

與子 Agent 不同，它在同一個上下文視窗中運行。它只是成為工作階段一部分的可重複使用指令。

建立一個技能的觸發條件：你注意到自己每次新對話都貼上同樣的指令。 這就是一個等待被建立的技能。一個 PR 檢查清單、一個評估程序、一個發布流程——寫一次，永遠呼叫。

而且因為技能是可重複使用的單元，它們是讓 Harness 隨著時間改進的原因：每次程序以新方式失敗時，你把教訓加入技能，下一次運行就會繼承它。

09. 掛鉤：模型無法幻覺的確定性規則。

到目前為止的一切都依賴模型理解你的指令。掛鉤則不然。

掛鉤是一個在 Agent 生命週期中的固定時間點觸發的 shell 命令——在工具運行前、檔案變更後、工作階段結束時——它的退出碼可以阻止這個動作。掛鉤是強制執行，CLAUDE.md 是建議。

有兩個掛鉤幾乎每個 Harness 都值得擁有：

• 一個 PreToolUse 閘門，可以確定性地阻止危險命令——rm -rf、讀取 .env、推送到主分支。退出碼 2 會在呼叫發生前阻止它。模型無法說服它繞過。
• 一個 PostToolUse 格式化工具，在每次編輯後運行你的 linter 或格式化工具。Agent 永遠不會送出未格式化的程式碼，因為 Harness 會自動格式化它。

1"hooks": {
2  "PreToolUse": [{
3    "matcher": "Bash",
4    "command": "./.claude/hooks/block-dangerous.sh"
5    // exit 2 = 在呼叫執行前阻止它
6  }],
7  "PostToolUse": [{
8    "matcher": "Edit|Write",
9    "command": "prettier --write \"$CLAUDE_FILE_PATH\""
10  }]
11}

使用掛鉤來處理任何必須發生或絕不能發生的事情——安全性、格式化、稽核日誌。

不要把它們用於需要判斷的情況；那是模型的工作。一個好的 Harness 有一兩個銳利的掛鉤，而不是二十個。

第三部分 · 讓它複合

10. 加入一個循環。現在 Harness 會按計時器運行。

一個設定好的 Harness 仍然等待你輸入。一個循環讓它自己運行。最簡單的版本是 Claude Code 中的 /loop——一個按節奏重複發生的提示。

將它與 /goal 配對，循環就會持續進行，直到一個客觀條件成立，由一個獨立的評分者檢查，而不是由 Agent 自己評分。

1> /loop 30m /goal 所有測試通過且 lint 乾淨。
2  分類新的失敗，在 claude/ 分支中起草修復。
3
4▲ Claude 使用你建立的 Harness：
5  - rules/ 用於慣例
6  - reviewer 子 Agent 檢查每個修復
7  - PreToolUse 掛鉤阻止推送到主分支
8✓ 循環中。獨立評分者決定「完成」。

注意剛才發生的事：循環並沒有增加智慧。它重新使用了 Harness 中的一切——規則、審查者子 Agent、安全掛鉤。一個好的 Harness 讓循環變得微不足道。這就是為什麼要先打好基礎。

11. 加入動態工作流程。Harness 自己編寫編排。

對於對單一循環來說過於複雜的任務——大規模平行、高度結構化、對抗性——Claude 可以在運行時即時編寫自己的 JavaScript Harness。

這就是一個動態工作流程：agent() 用於產生、parallel() 用於分叉、pipeline() 用於串流。它將你的 Harness 定義的子 Agent 組合成諸如「分叉並綜合」或「對抗性驗證」等模式。

與 Harness 工程的關聯：一個動態工作流程的好壞取決於它可以呼叫的子 Agent 和技能。

如果你的 Harness 有一個銳利的審查者子 Agent 和一個寫得很好的評估技能，工作流程就有好的零件可以編排。如果 Harness 是空的，工作流程就無從發揮。

工作流程是指揮，你的 Harness 是樂團。

12. 加入記憶。Agent 忘記的，Harness 記住。

這是將一個設定好的 Harness 轉變為一個真正能夠改進的系統的步驟。Agent 在每次運行之間忘記了一切。Harness 不需要。

一個狀態檔案——位於 agent-memory/ 中的一個 markdown 檔案，或是一個 Linear 看板——記錄了嘗試過什麼、什麼有效、什麼失敗了、哪些規則存活了下來。

讓記憶複合的模式，來自最強大的 Agent 如何使用它：

• 離開前寫下。 每次運行以更新狀態檔案結束——學到的教訓、驗證過的事實、下一步要做什麼。
• 開始時讀取。 每次運行以讀取狀態檔案和相關技能開始，這樣它就能繼續而不是重新開始。
• 提煉成技能。 當一個教訓是通用的（「Windows 運行器需要 bash，而不是 PowerShell」），它就從狀態檔案畢業進入技能，適用於未來每個專案。

1# 專案記憶
2
3## 已驗證的事實 # 停止猜測這些
4- prc 是以美元計價，不是分（通過 SELECT MIN/MAX 檢查）
5- 認證中介層順序：rate_limit -> jwt -> rbac
6
7## 經驗教訓 # 將通用的提煉成技能
8- Windows CI 運行器在 PowerShell 中會失敗 TLS 1.2——改用 bash
9- 超過 1M 行的資料表遷移必須以 10k 批處理
10
11## 上次工作階段 # 繼續，不要重新開始
122026-06-11 · 3 個修復已合併，2 個升級。下一步：驗證 rate-limit 修復。

13. 閉合循環。輸出 → 教訓 → 技能 → 更好的輸出。

這就是三個樓層鎖在一起，形成一個自我改進的系統。每次運行都會產生輸出。審查者子 Agent（步驟 7）檢查它。

結果——什麼通過了、什麼失敗了、學到了什麼——被寫入記憶（步驟 12）。通用的教訓被提煉成技能（步驟 8）。

下一次運行繼承了更銳利的技能和更豐富的記憶。

這就是整個自我改進的循環，注意它完全由 Harness 的零件構成：

• 子 Agent 評分工作——客觀檢查、新的上下文。
• 記憶 記錄判決——在運行之間存活。
• 技能 提煉教訓——為未來應用。
• 循環 再次運行它——現在有了上次運行學到的一切。

模型從未改變。它周圍的 Harness 變得更銳利。這就是「自我改進」的真實含義——不是一個學習的模型，而是一個累積的 Harness。

14. 發布 Harness。打包它。分享它。重用。

一個在一個專案上有效的 Harness 是一項資產。

將技能、子 Agent 和規則打包成一個插件，你的整個團隊就能一步安裝相同的設定——相同的慣例、相同的安全掛鉤、相同的審查者。

Harness 不再是你的個人設定，而變成了共享的基礎設施。

建立順序，最後再說一次，因為順序就是教訓：先在一個乾淨的 Harness 上讓一次手動運行變得可靠。

加入上下文和權限。加入一個審查者子 Agent。加入記憶。然後，只有這樣，才用循環把它包起來。 一個好的 Harness 上的循環會複合。一個壞的 Harness 上的循環只會更快地流血。

§ 讓每個循環變得更糟的 Harness 錯誤

• 在預設設定上運行。 沒有上下文、沒有規則、沒有記憶——Agent 每次工作階段都從頭推導你的專案。
• 一個腫脹的 CLAUDE.md。 程序塞進固定上下文，讓每次運行都膨脹。把它們移到技能裡。
• 在 CLAUDE.md 中強制執行而不是用掛鉤。 模型可以忽略一個建議。它無法忽略一個退出碼為 2 的掛鉤。
• 一個 Agent 同時寫作和評分自己的工作。 加入一個擁有全新上下文視窗的審查者子 Agent。
• 沒有記憶。 每次運行都從零重新開始。狀態檔案是讓明天可以繼續的東西。
• 在一個壞的 Harness 周圍包上一個循環。 循環只是更快地產出垃圾。先打好基礎。
• 二十個掛鉤。 一兩個銳利的掛鉤勝過一堆沒人理解的東西。
• 沒有掃描就發布 Harness。 洩漏的密碼和過於寬泛的權限會擴散給每個安裝它的人。

結論：

循環獲得榮耀。Harness 做實際的工作。

循環工程是令人興奮的部分——Agent 自我提示，在你睡覺時運行。但一個循環只是一個按計時器運行的 Harness。

決定輸出是好是垃圾的一切都住在下面一層，在你選擇的模型、你允許的工具、你寫的上下文、你加入的審查者、你保留的記憶裡。

把那一層建好，它上面的一切就會複合：循環重用你的子 Agent，工作流程編排你的技能，記憶讓每次運行都比上一次更銳利。

自我改進從來不是模型的屬性。它是你圍繞它建立的 Harness 的屬性。

選擇一件你還沒在做的事——很可能是一個審查者子 Agent、一個安全掛鉤、或一個狀態檔案——今天就把它加上去。保持 Harness 小到可以解釋。然後在它上面放一個循環，看著基礎結構完成工作。