Learn Harness Engineering — 讓 AI Coding Agent 在真實專案穩定工作的開源課程

9 美金跟 200 美金。同一個模型、同一個 prompt，做同一個 2D retro game editor。

裸跑那次跑了 20 分鐘，產出一個跑不動的東西。加上 planner / generator / evaluator 完整馬具的那次跑了 6 小時，做出一個能玩的遊戲。模型沒換，prompt 沒改，差別只在外面包了一層工程環境。

這個對照實驗是 Anthropic 自己做的，數字寫得很乾淨：環境的價值是模型的 22 倍。

大部分人在用 Claude Code 不順的時候，第一反應是換更大的模型、寫更長的 prompt、加更多 example。這就像馬不會拉車的時候，你想換一匹更貴的馬，而不是去買馬具。

walkinglabs/learn-harness-engineering 在解的，剛好就是這個。

馬具到底是什麼

Harness 這個詞在軟體圈被用爛了。Harness.io 是 CI/CD 平台、test harness 是測試骨架、LLM eval harness 是評估管線——這門課裡的 harness 跟以上都沒關係。

它指的是包覆在 AI coding agent 周圍的工程環境。

馬具這個類比成立的地方在於：再快的馬，沒套馬具就只能在原地亂跑；套上馬具，同一匹馬才能真正幫你拉車。AI agent 跟馬一樣，光靠肌肉（模型能力）不能完成工作，得靠外圍那套裝備把它的力量導引到「你要的方向」。

這套裝備被拆成五個子系統。每一個都有一個明確的最小產物，少了哪一個你都能立刻指認出是哪裡破了：

對照五個子系統去 debug，比抱怨「Claude 又笨了」有效率得多。你在自己專案裡用 agent 三不五時出狀況，幾乎都能對應到上面其中一格。

不用讀完 12 章才能用

這是這門課務實的地方。README 提供「Improve Your Agent Today」起手包，丟四到五個檔到專案根目錄即可：

1
2
3
4
5
6
7

YOUR PROJECT ROOT
├── AGENTS.md              # agent 的 operating manual
├── CLAUDE.md              # Claude Code 用
├── init.sh                # install + verify + start
├── feature_list.json      # 哪些 feature、哪些已完成
├── claude-progress.md     # 每個 session 發生什麼
└── src/                   # 你的程式碼

或者跑內建的 harness-creator skill 一鍵生成：

1
2
3
4
5
6
7
8
9
10
11
12

# 生一套 harness 到你的專案
node skills/harness-creator/scripts/create-harness.mjs \
  --target /path/to/project

# 驗證完整度（五子系統評分）
node skills/harness-creator/scripts/validate-harness.mjs \
  --target /path/to/project

# 跑 benchmark 產出 HTML 報告
node skills/harness-creator/scripts/run-benchmark.mjs \
  --target /path/to/project \
  --html /path/to/report.html

harness-creator 本身是 Anthropic Agent Skills 規格的範例。要寫公司自己的 skill，拿這個結構照抄最快，省下你研究 SKILL.md / metadata.json / agents/openai.yaml / evals/evals.json 各自要長什麼樣的力氣。

12 堂課的設計哲學

這門課把每一章標題寫成「為什麼 X」，不是「怎麼做 X」。差別很大。

「為什麼長時任務會失去連續性？」這種問句逼你先承認問題、再吸收解法。對照的反例是傳統教材常見的「session handoff 設計指南」——你還沒搞清楚為什麼需要它，就先被塞了一堆要記的欄位。

12 章的問題清單長這樣：

L04 是最容易踩坑的觀念。很多人寫 CLAUDE.md 寫到 3000 行，想把所有規則塞進去——agent 進來第一件事是把整份吞進 context window，等到要工作的時候已經沒空間了。這份檔該長得像「地圖」（指出去哪找答案），不是「百科全書」（直接給所有答案）。

L09 是最容易被忽略的觀念。agent 宣稱「done」的時候，到底有沒有跑測試？沒有 Verification 子系統的專案，這個問題的答案是「看運氣」——這個運氣最後會在 production 找你算帳。

6 個 Project：同一個 App、逐步演進

課程設計最聰明的地方在這。六個 project 全部圍繞同一個 Electron 桌面知識庫 App（匯入本地文件 → 建索引 → AI Q&A with citation），每個 P(N) 的 solution 就是下一個 P(N+1) 的 starter。

跑起來很直接：

1
2
3
4
5

cd projects/project-01/starter   # 或 solution/
npm install
npm run dev      # build + 啟動 Electron
npm run check    # type-check
npm run test     # Vitest

P06 capstone 提供完整 harness 與「拆掉某子系統」的對比版本。想驗證「到底是 progress.md 重要還是 feature_list.json 重要」，拆一個跑一次看結果差多少。這是少數能讓你做 ablation study 的教材，不是讀完就忘的那種。

標準 Agent Session Lifecycle

整套課程把 agent session 抽象成四個階段。這個流程套到自己專案也通用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

START   → 讀 AGENTS.md / CLAUDE.md
        → 跑 init.sh
        → 讀 progress.md
        → 讀 feature_list.json
        → 看 git log

SELECT  → 挑一個未完成 feature（只一個）

EXECUTE → 實作
        → 跑 verification（tests / lint / type-check）
        → 失敗則修、過才記錄 evidence

WRAP UP → 更新 progress.md / feature_list.json
        → 記下還壞或未驗證的
        → commit
        → 留 clean restart path

關鍵在於每一步都跳不過。AI agent 天生想跳過 SELECT 直接改一堆檔、跳過 EXECUTE 的 verification 宣稱完成、跳過 WRAP UP 讓下個 session 接不下去——這些就是大家用 Claude Code 在抱怨的所有問題的源頭。

把 lifecycle 寫進 CLAUDE.md 並用 hook 強制驗證每一步，比期待 agent「乖一點」可靠得多。

用得到這套東西的人

新專案導入 agent 前。新開的 repo 預計要讓 Claude Code 一起寫——不要裸跑，先用 harness-creator 生 AGENTS.md / feature_list.json / init.sh，讓 agent 一進來就知道吃什麼、送什麼、什麼叫完成。

既有 repo 的 agent 不穩定診斷。agent 在你專案三不五時忘記上次做什麼、重複修同地方、宣稱完成但其實沒跑測試——跑 validate-harness.mjs 拿五子系統評分。verification 分最低就缺 init.sh / 測試門檻；lifecycle 分最低就缺 progress.md。

多 session 長時開發。一個功能要做兩三天、跨多個 session、跨多人。用 progress.md + session-handoff.md，下個 session（不同人不同時間）能接力上，不用每次從「你是誰要做什麼」重來。

團隊統一 agent 使用規範。企業 repo 強制 AGENTS.md + feature_list.json 規格。不同工程師用同一個 agent 拿到一致行為，PR review 時也能照 feature_list 逐項檢核是否真的都做了。

內部 agent skill 開發範本。skills/harness-creator/ 本身就是 Anthropic Agent Skills 規格的示範。要為公司寫 skill，拿這個結構去打就行。

限制與不適合用的場合

課程很新——2026-03-29 才建 repo。部分章節跟程式碼一致性還在補強中，GitHub Issue #15、#9、#7、#4、#2 都在反映文件 vs. code 對不上。5/20 一波「Align project docs with checked-in code」修了不少，但還沒到完全乾淨。

其他要踩穩的：

• Q&A 範例是 mock 不接真實 LLM：要教的是 harness 結構，不是 LLM 整合。想看怎麼串 OpenAI / Anthropic API 要另外找資源。
• benchmark report 只是結構性評分：run-benchmark.mjs 驗證你有沒有這些檔、這些欄位，不能評估 agent 實際表現。真正效果要靠 representative task 的 before/after agent session 對照。
• 需要 Electron 背景才跑得順 capstone：project 幾乎都是 Electron + React + TypeScript。沒碰過桌面 app 的人在 P05 / P06 會多花一些時間適應。
• 綁在 Anthropic Agent Skills 規格：harness-creator 用的 metadata 是 Anthropic skill format。同時用 Codex / Cursor 要另外適配。
• License 有個小瑕疵：README 標 MIT，但 repo 根目錄沒 LICENSE 檔（gh repo view 看到 licenseInfo: null）。實際使用沒大問題，要做法務依據得多注意。

為什麼值得看

這門課的價值不在於「教你寫 prompt」，而在於把 OpenAI、Anthropic、Cursor、LangChain、Thoughtworks 這些大廠零散的 harness 觀念集結成一個可動手、可複製、可驗證的課程。

你可能零散讀過 OpenAI 那篇 “Harness Engineering: leveraging Codex”、Anthropic 的 “Effective harnesses for long-running agents”、Martin Fowler 那篇 “Harness engineering for coding agent users”——讀完還是不知道今天進 repo 該補哪些檔。這門課把那些觀念變成你可以拍成 template 的具體產物：AGENTS.md 長這樣、init.sh 該跑什麼、progress.md 寫什麼。

背後的線索就一條：模型本身已經夠強了。下一個十倍的效能提升，不會來自更大的模型，而來自更好的環境。誰先把馬具做穩，誰的馬就能拉真正的車。

★ 安裝指令 ─────────────────────────────────────

1
2
3
4
5
6

git clone https://github.com/walkinglabs/learn-harness-engineering
cd learn-harness-engineering
npm install
npm run docs:dev      # 本地預覽教材（VitePress）
npm run docs:build    # production build
npm run pdf:build     # 產出 PDF 教材到 artifacts/pdfs/

─────────────────────────────────────────────────

相關連結

• GitHub repo：walkinglabs/learn-harness-engineering
• 文件站：walkinglabs.github.io/learn-harness-engineering
• 繁中 README：docs-readme/zh-TW/README.md
• 配套清單：awesome-harness-engineering

理論基礎文獻：

• OpenAI: Harness engineering: leveraging Codex
• Anthropic: Effective harnesses for long-running agents
• Martin Fowler / Thoughtworks: Harness engineering for coding agent users
• Cursor: Continually improving our agent harness