外觀

語言

高效 AI 駕馭術

Harness Engineering 是什麼?AI Harness 讓 AI agent 穩定做事的 7 個部分(2026)

AI harness 指包在模型外面的那一整套環境:規則、把規則寫成測試、技能、MCP、記憶、子代理,以及驗收和人工把關。每個部分附上我實際的做法。

Kelvin Wang · · 9 分鐘閱讀

重點整理

  1. 模型每次都從空白開始,harness 負責把它需要知道、需要遵守、需要檢查的東西放在固定的地方。
  2. 規則寫在一份檔案給所有工具共用;一定不能違反的規則改寫成測試或 hook,不靠模型記得。
  3. 做法寫成 skill、外部資料接 MCP、我的回饋存成記憶,旁支工作交給子代理。
  4. 完成要有證據:測試、截圖、線上頁面;發布和上線由我點頭。

同一個模型,在兩個人手上做出來的東西可以差很多。差別多半不在模型,在它周圍的東西:它開工前讀到哪些規則、能用哪些工具、做錯了有沒有東西擋住、做完由誰檢查。我把這些統稱為 harness,原意是馬具,套在馬身上讓牠的力氣往你要的方向走。

對我來說,harness 從一開始就在做了。它是把 AI 的流程自動化,但不像用 Python 跑 cron job 或 loop 那樣定時重複同一件事,而是讓 AI 反覆迭代自己的過程。

AI harness 是什麼?

Anthropic 的 Claude Code 最佳實務文件裡,直接把 Claude Code 這個工具稱為 harness:模型讀規則、決定要做什麼;harness 則是在固定時間點執行你設定的檢查,不管模型怎麼想1。我用的定義再寬一點:模型以外、讓它每次都照同一套方式做事的所有東西,包括工具本身的設定,也包括你自己寫的規則檔、測試和流程。

它要解決的問題很單純。每次開新對話,模型的 context 都是空的。你上週糾正過的事、專案裡踩過的坑、哪些操作要先問你,它都不知道,除非這些東西放在它每次都會讀到、或每次都會被檢查到的地方。

我現在同時用 Claude Code 和 Codex,兩邊的功能名稱不同,但需要的部分是一樣的。我把它拆成七個:

部分解決什麼我的做法
1. 規則每次都要知道的事一份 AGENTS.md 給兩個工具共用,專案再各有一份
2. 規則變成測試一定不能違反的事設計規範、寫作規則、部署設定都有測試或稽核腳本
3. 技能重複的做法skill 正本放在一個 git repo,setup.sh 連到兩個工具
4. MCP外部資料和服務.mcp.json 只放啟動指令,憑證在 repo 外
5. 記憶我給過的回饋Claude Code 的記憶檔,一則回饋一個檔案
6. 子代理旁支工作和平行開發研究交給子代理;多個代理各用一個 worktree
7. 驗收與人工把關「說做好了」不等於做好測試、截圖、線上頁面;發布前要我同意

用哪個工具不是重點,我比較 Claude Code、Codex 和 Grok Build 的文章在AI 寫程式工具比較。

1. 規則:AI 每次開工前要讀的檔案

Claude Code 每次啟動會讀 CLAUDE.md,Codex 會讀 AGENTS.md23。這兩個檔案是 harness 最基本的一層:建置和測試指令、容易誤導的地方、已經做過的決定,寫一次,之後每個對話都看得到。

我的規則分兩層:

  • 全域一份。所有專案都適用的規則(溝通方式、改檔前先讀最新版、commit 前只提交自己的修改)放在 ~/ai-config/AGENTS.md,這是一個 git repo。Codex 的 ~/.codex/AGENTS.md 是指向它的 symlink,Claude Code 的 ~/.claude/CLAUDE.md 只有一行 @~/ai-config/AGENTS.md。兩個工具讀到的是同一份檔案。
  • 專案各一份。這個網站的專案規則寫著:改畫面前先讀 DESIGN.md、文章是 repo 裡的檔案、測試指令是 npx vitest run。

寫規則最常犯的錯是寫太長。Claude Code 官方建議每個 CLAUDE.md 控制在 200 行以內,越長越不容易被遵守2;Codex 的文件也說,短而準確的 AGENTS.md 比一份寫滿模糊規則的長檔有用4。

想深入 CLAUDE.md、AGENTS.md 怎麼寫?一份規則管所有 AI 寫程式工具(2026) 兩個檔案各由誰讀、放在哪、寫什麼不寫什麼,附可以複製的範本。

2. 規則變成測試:不能違反的事交給程式擋

規則檔是給模型讀的 context,模型通常會照做,但沒有保證。Claude Code 的文件講得很直接:如果一直替某一行規則加強語氣,它還是漏掉,那一行就該改成 hook1。

我的做法是把「一定要成立」的規則寫成測試,讓 npx vitest run 擋住:

  • 間距只能用規範裡的值。DESIGN.md 定了文章和頁面能用的間距,tests/spacing-scale.test.ts 掃所有頁面和元件,出現表外的值就失敗。
  • 狀態顏色只能用指定的角色。tests/status-colors.test.ts 擋住直接寫死的 Tailwind 色碼。
  • 每篇文章都要歸到一個主題。新文章沒加進 src/content/topics.ts,tests/blog-topics.test.ts 就失敗。
  • 部署設定不能被改回去。2026 年 11 月 5 日,7 次 push 裡有 5 次因為建置時同時開太多檔案(EMFILE)而部署失敗,當時沒人發現。修好之後加了 tests/build-config.test.ts,那個設定值被改大就失敗。

對我來說,把規則寫成測試,其實就是把我希望的限制(constraint)用文字說清楚。

有些規則是判斷題,不適合讓建置失敗。寫作規則就是:H2 是問句要加「?」、清單用粗體開頭、第一段不能重複導言。這些由 node tools/audit-writing.mjs 掃過所有文章,列出不符合的地方,只報告不擋建置,改不改由我決定。

另一類是工具層級的擋法。我在 Claude Code 全域設定掛了一個 PreToolUse hook:AI 透過 Supabase MCP 執行 SQL 之前先檢查,刪表、清空資料這類語句會跳出確認,我看過完整的 SQL 才放行。

這個部分還沒有獨立的教學,之後會另外寫。

3. 技能:把重複的做法寫成 skill

skill 是一個放著 SKILL.md 的資料夾。工具平常只看它的名稱和說明,任務符合時才讀全文,所以多步驟的做法放在 skill,比全部塞進規則檔省 context1。

我自己維護的 skill 正本放在 ~/ai-config/skills/。Claude Code 從 ~/.claude/skills 讀,Codex 這邊我用 ~/.agents/skills,所以寫了一支 setup.sh,用 symlink 把每個 skill 同時連到兩個位置:

  • 個人 skill:~/ai-config/skills/ 裡的每個資料夾。
  • 第三方 skill:快照放在 vendor/,不直接改,要更新就整包換成新版。同事照著裝,版本跟我一模一樣。
  • 專案 skill:正本留在各自的專案 repo,在 skills.manifest 一行登記一個。
  • 只裝在一邊的:某個安裝器只裝進其中一個工具時,setup.sh 會鏡像連到另一邊。

setup.sh --check 只檢查不動手:哪些還沒連結、哪些只在一邊、哪些同名但內容分岔。裝完或移除 skill 後跑一次,回報 ok 才算完成。

想深入 AI 寫程式的 skill 去哪找:來源與挑選方式 skill 放在哪、去哪找,以及安裝前要檢查什麼。

4. MCP:讓 AI 讀得到外部資料

MCP 是讓 AI 工具連接外部服務的開放標準。我接的有 SEO 數據、Cloudflare、Supabase 這類服務,讓 AI 查資料時直接讀來源,不靠我貼。

harness 的重點在憑證。這個網站 repo 的 .mcp.json 只有一行啟動指令,指向 tools/seo-mcp.sh;金鑰放在 repo 外、權限 600 的私有檔,由腳本在執行時讀進來。repo 推上 GitHub、給別人 clone,憑證都不會跟著出去。

想深入 MCP 教學:MCP server 怎麼設定、.mcp.json 放哪、憑證怎麼不進 repo scope、核准、啟動腳本,附我實際的設定。

5. 記憶:我說過的話不用說第二次

規則檔是我寫的,記憶是 AI 自己記的。Claude Code 的 auto memory 會把你的糾正和偏好存成檔案,放在 ~/.claude/projects/<專案>/memory/,索引檔 MEMORY.md 的前 200 行(或前 25KB)每次對話都會載入2。

我的網站專案現在有四十幾則記憶,每則一個檔案,寫著規則、原因和怎麼套用。例如:

  • 改一個就掃整類。我審交易所評測時,要求把同類的費用算式一次掃完。文案直接寫「2.4 USDT」,讀者就不用自己算「12 × 20%」。
  • 刪掉畫面已經說明的文字。事件列表如果看得出日期排序,標題寫「事件經過」就夠了。我審稿時也會找「下方連結」這種靠版面就能理解的字句。

記憶和規則檔的差別在於:記憶只存在這台電腦、只有 Claude Code 讀得到2。所以要讓 Codex 也遵守的事,我會從記憶搬進 AGENTS.md。

我每篇都會自己看過。記憶讓這些規則在下次改稿時還找得到,我最後再檢查稿子有沒有做到。

這個部分還沒有獨立的教學,之後會另外寫。

6. 子代理:旁支工作移出主對話

子代理(subagent)有自己的 context,做完只回傳摘要。適合的工作是會帶進一大堆搜尋結果或檔案內容、但主對話之後用不到的那種。Claude Code 自己也會把獨立的工作分給子代理1。

我用子代理做兩件事:

  • 研究和爬資料。查官方文件、整理數據都交給子代理。實際分工上,研究和爬蟲派給 Sonnet、Haiku 跑的子代理,主對話只看結論。
  • 平行開發。2026 年 11 月 16 日,網站上八個計算機工具分給幾個代理同時做。每個代理在自己的 git worktree 裡,共同的做法寫在一份 spec:先讀哪些文件、檔案放哪、數字只用官方來源、不准 push 或合併到 main。最後由一個整合代理把各分支合進同一條分支,統一處理大家都要改的共用檔,例如工具清單和主題分類。

讓幾個 session 同時改同一個 repo、又不互相蓋掉,關鍵是 git worktree:每個 session 一個工作目錄、一條分支。

想深入 2026 Oracle Cloud 免費 ARM 主機怎麼搶?常駐 Claude Code + Git repo 合作流程解析 在常駐主機上用 git worktree 讓多個 session 一起改同一個 repo。

7. 驗收與人工把關:誰說了算?

AI 回報「完成」只是一句話。我要的是證據:

  • 網站功能:npx vitest run 全過、npm run build 成功,用 Playwright 截手機 390px 和桌機 1280px、淺色和深色四張圖。
  • 上線:push 之後等 Cloudflare 的建置結果,用 curl 打開線上頁面確認改動真的在上面,才算上線。
  • SEO 改動:上線後用 SEO 工具記錄這次改了什麼,7、14、28 天後回頭看成效。

什麼叫完成,要在動手前寫清楚。我先寫 spec 定目的和完成條件,再寫 plan,做法在先寫 Spec,再寫 Plan。

最後一關是我自己。這個網站 push 到 main 就會自動部署,所以文章 commit、push 前要我明確同意;Threads 和 X 的貼文要另外同意,而且是針對確切的那段文字,「網站可以發了」不代表社群也可以發。

網站文章和社群貼文,我分開確認。社群貼文是用我的名字直接對讀者說話,每一句我都要自己看過、點頭了才發。

程式碼改動走 PR,我在手機上看 diff、留言、決定要不要合併。

同一支手機也用來遠端連線到不同電腦上的 Codex。我在各台電腦分別授權,只有這支手機能存取所有已連線的裝置。

想深入 2026 手機怎麼用 Claude Code 改程式、開 PR?Remote Control + GitHub App 從改到合併的完整流程 AI 開分支、跑測試、開 PR,我在手機上看 diff 再合併。

要從哪一個部分開始?

七個不用一次做完。我建議的順序:

  1. 規則:寫一份短的 AGENTS.md 或 CLAUDE.md,只放測試指令和你已經糾正過兩次的事。
  2. 驗收:每次都要 AI 拿出證據,跑了哪個指令、輸出是什麼。
  3. 規則變成測試:哪一條規則被違反第二次,就把它寫成測試或 hook。
  4. 技能、MCP、記憶、子代理:遇到重複的做法、要讀的外部資料、重講的回饋、太長的旁支工作時再加。

harness 會跟著你的錯誤長大。每一條規則、每一個測試背後,大多是一次真的出過的問題。

資料來源

  1. 1. Best practices for Claude Code · Claude Code Docs · 2026-11-16 查詢
  2. 2. How Claude remembers your project · Claude Code Docs · 2026-11-16 查詢
  3. 3. Custom instructions with AGENTS.md · OpenAI Codex Docs · 2026-11-16 查詢
  4. 4. Codex best practices · OpenAI Codex Docs · 2026-11-16 查詢

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我