這一課會完成什麼
- 分清模型能力問題，以及脈絡、狀態、控制與環境回饋的結構性缺口
- 保存可重現的基準，包括品質、人工介入、修改範圍、成本與復原證據
- 根據觀察挑選最小的一項 harness 介入，不先堆滿指令與工具
- 說清單次前後比較的限制，避免把課堂執行包裝成普遍基準評測
開始前先準備
- • 本機已安裝 Git，並有一套可在 sandbox 程式庫讀寫的程式撰寫 agent
- • 使用 Release Desk 課程測試資料，不得放真實憑證、客戶紀錄或正式環境連線
先把定義說清楚
Harness 缺口診斷
Harness 缺口是模型周邊系統造成、可以重複觀察的失敗。例如需求沒有可驗證的定義、程式庫說不清架構、環境無法穩定啟動，或進度只留在聊天紀錄。權限與停止條件交給模型自行判斷、驗證無法涵蓋實際使用路徑，也屬於這類問題。診斷時先保留相同任務的基準證據，定位失敗邊界，再評估工程修正是否有效。每一層都要能說明修好了什麼，以及增加多少維護成本。
一次失敗後立刻換模型、加長提示詞，可能讓下一次看起來順一點，卻沒有修好程式庫本身。Agent 仍可能找錯檔案、漏跑資料遷移、把局部測試當作完成，或在工作階段中斷後重做已完成的效果。這些問題換一個功能名稱就會再出現。
基準把討論從印象換成可查證的紀錄。你要保存開始提交版本、完整任務文字、agent 看過的入口、第一個宣稱完成的時間、真正執行的檢查、修改路徑、人工提示、失敗位置與後續修復。後面每一層 harness 都必須改善其中一項觀察，否則就應刪除，避免維護成本反過來拖慢工作。
現場情境
Release Desk 的第一次無 harness 任務
Release Desk、任務、agent 行為、執行時間與所有結果都是課程合成測試資料。
- 負責人
- 你是準備導入程式撰寫 agent 的技術主管，要先知道程式庫缺的是什麼。
- 要做的決策
- 這次失敗最主要落在哪一個 harness 邊界，第一個值得實作的介入是什麼？
- 目前狀態
- 程式庫可以手動啟動，但沒有入口說明、環境健檢、工作台帳或端到端命令。任務要求有權限的審查者對一筆 open 請求提出變更，必須保存原因並留下一筆稽核。
- 預期成果
- 交出一份能重播的基準驗收憑證，列出證據、人工介入與限制，並只選一項有理由的後續工作。
限制條件
- • 基準執行不得新增 AGENTS、README 補丁、工具 wrapper 或測試，只能保存 agent 原本的操作證據
- • 最多 90 分鐘、12 個 agent 回合，任何真實外部寫入與正式環境憑證都在範圍外
- • 完成要以登入後頁面、資料持久化、權限拒絕與稽核次數判定，不能只看終止宣告
實作範例
API 通過，但使用者路徑沒有完成
證據類型: 具名模擬情境Agent 找到路由 handler，加入狀態轉換後執行單元測試，看到綠燈便宣稱完成。差異沒有接前端操作，也沒有檢查重整後資料。審查者打開頁面時找不到按鈕；手動呼叫 API 後，狀態又在重新整理時消失。
團隊沒有把問題歸咎於模型，而是記為兩個缺口：任務合約沒寫可觀察的使用者旅程，程式庫也沒有一個能驗登入、操作、持久化與稽核的完整檢查。第一項介入是鎖定可執行的任務契約，而不是先新增更多工具。
基準紀錄保留起始提交版本、11 個回合、兩次人工提示、4 個額外修改檔案、缺少瀏覽器證據，以及持久化失敗。這些數字只描述合成測試資料，後續候選必須在相同驗收條件下比較。
主張限制
單次執行無法估計模型變異，也不能證明其他程式庫會有相同結果。要擴大結論，仍需固定任務集、重複試跑、保留評測與人工審查。
做法
照著做，每一步都有檢查點
現場情境
這次失敗最主要落在哪一個 harness 邊界，第一個值得實作的介入是什麼？
- 01鎖定基準條件
- 02旁觀完整工作軌跡
- 03獨立執行驗收
驗收條件
你能用一份可重播紀錄說明失敗在哪一層、哪些仍是未知，以及下一個最小實驗要改善哪個觀察。
- 01
鎖定基準條件
記錄提交版本、分支、lockfile、執行環境、測試資料、agent、任務文字、預算與停止條件。先不要更動程式庫說明，也不要把審查者的背景知識塞進提示詞。
檢查點 · 另一位同事可以取得相同起點，且所有差異都能在驗收憑證看到。
- 02
旁觀完整工作軌跡
保存每次工具操作、失敗、修改路徑、測試、agent 第一次完成宣告與人工提示。敏感值只能以 canary 或雜湊檢查，不把完整內容收進教材。
檢查點 · 時間線能回答 agent 看了什麼、改了什麼、依據什麼說完成，以及人工在哪裡介入。
- 03
獨立執行驗收
從乾淨狀態檢查型別、規則、API、登入後瀏覽器旅程、重整持久化、未授權角色與稽核次數。不要沿用 agent 口頭說通過的結果。
檢查點 · 每一項合約要求都有 pass、fail、缺漏或 skipped 狀態與實際證據。
- 04
分類並挑一項介入
把問題分到意圖、可讀性、持續性、控制與回饋五類，附上證據及其他可能解釋。按影響、重複機率、可測性與維護成本排序，只選一項可以驗證效果的 Harness 改造。
檢查點 · 決策沒有把所有失敗都推給模型，也沒有一次加入整套複雜支援結構。
實務脈絡
展示版之後
固定任務與環境
使用課程提供的請求變更功能，固定測試資料、隨機種子、依賴版本與 Agent 設定。記錄起始提交版本、工作樹狀態、任務文字、預算與停止點。後續若使用事先保留、未參與開發的評測案例，難度和驗收路徑也要相當，不能換成較容易的案例再宣稱改善。
基準期間不補程式庫指令，也不偷偷修啟動流程。安裝失敗就保存輸出；agent 問到只存在工程師腦中的知識，也要記下問題而不是立即回答。缺少的資訊本身就是 harness 診斷證據。
按照可修邊界分類
把觀察分成意圖、可讀性、持續性、控制與回饋。缺架構地圖而改錯層，屬於可讀性問題；修改正確、重整後狀態卻消失，屬於回饋與驗收問題；逾時後重複寫入，則查控制與復原。以可修正的工程位置描述失敗，少用粗心或不夠聰明這類無法驗證的標籤。
比較時同時看結果與過程：任務是否真的通過、修改是否超出範圍、發生幾次人工介入、走了多少無效步驟、脈絡花在哪裡、失敗後多久能定位與復原。最後寫成診斷表，每個推測都要連到執行軌跡、差異、指令輸出或人工紀錄。
動手實作
跑一次基準並寫出 harness-gap 診斷
在乾淨 Release Desk 測試資料執行固定任務，不補提示，保存操作、差異、檢查與人工介入，再依五個邊界分類。
準備項目
- • 建立獨立 worktree，確認沒有正式環境連線、真實秘密或其他專案程序會被碰到
- • 鎖定任務文字、起始提交版本、agent 設定、時間與回合上限，準備旁觀用記錄表
本課產出
一份基準版本驗收憑證、時間線、差異範圍、驗收結果、人工介入紀錄、五類缺口診斷，以及只含一個優先介入的決策。
起始模板: 基準觀察表
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預期結果
你能用一份可重播紀錄說明失敗在哪一層、哪些仍是未知，以及下一個最小實驗要改善哪個觀察。
留給下一課
保留原始任務文字與基準版本驗收憑證。模組 01 會把它改寫成機器與審查者都能執行的任務合約，之後每一層都要回來對照這份基準。
驗收條件
- 01基準條件包含提交版本、環境、測試資料、任務、agent 設定、預算與停止點
- 02證據涵蓋真實使用路徑、持久化、權限、稽核、修改範圍、人工介入與復原
- 03每個診斷都連到可查的執行軌跡、差異、輸出或審查者紀錄
- 04後續介入只有一項，且預先寫好成功、失敗與移除條件
常見故障
故障診間
F1基準途中一直補提示，最後任務雖完成卻不知道是哪個介入有效。
- 先檢查
- 對照每次人工訊息、程式庫變更、檢查與結果時間點。
- 可能原因
- 沒有先定停止點與介入記錄，把觀察和教學混在同一個執行。
- 修復方式
- 將這次標為探索，回到乾淨提交版本重新跑受控基準。
- 下次怎麼避免
- 基準只記錄問題；任何協助都另開候選執行並版本化。
F2Agent 說完成，獨立審查者卻無法操作功能。
- 先檢查
- 核對 agent 執行的命令、skipped 測試集、瀏覽器使用流程、持久化與驗收憑證。
- 可能原因
- 完成定義停在單元測試或 API，沒有涵蓋使用者可觀察行為。
- 修復方式
- 把缺少的路徑記為回饋缺口，保留失敗案例供後續評測器。
- 下次怎麼避免
- 所有完成主張都由任務合約與獨立驗收建立，不採信工作階段摘要。
F3診斷表把每個問題都寫成模型不夠好。
- 先檢查
- 逐一問程式庫、環境、狀態、權限或回饋是否真的提供必要條件。
- 可能原因
- 分類描述人格與結果，沒有定位可修的系統邊界。
- 修復方式
- 用五類架構重寫，未知就保留未知，不硬湊單一原因。
- 下次怎麼避免
- 要求每個原因附證據、反證與可測的最小介入。
展示版之後
正式上線前的邊界
- 01基準與候選的任務、環境、測試資料、模型設定、預算與驗收路徑可比較
- 02所有資料為合成或明確授權內容，執行軌跡、截圖與驗收憑證不含真實秘密
- 03完成狀態來自獨立驗收，不來自 agent 的文字宣告
- 04人工介入、修改範圍、失敗、成本、復原與未解問題都如實保存
- 05診斷區分證據、推測與其他可能原因，沒有把單次結果當普遍結論
- 06每個新增 harness 層都有預期效益、維護成本、負責人與移除條件
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [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 資源