Harness Engineering 實戰：讓 AI Agent 自動從 Bug 中學習的閉環系統

2025 年，所有人都在比誰的 AI Agent 更厲害。2026 年，贏家已經換了跑道——比的是誰的 Harness 更成熟。

如果你正在用 Claude Code、Codex CLI、或任何 AI coding agent，你每天都在跟 harness 打交道，只是你可能不知道它叫這個名字。這篇文章會用我自己的實戰設定，從零解釋什麼是 Harness Engineering，以及你今天就能動手做的事。

Harness Engineering 是什麼？一句話定義

Harness Engineering 是設計「包裹在 AI 模型周圍的控制系統」的工程學科。用 Martin Fowler 的公式來說：

Agent = Model + Harness

Model 提供智能，Harness 讓這個智能可靠、可控、可用。Phil Schmid 用了一個精準的電腦比喻：

電腦零件	AI 系統對應	說明
CPU	AI Model（GPT、Claude）	原始運算能力
RAM	Context Window	有限的工作記憶
作業系統	Agent Harness	管理資源、提供標準介面、控制生命週期
應用程式	Agent	跑在 OS 上的具體任務邏輯

你不會直接在 CPU 上跑程式，你需要作業系統。同樣地，你不會直接對 Claude 說「幫我寫整個系統」就放手不管——你需要 Harness 來確保它走對方向、犯錯時被攔住、學到的教訓不會遺失。

Harness 不是 Framework——搞清楚差異

很多人把 Harness 跟 LangChain、CrewAI 這類框架搞混。它們是完全不同的東西：

Framework（框架）	Harness（治具）
LangChain、CrewAI、AutoGen	Claude Code、Codex CLI
提供零件讓你自己組裝	提供完整運行環境
你自己負責接水管	幫你管好 context、工具、權限、失敗處理
Blueprint	Runtime environment

Framework 是建築材料，Harness 是建好的房子。你可以用 LangChain 的零件去蓋一個 harness，但 Claude Code 本身就已經是一個 harness。

Harness 的兩大核心機制：Guide 與 Sensor

根據 Martin Fowler 的分析，所有 harness 都由兩種控制機制組成：

Guide（前饋控制）——在錯誤發生之前攔住

Guide 是你預先給 agent 的方向和規則。它們在 agent 開始工作之前就生效，目的是讓 agent 第一次就做對。

• CLAUDE.md：專案規則文件（「不准動 main branch」「用繁體中文回應」）
• Domain Brain：過去踩過的坑的知識庫（「TWSE API 的 ROC 日期格式會導致解析錯誤」）
• Skills：標準化的工作流程（「寫 iDempiere event handler 要用這個 pattern」）
• AGENTS.md：角色分配和模型選擇規則

Sensor（反饋控制）——做完之後自動檢查

Sensor 監控 agent 的輸出，在問題擴大之前抓住它。分兩種：

• 計算型 Sensor：linter、type checker、單元測試——毫秒級回應，確定性結果
• 推理型 Sensor：用另一個 AI 審查輸出（code review agent）——秒級回應，有判斷力但不確定

大多數人只做了 Guide（寫 CLAUDE.md），完全忘了 Sensor。這就像開車只看前方，不看後照鏡。

完整的 Harness Cycle：6 步閉環

一個成熟的 harness 不是「設定好就不管」的靜態文件，而是一個會自我進化的閉環系統。完整的 cycle 有 6 個步驟：

① LOAD ──▶ ② GUIDE ──▶ ③ EXECUTE ──▶ ④ SENSE
 自動載入     前饋引導     Agent 做事     自動檢查
 context     規則+經驗                   品質
                                          │
⑥ EVOLVE ◀── ⑤ LEARN ◀───────────────────┘
 更新規則      萃取教訓
 和知識庫      從錯誤中

步驟	做什麼	Harness 類型	常見工具
① LOAD	自動載入專案 context	基礎設施	SessionStart hook, CLAUDE.md
② GUIDE	讀取規則 + 過去經驗	Guide（前饋）	Domain Brain, Skills
③ EXECUTE	Agent 寫 code	—	Claude Code Bash/Edit/Write
④ SENSE	自動偵測品質問題	Sensor（反饋）	PostToolUse hook, linter, test
⑤ LEARN	從 bug fix 中萃取教訓	Sensor → Guide 橋接	PreCompact hook
⑥ EVOLVE	更新 Brain / 規則文件	Guide 進化	Stop hook 驗證

關鍵是步驟 ⑤→⑥→②：agent 修 bug → 教訓寫入 Brain → 下次讀 Brain → 不再犯同樣的錯。這就是閉環。沒有這個迴路，你的 harness 永遠停留在你第一天寫的水平。

實戰：用 Claude Code Hooks 建立閉環 Harness

讓我用真實的 Claude Code 設定來展示。以下不是理論——這是我每天在用的 harness。

步驟一：建立 Domain Brain（Guide）

Domain Brain 是一組按技術領域分類的 markdown 文件，記錄「過去踩過的坑」。放在 ~/.claude/projects/{project}/memory/brain/ 目錄下：

brain/
├── python-crawler-data.md    # 爬蟲：ROC 日期、欄位映射、空值處理
├── idempiere-osgi-bundle.md  # OSGi：MANIFEST.MF、classloader 問題
├── idempiere-2pack.md        # 2Pack：UUID 穩定性、afterPackIn
├── stock-backtesting.md      # 回測：signal divergence、entry price bug
└── design-principles.md      # 設計原則：頻次驅動架構、anti-patterns

每個 brain file 的內容格式：

# Python Crawler — Everything That Can Go Wrong

## ROC Date Format
- [source: analyst] "1150309" 被解析成 AD 1150 年，要用 7 位 YYMMDD ROC 格式
- [source: analyst] TPEX 欄位名 TransactionAmount 不是 TradingMoney

## Holiday / Empty Response
- [source: analyst] TWSE API 假日返回空值，必須 guard `if not data: return []`

然後在 CLAUDE.md 裡強制 agent 在開工前讀 brain：

## Domain Brain — MANDATORY before ANY implementation work
Before writing any plan, code, or review, you MUST:
1. Find the `## Domain Brain:` line in the project's CLAUDE.md
2. Read each listed brain file
3. If you skip this step and a bug was documented in brain, that is YOUR failure

步驟二：用 Hooks 自動偵測 fix: commit（Sensor）

這是整個閉環最關鍵的一步。在 ~/.claude/settings.json 加入 PostToolUse hook：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "if": "Bash(git commit:*)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/claude-harness-fix-detect.sh",
            "timeout": 5,
            "statusMessage": "Harness: checking for fix: commit"
          }
        ]
      }
    ]
  }
}

偵測腳本做的事很簡單——從 stdin 讀取 Claude Code 傳來的 JSON，提取 commit message，如果是 fix: 開頭就注入 context 強制 agent 更新 brain：

#!/bin/bash
INPUT=$(cat)
msg=$(echo "$INPUT" | jq -r '.tool_input.command' | sed -n 's/.*-m[[:space:]]*["'\'']\?\([^"'\'']*\).*/\1/p')

case "$msg" in
  fix:*|fix\(*)
    project=$(echo "$INPUT" | jq -r '.cwd' | xargs basename)
    cat <<EOF
{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"⚠️ BRAIN UPDATE REQUIRED\nYou committed: $msg\nUpdate the brain file NOW before next task."}}
EOF
    ;;
  *) echo '{}' ;;
esac

效果：agent commit 了 fix: handle empty API response → hook 自動觸發 → agent 的 context 被注入「你必須更新 brain」的指令 → agent 無法忽略。

步驟三：PreCompact 安全網

Claude Code 在 context window 快滿時會自動壓縮（compact）。如果 brain 更新的指令在壓縮中被丟掉怎麼辦？加一個 PreCompact hook：

{
  "PreCompact": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "/path/to/claude-harness-precompact.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

腳本掃描最近 5 個 commit，如果有 fix: 就在壓縮前再次提醒。雙重保險。

步驟四：Stop hook 結算

Session 結束時，Stop hook 比對「今天的 fix: commit 數量」和「brain file 是否有更新」。如果數字不匹配，就警告使用者——這是最後的安全網。

真實案例：閉環如何拯救你的下一個 bug

讓我走過一個完整的案例。假設你的 TWSE 爬蟲在假日會爆錯：

1. ① LOAD：你打開 Claude Code，說「爬蟲昨天跑失敗了，幫我查」
2. ② GUIDE：Agent 讀 brain/python-crawler-data.md，發現裡面已經記錄了 ROC 日期和欄位映射的坑。帶著這些經驗開始查 bug，不走冤枉路
3. ③ EXECUTE：Agent 找到 root cause——假日 API 返回空 response，parse() 沒處理 None。寫修復
4. ④ SENSE：git commit -m "fix: handle empty API response on holidays" → PostToolUse hook 觸發 → 注入 brain update 指令
5. ⑤ LEARN：Agent 被強制讀 brain file，加入新教訓：「假日 API 返回空值必須 guard」
6. ⑥ EVOLVE：Brain file 更新完成。下次任何專案遇到 TWSE 爬蟲問題，都不會再踩同樣的坑

沒有這個閉環會怎樣？你修完 bug，commit，然後忘了。三個月後在另一個專案遇到同樣的問題，重新 debug 兩小時，再次發現「啊，假日要特別處理」。這就是知識衰減——你修了 bug，但教訓死在那個 commit 裡。

大多數人的 Harness 在哪裡斷裂？

我觀察到的最常見模式：

步驟	大多數人的狀態	問題
① LOAD	✅ 有 CLAUDE.md	—
② GUIDE	⚠️ 寫了規則但靠 AI 自律	AI 經常跳過，特別是簡單任務
③ EXECUTE	✅ Agent 正常工作	—
④ SENSE	❌ 完全沒有自動檢查	commit 後不跑 lint/test
⑤ LEARN	❌ 靠 AI 記得	AI 經常忘記更新知識庫
⑥ EVOLVE	❌ 靠 AI 記得	教訓死在 commit 裡

Cycle 在第 ④ 步就斷了。 Guide 做了一半，Sensor 完全不存在，閉環更不用說。這就是為什麼同樣的 bug 會反覆出現——不是 model 不夠聰明，是 harness 沒有記憶。

你的 Harness 成熟度在哪一層？

我把 harness 成熟度分成 4 層，你可以自我評估：

層級	特徵	你有什麼
Level 0：裸奔	直接對 AI 說話，沒有任何規則文件	只有 model
Level 1：有規則	有 CLAUDE.md、有 coding style guide	Guide（開環）
Level 2：有回饋	有 hooks 跑 linter/test、有 code review agent	Guide + Sensor（開環）
Level 3：閉環	Sensor 的結果會自動回寫到 Guide（Domain Brain）	Guide + Sensor + 閉環迴路

大多數人在 Level 1。用了 Claude Code 的人可能在 Level 1.5（有 CLAUDE.md 但沒有 hooks）。Level 3 是目標——你的 harness 會隨著每次 bug fix 自動進化。

今天就能做的 3 件事

不需要重新設計整個系統。從這三件事開始：

1. 建 Domain Brain 目錄：按技術領域建 brain files，把你已知的坑寫進去。不需要完美——一個 brain file 有 5 條教訓，就比沒有好 100 倍
2. 加一個 PostToolUse hook：偵測 fix: commit，注入 brain update 提醒。這一個 hook 就打通了 ④→⑤ 的斷裂
3. 在 CLAUDE.md 加 Domain Brain 規則：強制 agent 在開工前讀 brain。不是「建議」，是「MUST」

這三步讓你從 Level 1 直接跳到 Level 2.5。剩下的 0.5（完全自動化的 brain 更新）可以後面再做。

結語：Model 會被換掉，Harness 不會

OpenAI 一個月前還領先，現在 Claude 追上了。三個月後可能又換一輪。Model 是最不穩定的變數——你永遠不知道下一個版本是更好還是更差（我之前叫了 20 個 AI 專家 Review 的慘痛教訓就是證明）。

但你的 Harness——你的規則、你的 Brain、你的 Hooks——這些是你的資產。不管底層 model 怎麼換，你累積的工程知識和控制系統都會繼續生效。

2026 年的 AI 工程贏家，不是有最好 model 的人，而是有最成熟 harness 的人。你今天就可以開始建。

延伸閱讀

• Martin Fowler — Harness Engineering for Coding Agent Users
• Anthropic — Effective Harnesses for Long-Running Agents
• Phil Schmid — The Importance of Agent Harness in 2026