這一課會完成什麼
- 分清模型能力問題，以及脈絡、狀態、控制與環境回饋的結構性缺口
- 保存可重現的基準，包括品質、人工介入、修改範圍、成本與復原證據
- 根據觀察挑選最小的一項 harness 介入，不先堆滿指令與工具
- 說清單次前後比較的限制，避免把課堂 run 包裝成普遍 benchmark
開始前先準備
- • 本機已安裝 Git，並有一套可在 sandbox repository 讀寫的 coding agent
- • 使用 Release Desk 課程 fixture，不得放真實憑證、客戶紀錄或 production 連線
先把定義說清楚
診斷 harness 缺口
Harness 缺口是模型周邊系統造成、而且能重複觀察的失敗。常見成因包括需求沒有可執行定義、repository 無法交代架構、環境不能穩定啟動、工作狀態只留在聊天、權限與停止條件放在模型文字裡，或驗證回饋無法證明真實使用路徑。診斷的目的不是替 agent 打分數，而是找出能由工程手段修正的邊界。
一次失敗後立刻換模型、加長 prompt，可能讓下一次看起來順一點，卻沒有修好 repository 本身。Agent 仍可能找錯檔案、漏跑 migration、把局部測試當作完成，或在 session 中斷後重做已完成的效果。這些問題換一個功能名稱就會再出現。
基準把討論從印象換成可查證的紀錄。你要保存開始 commit、完整任務文字、agent 看過的入口、第一個宣稱完成的時間、真正執行的檢查、修改路徑、人工提示、失敗位置與後續修復。後面每一層 harness 都必須改善其中一項觀察，否則就應刪除，避免維護成本反過來拖慢工作。
現場情境
Release Desk 的第一次無 harness 任務
Release Desk、任務、agent 行為、執行時間與所有結果都是課程合成 fixture。
- 負責人
- 你是準備導入 coding agent 的技術主管，要先知道 repository 缺的是什麼。
- 要做的決策
- 這次失敗最主要落在哪一個 harness 邊界，第一個值得實作的介入是什麼？
- 目前狀態
- Repository 可以手動啟動，但沒有入口說明、環境健檢、工作 ledger 或端到端命令。任務要求有權限的 reviewer 對一筆 open request 提出 changes，必須保存原因並留下一筆 audit。
- 預期成果
- 交出一份能重播的基準 receipt，列出證據、人工介入與限制，並只選一項有理由的後續工作。
限制條件
- • 基準 run 不得新增 AGENTS、README 補丁、工具 wrapper 或測試，只能保存 agent 原本的操作證據
- • 最多 90 分鐘、12 個 agent turn，任何真實外部寫入與 production 憑證都在範圍外
- • 完成要以登入後頁面、資料持久化、權限拒絕與 audit 次數判定，不能只看 terminal 宣告
實作範例
API 通過，但使用者路徑沒有完成
證據類型: 具名模擬情境Agent 找到 route handler，加入狀態轉換後執行單元測試，看到綠燈便宣稱完成。Diff 沒有接前端 action，也沒有檢查重整後資料。Reviewer 打開頁面時找不到按鈕；手動呼叫 API 後，狀態又在重新整理時消失。
團隊沒有把問題歸咎於模型，而是記為兩個缺口：任務合約沒寫可觀察的使用者旅程，repository 也沒有一個能驗登入、操作、持久化與 audit 的完整檢查。第一項介入是鎖定 executable task contract，而不是先新增更多工具。
基準紀錄保留起始 commit、11 個 turn、兩次人工提示、4 個額外修改檔案、缺少 browser evidence，以及持久化失敗。這些數字只描述合成 fixture，後續候選必須在相同驗收條件下比較。
主張限制
單次 run 無法估計模型變異，也不能證明其他 repository 會有相同結果。要擴大結論，仍需固定任務集、重複試跑、holdout 與人工審查。
做法
照著做，每一步都有檢查點
現場情境
這次失敗最主要落在哪一個 harness 邊界，第一個值得實作的介入是什麼？
- 01鎖定基準條件
- 02旁觀完整工作軌跡
- 03獨立執行驗收
驗收條件
你能用一份可重播紀錄說明 failure 在哪一層、哪些仍是未知，以及下一個最小實驗要改善哪個觀察。
- 01
鎖定基準條件
記錄 commit、branch、lockfile、runtime、fixture、agent、任務文字、預算與停止條件。先不要更動 repository 說明，也不要把 reviewer 的背景知識塞進 prompt。
檢查點 · 另一位同事可以取得相同起點，且所有差異都能在 receipt 看到。
- 02
旁觀完整工作軌跡
保存每次工具操作、失敗、修改路徑、測試、agent 第一次完成宣告與人工提示。敏感值只能以 canary 或雜湊檢查，不把完整內容收進教材。
檢查點 · 時間線能回答 agent 看了什麼、改了什麼、依據什麼說完成，以及人工在哪裡介入。
- 03
獨立執行驗收
從乾淨狀態檢查 type、規則、API、登入後 browser 旅程、重整持久化、未授權角色與 audit 次數。不要沿用 agent 口頭說通過的結果。
檢查點 · 每一項合約要求都有 pass、fail、missing 或 skipped 狀態與實際證據。
- 04
分類並挑一項介入
把問題對到 intent、legibility、continuity、control、feedback，附上證據與其他可能解釋。按影響、重複機率、可測性與維護成本排序，只選第一項可驗證的 harness 改造。
檢查點 · 決策沒有把所有失敗都推給模型，也沒有一次加入整套複雜 scaffolding。
實務脈絡
展示版之後
固定任務與環境
使用課程提供的 request changes 功能、固定 seed、鎖定依賴版本與同一套 agent 設定。先記錄起始 commit、工作樹狀態、任務文字、預算與停止點。後續若改用 holdout，難度與驗收路徑要相當，不能換成比較容易的案例再宣稱改善。
基準期間不補 repository 指令，也不偷偷修啟動流程。安裝失敗就保存輸出；agent 問到只存在工程師腦中的知識，也要記下問題而不是立即回答。缺少的資訊本身就是 harness 診斷證據。
按照可修邊界分類
把觀察分到 intent、legibility、continuity、control、feedback。因為沒有架構地圖而改錯層，屬於可讀性問題；程式修改正確但頁面重整後狀態消失，屬於回饋與驗收問題；逾時後重複寫入，牽涉控制與復原。不要用粗心、迷路或不夠聰明這類人格標籤，因為它們沒有可執行的修復位置。
比較時同時看結果與過程：任務是否真的通過、修改是否超出範圍、發生幾次人工介入、走了多少無效步驟、context 花在哪裡、失敗後多久能定位與復原。最後寫成診斷表，每個推測都要連到 trace、diff、指令輸出或人工紀錄。
動手實作
跑一次基準並寫出 harness-gap 診斷
在乾淨 Release Desk fixture 執行固定任務，不補提示，保存操作、diff、檢查與人工介入，再依五個邊界分類。
準備項目
- • 建立獨立 worktree，確認沒有 production 連線、真實秘密或其他專案程序會被碰到
- • 鎖定任務文字、起始 commit、agent 設定、時間與 turn 上限，準備旁觀用記錄表
本課產出
一份 baseline receipt、時間線、diff scope、驗收結果、人工介入紀錄、五類缺口診斷，以及只含一個優先介入的決策。
起始模板: 基準觀察表
Markdown{
"runId": "he-00-baseline-001",
"startingCommit": "REPLACE_ME",
"taskFixture": "request-changes-v1",
"agentSetup": { "tool": "REPLACE_ME", "modelLabel": "REPLACE_ME" },
"limits": { "minutes": 45, "externalWrites": 0 },
"firstCompletionClaim": null,
"acceptance": [],
"humanInterventions": [],
"filesChanged": [],
"failureClass": [],
"limitsOfEvidence": "single synthetic run"
}可下載的實作檔
Baseline worksheet
harness-baseline.json · JSON
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-00-receipt.json · JSON
A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.
驗收指令
npm run harness:baseline -- --receipt .harness/harness-baseline.json預期 receipt
PASS he-00 baseline-recorded
task=request-changes-v1 evidence>=5 externalWrites=0
decision=recorded limits=single-run預期結果
你能用一份可重播紀錄說明 failure 在哪一層、哪些仍是未知，以及下一個最小實驗要改善哪個觀察。
留給下一課
保留原始 task text 與 baseline receipt。模組 01 會把它改寫成機器與 reviewer 都能執行的任務合約，之後每一層都要回來對照這份基準。
驗收條件
- 01基準條件包含 commit、環境、fixture、任務、agent 設定、預算與停止點
- 02證據涵蓋真實使用路徑、持久化、權限、audit、修改範圍、人工介入與復原
- 03每個診斷都連到可查的 trace、diff、輸出或 reviewer 紀錄
- 04後續介入只有一項，且預先寫好成功、失敗與移除條件
常見故障
故障診間
F1基準途中一直補提示，最後任務雖完成卻不知道是哪個介入有效。
- 先檢查
- 對照每次人工訊息、repository 變更、檢查與結果時間點。
- 可能原因
- 沒有先定停止點與介入記錄，把觀察和教學混在同一個 run。
- 修復方式
- 將這次標為探索，回到乾淨 commit 重新跑受控基準。
- 下次怎麼避免
- 基準只記錄問題；任何協助都另開候選 run 並版本化。
F2Agent 說完成，獨立 reviewer 卻無法操作功能。
- 先檢查
- 核對 agent 執行的命令、skipped suite、browser journey、持久化與 receipt。
- 可能原因
- 完成定義停在單元測試或 API，沒有涵蓋使用者可觀察行為。
- 修復方式
- 把缺少的路徑記為 feedback gap，保留失敗案例供後續 evaluator。
- 下次怎麼避免
- 所有完成主張都由任務合約與獨立驗收建立，不採信 session 摘要。
F3診斷表把每個問題都寫成模型不夠好。
- 先檢查
- 逐一問 repository、環境、狀態、權限或回饋是否真的提供必要條件。
- 可能原因
- 分類描述人格與結果，沒有定位可修的系統邊界。
- 修復方式
- 用五類架構重寫，未知就保留未知，不硬湊單一原因。
- 下次怎麼避免
- 要求每個原因附證據、反證與可測的最小介入。
展示版之後
正式上線前的邊界
- 01基準與候選的任務、環境、fixture、模型設定、預算與驗收路徑可比較
- 02所有資料為合成或明確授權內容，trace、截圖與 receipt 不含真實秘密
- 03完成狀態來自獨立驗收，不來自 agent 的文字宣告
- 04人工介入、修改範圍、失敗、成本、復原與未解問題都如實保存
- 05診斷區分證據、推測與其他可能原因，沒有把單次結果當普遍結論
- 06每個新增 harness 層都有預期效益、維護成本、owner 與移除條件
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [1]Harness engineering：在 agent-first 開發環境中運用 Codex知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
OpenAI · 公開案例 · 2026-08-26
- [2]長時間執行 agent 的有效 harnessinitializer 模式 · feature ledger · session 交接 · 端到端驗證
Anthropic · 已發表研究 · 2026-08-26
- [3]打造有效的 agent採用能通過需求的最簡架構 · workflow 模式 · 環境回饋 · 停止條件
Anthropic · 官方文件 · 2026-08-26
- [4]Learn Harness Engineering專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
Walking Labs · 公開案例 · 2026-08-26
- [5]Andrej Karpathy 的 AI Engineering PlaybookSoftware 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
AI Builder Club · 公開案例 · 2026-08-26
延伸的 Tenten 資源