我用一個真實 PR 開始衡量 Coding Agent Harness 的效果

大家好,我是來自韓國的初級開發者。
繁體中文是用工具輔助寫的,如果有不自然的地方請見諒。
最近我在 dogfood 一個開源專案:
https://github.com/baskduf/harness-starter-kit
它的想法很簡單:
不要只靠一次性的 prompt 來告訴 Coding Agent 專案規則,而是把規則、檢查、決策紀錄和失敗記憶放進 repository。
我把這個方向稱為 repo-level harness。
為什麼需要這個?
我在使用 Codex / Claude Code / Cursor 這類 coding agent 時,常遇到幾個問題:
每次新 session 都要重新說明專案規則
agent 可能會改到不該改的檔案
已經發生過的錯誤,下次又重複
某些失敗只留在聊天紀錄裡,repo 本身沒有記住
很難判斷「感覺有用」到底是不是真的有用
所以 harness-starter-kit 想做的不是讓 agent 魔法般變聰明,而是讓 repository 變得更適合 agent 工作。
它包含:
AGENTS.md專案規則docs/decisions/決策紀錄docs/failures/失敗記憶drift / structure / failure memory checks
/harness doctor,/harness update,/harness refresh,/harness reviewDjango、Next.js、React、Vue、Go、FastAPI 等 profile
adoption report 和 effectiveness report 模板
這次我做了什麼?
之前我主要在觀察:
harness 是否能讓錯誤更早暴露,並讓 repo 記住這些錯誤?
這次我想再往前一步:
如果說 harness 有用,那我可以衡量什麼?
所以我用一個真實 dogfood PR 做了一個很小的 benchmark。
這個 PR 來自一個 Next.js 專案 today-bus。
它是一個幫使用者規劃公車與火車銜接時間的小工具。
這次 PR 裡,我只計算真正的 product task,排除 setup run。
因為 setup run 雖然有用,但如果沒有明確的 task boundary、known failure mode 和 verification command,就不應該拿來當 effectiveness evidence。
這次統計的 3 個 task
這次 PR 裡統計了 3 個 product-task outcome:
homepage copy tightening
deterministic planner empty-result test hardening
domain terminology alignment
我觀察的指標包括:
expected file boundary
actual changed files
wrong-file edits
repeated known mistakes
first-pass verification
reverted files
human rework
結果是:
Metric | Result |
|---|---|
Product-task outcomes counted | 3 |
Wrong-file edits | 0 observed |
Repeated known mistakes | 0 observed |
First-pass verification | 3 / 3 |
Drift violations detected | 0 observed |
Reverted files | 0 observed |
Human rework minutes | Unknown |
這不是效果證明
這裡我想特別小心。
我不想說:
harness 已經證明讓 agent 更有效。
因為這次還有很多限制:
沒有 pre-harness baseline
樣本只有一個 PR
task 數量很少
reviewer 給了明確的 boundary 和 known failure mode
human rework 沒有測量
prompt text / prompt hash 還沒有穩定保存
所以比較準確的說法是:
這是一個 initial benchmark。
它讓我開始用 PR outcome 記錄 agent work,而不是只靠感覺。
我覺得有價值的地方
這次對我最有幫助的不是數字本身,而是衡量方式。
以前看 PR,主要看:
code 對不對
test 有沒有過
reviewer 有沒有 approve
但如果是 AI coding agent 參與的 PR,我現在也會問:
agent 原本應該改哪些檔案?
實際改了哪些檔案?
有沒有 wrong-file edit?
有沒有重複已經記錄過的 mistake?
verification 是第一次就通過,還是 human 修正後才通過?
這次結果有沒有留下可以比較的紀錄?
如果這些資訊只留在聊天紀錄裡,很快就會消失。
但如果留下 task outcome record,下一個 PR 就可以比較。
Harness health 不等於 Agent effectiveness
這也是我現在一直想分清楚的地方。
Harness health 是:
repo 裡有沒有 durable rules / checks / memory?
Agent effectiveness 是:
真實任務裡,agent 是否更少越界、更少重複錯誤、更少需要 human rework?
兩者有關係,但不是同一件事。
Harness Doctor 可以檢查 repo 裡有沒有 AGENTS.md、decision records、failure records、local checks、CI hints。
但它不能證明 agent 真的少犯錯。
要衡量 agent effectiveness,還是需要 task outcome records 和 effectiveness reports。
想請教大家
我還是初級開發者,所以這個專案還在摸索中。
想請教台灣開發者幾個問題:
這種 repo-level harness 對團隊使用 Coding Agent 有幫助嗎?
AGENTS.md+ failure memory + drift checks 會不會太重?你們會怎麼衡量 AI coding agent 的實際效果?
如果要支援台灣常見的團隊 workflow,還缺哪些東西?
這種 approach 比單純 prompt engineering 有沒有說服力?
專案連結:
https://github.com/baskduf/harness-starter-kit
Effectiveness report 範例:
歡迎任何批評或建議。
目前 README 有英文、韓文、日文和簡體中文版本,繁體中文 README 還沒有整理好。如果這個方向對台灣開發者有幫助,我之後會補上繁體中文版本。
作者:Yuan