這一課會完成什麼
- 整合任務契約、知識、初始化程序、隔離、狀態、工具、規則、評測、可觀測性、復原與工作圖規則
- 在相同範圍執行改造前後的保留評測,保存全部試跑
- 用 Harness Card 說清邊界、預算、驗收憑證、失敗規則、負責人與移除
- 決定限定範圍試行、待補件後再審或 no-go,移除沒有可量測收益的支援層
開始前先準備
- • 模組 00 到 09 的交付檔案與通過的驗收憑證
- • 全新複製的 Release Desk、固定 request-reopen 保留評測、獨立審查者與僅能使用測試資料的身分
先把定義說清楚
既有程式庫總整專案
這個總整專案使用具有既有系統形狀、但資料完全合成的程式庫,練習依據證據改造 Harness。交付包含功能修改、可重現環境、完整驗收憑證、復原與安全演練、清楚交接、維護計畫,以及限於已評測任務類型的營運決策。每一層都要說明守住哪項邊界,或改善哪個基準失敗,並能負擔維護成本。測試資料中的結果只適用指定範圍,正式環境仍需另做授權、風險與驗收。
Harness 工程要由另一個人從乾淨環境進入程式庫、理解架構、完成任務、檢查證據、中斷後安全恢復,並得到同一發布決策,才算真正交付。流程圖與錄好的成功工作階段都不能替代未參與開發的重現。
最終決策也要留下不確定性。候選版本可能縮短理解程式庫、減少人工介入,卻在復原演練失敗;這是 hold,不是降低驗收門檻的理由。反過來,某個複雜摘要產生器若沒有增加正確率或降低交接成本,移除它也是成功的 harness 結果。
現場情境
用未見過的請求重新開啟驗 harness
Release Desk、保留評測、執行、指標、審查者、失敗與決策均為合成教材。
- 負責人
- 你是要向要求證據的工程負責人與獨立審查者交付程式庫改造的 harness 工程師。
- 要做的決策
- 完成的 Harness 是否足以支援提議的無人看守時間?哪些層有證據應保留、哪些要修改或移除?
- 目前狀態
- 請求變更已完成。保留評測要求已授權審查者能用原因重新開啟 resolved 請求,保留一筆稽核操作效果、拒過期狀態,重新整理後顯示新狀態。基準版本 agent 沒看過此任務。
- 預期成果
- 審查者重現功能與驗收憑證,驗一個邏輯操作效果和限定範圍的清理,再簽版本綁定的有上限的決策。
限制條件
- • 基準版本與候選版本從等同條件的乾淨提交版本開始,取得同一契約與預算
- • 候選版本只能用已提交的交付檔案,不得有私有個別提示或對話紀錄
- • 審查者要跑乾淨重現、程序崩潰、權限拒絕、機密 canary 與雙 worktree 衝突
- • 關鍵失敗必須 hold 或 no-go,直到新版本通過固定測試集
實作範例
理解程式庫變快,也不能抵銷復原失敗
證據類型: 具名模擬情境候選版本比基準版本更快找到狀態轉移邊界,差異也較集中,人工介入較少。正常流程全過;獨立程序崩潰演練卻發現恢復沿用已到期核准,重新授權前就準備派送執行。
過期權限關鍵驗收高於工作效率變化量,決策維持待補件後再審。團隊將授權驗證移到恢復資格前,失敗加入開發與保留評測,再由新的審查者乾淨重現。
第二版拒絕過期核准,只寫一筆稽核,也通過衝突測試且未影響另一個 worktree。決策只允許已評測的狀態轉移任務在指定時間和預算內執行。台帳與地圖已足夠,因此移除功能重複的文字摘要產生器。
主張限制
決策僅適用已記錄的提交版本、harness 版本、任務類型、模型/工具設定、預算與測試資料。正式環境資料、更廣的寫入、程式庫重整或更多工作單元都要新證據。
做法
照著做,每一步都有檢查點
現場情境
完成的 Harness 是否足以支援提議的無人看守時間?哪些層有證據應保留、哪些要修改或移除?
- 01組裝並驗交付檔案清單
- 02跑等同條件的基準版本/候選版本
- 03挑戰並簡化候選版本
驗收條件
全新審查者能重現任務,依證據說明通過原因,測試安全停止、恢復及隔離清理,再簽只適用於精確版本和範圍的自治決策。
- 01
組裝並驗交付檔案清單
各模組的檔案連到來源提交版本、版本、負責人、健康檢查、證據與移除方式。保留評測前先處理失效連結、到期例外、過期地圖、未提交變更、缺測試資料與憑證不一致。
檢查點 · 乾淨複製程式庫用一個指令驗清單;Harness Card 每個主張都解析到可執行的控制或證據。
- 02
跑等同條件的基準版本/候選版本
同一固定 request-reopen 任務分別不使用新 harness 與使用已凍結的候選版本。保存所有試跑,按評分規準比行為、關鍵控制、人工介入、範圍、理解程式庫、復原、時間、成本、脈絡與審查。
檢查點 · 兩份報告綁同一範圍,所有環境/模型差異揭露,關鍵失敗沒藏在工作效率變化量。
- 03
挑戰並簡化候選版本
執行過期核准、unknown 寫入、機密 canary、skipped 瀏覽器、衝突與破壞性目標。逐層寫收益、成本、負責人、移除條件,刪一個無證據層,重跑完整測試集。
檢查點 · 關鍵案例通過,移除的層沒有隱藏依賴;縮小後的 Harness 仍能讓全新工作階段理解現況並安全復原。
- 04
交給獨立審查者重現
只給程式庫、標準入口和測試資料權限。審查者自行初始化、檢查或完成保留任務,跑驗收、中斷恢復、指定範圍清理及檔案核對,再簽 go、hold 或 no-go。
檢查點 · 審查者從乾淨環境重現證據,不靠對話說明上限與下一個操作,決策綁精確版本。
- 05
設定營運/維護契約
定支援任務、無人看守時間、負責人、監測、抽查、緊急停止權責、事故處理、更新條件、健康檢查排程、維護預算、回復方案與重新評估條件。
檢查點 · 最終備忘錄列受限範圍、具名負責人、關鍵停止條件、下次審查日期與較簡單的備援方式。
實務脈絡
展示版之後
組成可重現 Harness Card
Harness Card 列支援及排除的任務、程式庫入口、正式狀態、初始化程序、環境、工具、權限、規則、評測、預算、停止原因、操作效果、復原、緊急停止與交接。另列負責人、證據保存期限、健康檢查及移除指令。每項主張連到能執行或驗證它的檔案。
記錄模型、工具、環境、lockfile、測試資料、契約、指引、規則、評測器和產生器版本。分開呈現已驗證事實、假設與合成測試結果。審查者應能看出哪些規則由程式執行、哪些判斷仍靠人,以及哪些項目未驗。
用變化量與關鍵驗收門檻決定
基準版本/候選版本比正確性、驗收涵蓋程度、完成如實回報、人工介入、已變更的範圍、理解程式庫、復原、經過時間、總計成本、脈絡數量與審查工時。權限、重複操作效果、機密、破壞性操作、證據完整性與環境隔離失敗都是阻礙,不能由平均改善抵銷。
逐層列已觀察到的收益、持續成本、負責人、失敗情況與移除條件。只保留支援限定範圍的決策的最小集合。沒有證據或風險理由的層就移除,再跑完整測試集,證明簡化沒有藏著依賴。
交付補強
交付清單要能從乾淨複製的程式庫解析,不依賴建置者未提交的檔案、全域套件或手動服務。每份交付檔案記路徑、雜湊、來源模組、負責人、輸入版本、健康檢查指令、使用端與移除方式。執行前核對工作區身分,避免操作另一個程式庫的同名 `.harness`。重現憑證明列無法避免的外部變動,接手者應能只靠文件與證據重跑。
之前/之後比較要保留同一任務價值。基準版本不應故意拿掉一般程式庫文件或使用較差環境,候選版本也不能取得保留評測私人提示。兩者使用等同條件的契約、測試資料、模型設定、預算與審查者評分規準;若 lockfile 或供應商版本無法相同,要在報告分欄揭露,避免把外部變更誤算成 harness 改善。所有試跑都保存,失敗執行不能以暖機名義刪除。
層決策表是總整的核心。每一列寫它修正哪個基準版本證據、保護哪個邊界、由哪個檢查驗、帶來多少理解程式庫/人工介入/失敗復原改善、每週維護成本、負責人、已知失敗與移除條件。若只有『最佳實務』卻沒有本程式庫的理由,先移除再跑測試集。若移除造成全新工作階段走錯路,該失敗反而補上了保留層的直接證據。
未參與開發的審查者不只重跑正常流程。要刻意讓瀏覽器缺漏、核准已到期、寫入結果 unknown、機密 canary、worktree 衝突與 dangerous 清理目標出現,觀察 harness 是否停在正確終止。審查者也要從驗收憑證追到來源證據,驗提交版本與環境綁定。只要需要建置者說『這一關平常不用跑』,就代表必要驗收清單或課程說明仍有隱藏假設,應回到候選版本修正。
限定範圍的決策要寫允許與不允許。可以批准請求狀態轉移類任務在合成或已授權環境中,最多一個工作單元、指定回合/時間/支出、關鍵驗收全過、具名操作人員可緊急停止。程式庫重整、新的依賴、正式環境資料、外部寫入、更廣的 roles、額外工作單元與長期無人監督都在範圍外。當任一版本、權限、工具、資料或任務類型改變,決策自動進審查,不延續舊驗收憑證。
維護契約要指定平日誰看、事故時誰停、多久抽查執行軌跡、何時跑完整保留評測、例外最長多久、地圖如何更新、交付檔案保存多久、成本超標怎麼備援。回復版本不只回退程式碼,也要停需求接收、處理尚在執行的操作效果、恢復上一版規則/契約,並重新驗環境。若團隊無法負擔這份維護,正確決策可能是縮小無人看守的時段或只保留理解程式庫/驗證層。
最後的證據包要讓決策者看見通過與未解問題。首頁列精確版本、已支援的範圍、關鍵驗收、乾淨重現、邏輯操作效果、衝突結果、成本範圍與審查者決策;後面才附執行軌跡、差異、screenshots 與詳細表格。任何失敗被修復後,原失敗驗收憑證仍保留並連到修正提交版本,不能只呈現最後一次綠燈。殘餘風險要有負責人、期限與會改變決策的事實,避免用『後續持續觀察』當無責任的收尾。
課程完成不等於正式環境上線。若真實程式庫含客戶資料、部署憑證、外部寫入或受管制流程,需另做資料授權、威脅模型、供應商行為確認、目標環境的評測、事故演練與權責主管核准。可以重用交付檔案的形狀與檢查思路,不能重用測試資料的結果與閾值。最終備忘錄應明確寫出這條邊界,避免團隊把訓練驗收憑證當成正式環境的發布證據。
獨立簽核要分責任。工程審查者確認程式庫、狀態、規則、測試、復原與清理;安全審查者確認身分、權限、機密、操作效果與破壞性邊界;營運負責人確認預算、警示、緊急停止、事故、維護與範圍;產品或領域負責人確認任務合約與使用者結果。人數不足時可以由同一人依序扮演不同角色,但紀錄仍分開,不能一個『看起來沒問題』勾掉所有責任。任何角色選 hold,最終決策就列缺口、負責人、期限與重跑條件。
交付後安排第一次健康狀態審查,不等到事故才看。檢查全新環境啟動理解程式庫、規則誤判、例外存續時間、評測一致性、復原演練、操作人員負擔、成本尾端表現與實際任務範圍是否漂移。若團隊開始用 harness 做未批准工作,先縮回規則與需求接收,不以補更多警告文字處理。若使用率低到維護不划算,保留最有價值的程式庫地圖與驗證指令,其餘安全移除。決策的價值在於持續守住範圍,也允許根據證據簡化。
結案時將下一次重新評估條件寫成可檢查清單,例如模型或工具升版、權限擴大、工作圖增加節點、資料類別改變、重大規則失效、成本尾端超標或兩次復原演練未過。任何一項出現,原決策就轉為待審。
動手實作
交付 Harness Card 與未參與開發的重現
組裝所有課程交付檔案,跑基準版本/候選版本保留評測,只透過有版本紀錄的變更修復,移除一個低價值層,再由獨立審查者驗收與簽決策。
準備項目
- • 固定保留評測契約、關鍵門檻、人工評分規準、環境建立步驟、預算、清單與基準提交版本
- • 審查者不取得舊對話、私人筆記、正式環境存取或超出測試範圍的權限
本課產出
可執行的既有程式庫、Harness Card、附雜湊的檔案清單、基準與候選報告、保留評測憑證、乾淨環境重現紀錄、中斷及權限演練、交接資料、維護預算、各層取捨表與簽核範圍備忘錄。
起始模板: Harness Card
Markdown# Release Desk Harness Card
Supported task class:
Excluded work:
Authoritative state:
Initializer and isolation:
Tools and permissions:
Mechanical rules:
Verification and receipts:
Budgets and terminal reasons:
Recovery, kill, and handoff:
Owners, health, and removal:
Decision and review date:可下載的實作檔
Harness Card
HARNESS-CARD.md · Markdown
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-10-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:capstone -- --manifest .harness/artifacts.json --clean --blind-review預期 receipt
PASS he-10 brownfield-capstone
cleanReproduction=true criticalFailures=0 removedLayers=1
logicalEffects=1 collisionScopeViolations=0 decision=scoped-go預期結果
全新審查者能重現任務,依證據說明通過原因,測試安全停止、恢復及隔離清理,再簽只適用於精確版本和範圍的自治決策。
留給下一課
保留程式庫作為參考實作。任務類型、程式庫、模型、工具、資料、權限或規模改變時,重新診斷,檢查契約及威脅邊界,再做目標環境評測與營運審查。
驗收條件
- 01交付檔案清單在乾淨複製程式庫通過,綁檔案、規則、測試資料、驗收憑證、指令、提交版本、負責人與移除
- 02基準與候選範圍相同,報正確性、關鍵失敗、人工介入、理解現況、復原、時間、成本、脈絡與審查負擔
- 03過期核准、unknown 寫入、機密、skipped 瀏覽器、衝突與破壞性目標都回安全結果
- 04獨立審查者重現完整驗收憑證,簽有上限與審查日期的決策
- 05至少移除一個不受支持的層,完整測試集證明更簡單的 harness 保留所需行為與控制
常見故障
故障診間
F1只有建置者口頭補隱藏設定,總整專案才能 pass。
- 先檢查
- 比較已提交的指引、初始化程序、環境驗收憑證、私有筆記與人工操作。
- 可能原因
- 營運知識仍在聊天或個人記憶,不在正式紀錄。
- 修復方式
- 停止審查,將缺口寫入程式庫或確定性的設定,新增全新環境啟動測試資料後重來。
- 下次怎麼避免
- 審查者無先前脈絡,每次個別提示都算理解程式庫失敗。
F2工作效率改善,但權限或復原驗收門檻 fail。
- 先檢查
- 將速度變化量和權限、操作效果、機密、範圍、復原、驗收憑證分開看。
- 可能原因
- 決策用平均結果,必要控制被當次要指標。
- 修復方式
- 維持 hold 或 no-go,修正邊界、建立新候選版本,再重跑開發及保留評測。
- 下次怎麼避免
- 事前寫關鍵驗收門檻,不被時間或成本改善抵銷。
F3最終 harness 檔案很多,沒人能說明幾個層為何存在。
- 先檢查
- 逐層查收益、用量、維護、失敗涵蓋程度、負責人與移除條件。
- 可能原因
- 從範例累積交付檔案,沒有證據保護此程式庫。
- 修復方式
- 逐一移除不受支持的層,跑完整測試集,更新 Harness Card。
- 下次怎麼避免
- 各層都要有已觀察的收益或明確風險理由,以及具名負責人。
展示版之後
正式上線前的邊界
- 01Harness Card 說明已支援的/排除的任務、權限來源、資料、環境、操作效果、預算、負責人與審查日期
- 02各檔案已提交、有版本和雜湊,附證據、通過健康檢查,並指定負責人及移除方式
- 03基準版本/候選版本使用等同條件的契約、測試資料、關鍵驗收門檻、預算與證據
- 04乾淨重現涵蓋初始化、任務、完整驗證、中斷、復原、權限拒絕與限定範圍的清理
- 05關鍵操作效果、機密、權限、破壞性操作、隔離與證據失敗強制 hold/no-go
- 06最終範圍附監測、審查抽樣、緊急停止、事故處理、維護、回復與重新評估方式
- 07不受支持的支援結構移除後,較小候選版本通過完整測試集才交接
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。
- [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]長時間應用程式開發的 harness 設計planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨
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
- [6]Harness Engineering 學習指南repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理
deusyu · 公開案例 · 2026-08-26
延伸的 Tenten 資源