本篇代碼示例：code/ 實戰練習：Project 01. 只寫提示詞讓 agent 做，和定好規則再讓它做，差多少

第一講. 模型能力強，不等於執行可靠

你說你也算見過世面的人了——Claude Pro 訂著，GPT-4o 的 API key 也有，SWE-bench 排行榜上的數字你比誰都清楚。有一天你終於想讓 AI agent 幫你改一個真實的項目，信心滿滿地交代下去。結果呢？加了功能但測試掛了，改了 bug 但引入了新 bug，跑了 20 分鐘然後自信滿滿地說"完成了"——你一看代碼，根本不是你要的東西。

這時候你的第一反應是什麼？"這模型不行，得換一個更貴的。"且慢。先別急著掏錢包。問題可能根本不在模型身上。

讓我們先看一組數據。截至 2025 年底，最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這還是精心挑選過的、有明確 issue 描述和測試用例的任務。換到你日常開發的場景——需求模糊、沒有現成測試、隱含的業務規則散落在各處——這個數字只會更低。

但這組數據背後藏著一個反直覺的事實。

同一匹馬，兩種命運

Anthropic 做過一個對照實驗。同一個 prompt（"做一個 2D 復古遊戲編輯器"），同一個模型（Opus 4.5）。第一次讓它裸跑——20 分鐘，花了 $9，遊戲核心功能根本跑不起來。第二次給它配上完整的 harness（planner + generator + evaluator 三 agent 架構）——6 小時，花了 $200，遊戲可以正常遊玩。

模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬鞍。

OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白：Codex 在一個 harness 搭得好的倉庫裡，表現能從"不可靠"變成"可靠"。注意他們的用詞——不是"好了一點"，是質變。就像一匹千裡馬，沒馬鞍你也能騎，但騎不了多遠、跑不了多快、摔下來也不稀奇。harness 就是那個馬鞍——模型權重之外的一切工程基礎設施。

agent 到底卡在哪

那具體是什麼在出問題？

最常見的：你根本沒把任務說清楚。你說"加個搜索功能"，agent 理解的跟你完全不一樣——搜什麼？全文本還是結構化？要不要分頁？要不要高亮？你沒說清楚，agent 就自己猜。猜對了是運氣，猜錯了你再改，改的成本比一開始說清楚還高。這就像你去飯館跟師傅說"來個魚"，端上來是紅燒還是清蒸還是酸菜——全看運氣。

就算你說清了，項目裡隱含的架構約定 agent 也不知道。你們團隊統一用 SQLAlchemy 2.0 的新語法，但 agent 默認寫了 1.x 的代碼。所有 API 端點必須走 OAuth 2.0 認證，但這個規則只存在於你腦子裡和一個三個月前的 Slack 消息裡。Agent 看不到這些——它不是不想遵守，是壓根不知道有這回事。

環境也是個坑。開發環境配置不完整、依賴缺了、工具版本不對。Agent 把寶貴的上下文窗口花在了 pip install 失敗、Node 版本不對這些事上，而不是解決你的核心任務。就好比你讓一個木匠來幹活，結果錘子沒帶、釘子找不到、工作臺還是歪的——手藝再好也使不上勁。

更常見的：壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完代碼，自己看了看覺得沒問題，就說完成了。這就像讓學生交作業但不給答案檢查——他自己覺得自己做對了，但批改的時候一堆錯誤。Anthropic 還觀察到一個有意思的現象：當 agent 感覺上下文快滿了，它們會匆忙結束當前工作，跳過驗證步驟，選一個簡單的方案而不是最優方案。他們把這叫"上下文焦慮"——跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。

長任務跨會話就更慘了——上次會話的發現全丟了，每個新會話都得重新探索項目結構、理解代碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。

關鍵名詞解釋

理解了上面的場景，這些概念就不再是一堆術語了：

能力鴻溝（Capability Gap）：模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。
Harness：模型之外的一切——指令、工具、環境、狀態管理、驗證反饋。不是模型權重的部分，全是 harness。也就是我們說的"馬鞍"。
Harness 誘導失敗：模型本身能力足夠，但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。
驗證缺口：agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說"我做完了"但實際沒做完——這是最常見的失敗模式。
診斷循環：執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。
完成定義（Definition of Done）：一組可以用命令驗證的條件——測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義，agent 就會自己編一個。

遇到失敗，先修 harness

核心原則：遇到失敗，先別換模型，先檢查 harness。 如果同一個模型在類似的結構良好的任務中能成功，那優先假設是 harness 的問題。這就像汽車拋錨——你不會第一時間懷疑是發動機壞了，你會先看看是不是沒油了。

具體怎麼做：

每次失敗都歸因到具體層。 不要籠統地說"模型不行"，而是問：是任務沒說清楚？是上下文不夠？是沒有驗證手段？把每次失敗歸到五層防禦（任務規範、上下文供給、執行環境、驗證反饋、狀態管理）中的某一層。養成這個習慣，你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。

給每個任務寫顯式的完成定義。 不要說"加個搜索功能"，要說：

完成標準：
- 新增 GET /api/search?q=xxx 端点
- 支持分页，默認 20 条
- 返回結果包含高亮片段
- 所有新程式碼通過 pytest
- 類型檢查通過（mypy --strict）

創建 AGENTS.md 檔案。 在倉庫根目錄放一個檔案，告訴 agent 這個項目的技術棧、架構約定、驗證命令。這是 harness 工程的第一步，也是投入產出比最高的一步。一個 AGENTS.md 檔案可能比你換一個更貴的模型更有效——我不是在開玩笑。

建立診斷循環。 不要把失敗當作"模型又犯傻了"，而是當作"harness 又暴露了一個缺陷"的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來，你的 harness 會越來越強，agent 的表現會穩定提升。就像修路——每填一個坑，下一段路就更平坦。

量化改進。 記個簡單的日誌：每個任務成功了沒有，失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸，集中火力修那個層。

一百萬人行代碼的實驗

OpenAI 在 2025 年做了一個激進的實驗：用 Codex 從一個空的 git 倉庫起步，構建一個完整的內部產品。五個月後，這個倉庫有大約 100 萬行代碼——應用邏輯、基礎設施、工具、文檔、內部開發工具——全部由 agent 生成。三個工程師驅動 Codex，開了大約 1,500 個 PR 併合並。平均每人每天 3.5 個 PR。

這個實驗的關鍵約束是：人類永遠不直接寫代碼。 這不是噱頭，而是為了逼團隊搞清楚——當工程師的主要工作不再是寫代碼，而是設計環境、表達意圖、構建反饋迴路時，到底什麼變了？

早期進展比預期慢。不是 Codex 不行，而是環境不夠完整——agent 缺少必要的工具、抽象和內部結構來推進高層次目標。工程師的工作變成了：把大目標拆成小積木（設計、編碼、審查、測試），讓 agent 去搭建，然後用這些積木解鎖更復雜的任務。當某件事失敗了，修復幾乎從來不是"更努力"，而是"agent 缺什麼能力，怎麼讓它既可理解又可執行"。

這個實驗直接證明了本講的核心論點：同一個模型，在空白環境裡和在有完整 harness 的環境裡，產出有本質差異。 模型沒變，變的是環境。

來源：OpenAI: Harness engineering: leveraging Codex in an agent-first world

一個更接地氣的例子

一個團隊用 Claude Sonnet 給一箇中等規模的 Python Web 應用（FastAPI + PostgreSQL + Redis，約 15,000 行代碼）添加新的 API 端點。

起初他們只給了一句話："在 /api/v2/users 下添加用戶偏好設置端點"。結果呢？agent 花了 40% 的上下文窗口探索倉庫結構，產出了看似合理的代碼但沒遵循項目的錯誤處理模式，用了舊版 SQLAlchemy 語法，宣稱完成但端點實際有運行時錯誤。下一個會話還得重新做發現工作。

後來他們加了 AGENTS.md（描述項目架構和技術棧版本）、顯式的驗證命令（pytest tests/api/v2/ && python -m mypy src/）、和架構決策記錄。同一模型在三次獨立運行中全部成功，上下文使用效率提高了約 60%。

模型沒變。變的還是 harness。

帶走什麼

模型能力和執行可靠性是兩回事。千裡馬也得配上好馬鞍。
失敗的時候先看 harness，再看模型。換模型是成本最高的選擇——而且很多時候根本不是模型的問題。
每次失敗都是一個信號：你的 harness 有結構性缺陷。把它找出來、修掉。
五層防禦：任務規範、上下文供給、執行環境、驗證反饋、狀態管理。逐層排查，就像醫生看病先檢查最常見的病因。
一個 AGENTS.md 檔案可能比你換一個更貴的模型更有效。真的。

練習

對比實驗：選一個你熟悉的代碼倉庫和一項非平凡的修改任務。先不給任何 harness 支持，讓 agent 跑一次，記錄失敗。然後加一個 AGENTS.md 和顯式的驗證命令，讓同一個 agent 再跑一次。對比兩次的結果，把失敗歸因到五層防禦中的某一層。
驗證缺口測量：選 5 個編碼任務，在每個任務完成後記錄 agent 是否聲稱完成，然後用獨立測試驗證實際正確性。計算 agent 在實際沒完成時聲稱完成的比例——這就是你的驗證缺口。然後想想：加什麼驗證命令能把這個比例降下來？
診斷循環實踐：找一個 agent 在你的項目中反覆失敗的任務。跑一次，記錄失敗。歸因到五層中的某一層。修那一層。再跑。重複三到五輪，記錄每一輪的改善。

第一講. 模型能力強，不等於執行可靠 ​

同一匹馬，兩種命運 ​

agent 到底卡在哪 ​

關鍵名詞解釋 ​

遇到失敗，先修 harness ​

一百萬人行代碼的實驗 ​

一個更接地氣的例子 ​

帶走什麼 ​

延伸閱讀 ​

練習 ​