這一課會完成什麼
- 整合 task contract、knowledge、initializer、isolation、state、tools、rules、eval、observability、recovery 與 graph policy
- 用 equivalent scope 執行 before/after holdout,保留完整 trials
- 用 Harness Card 說清 boundary、budget、receipt、failure policy、owner 與 removal
- 做 scoped go、conditional hold 或 no-go,刪除沒有產生可量價值的 scaffolding
開始前先準備
- • 模組 00 到 09 的 artifacts 與 passing receipts
- • 全新 Release Desk clone、locked request-reopen holdout、未參與建置的 reviewer 與 fixture-only identity
先把定義說清楚
棕地 harness 總整
Capstone 是對真實形狀、但資料完全合成的 brownfield repository 做 evidence-backed retrofit。完成範圍包含功能 change、可重現 harness、完整 acceptance receipt、recovery 與 security drills、乾淨 handoff、maintenance plan,以及只適用已評 task class 的 operating decision。目標不是堆出最多檔案;每一層都要保護具名 boundary,或帶來足以負擔維護成本的改善。
Harness engineering 要由另一個人從 clean environment 進入 repository、理解架構、完成任務、檢查 evidence、中斷後安全 resume,並得到同一 release decision,才算真正交付。流程圖與錄好的成功 session 都不能替代 blind reproduction。
Final decision 也要留下不確定性。Candidate 可能縮短 orientation、減少 intervention,卻在 recovery drill 失敗;這是 hold,不是降低 gate 的理由。反過來,某個複雜 summary generator 若沒有增加正確率或降低交接成本,移除它也是成功的 harness outcome。
現場情境
用未見過的 request reopening 驗 harness
Release Desk、holdout、runs、metrics、reviewer、failure 與 decision 均為合成教材。
- 負責人
- 你是要向 skeptical engineering lead 與 independent reviewer 交付 repository retrofit 的 harness engineer。
- 要做的決策
- Completed harness 是否足以支援 proposed unattended window,哪些 layers 要保留、修改或移除?
- 目前狀態
- Request changes 已完成。Holdout 要求 authorized reviewer 能用 reason reopen resolved request,保留一筆 audit effect、拒 stale state,refresh 後顯示新狀態。Baseline agent 沒看過此 task。
- 預期成果
- Reviewer 重現 feature 與 receipts,驗一個 logical effect 和 scoped cleanup,再簽版本綁定的 bounded decision。
限制條件
- • Baseline 與 candidate 從 equivalent clean commits 開始,取得同一 contract 與 budgets
- • Candidate 只能用 committed artifacts,不得有 private coaching 或 transcript
- • Reviewer 要跑 clean reproduction、crash、permission denial、secret canary 與 two-worktree collision
- • Critical failure 必須 hold 或 no-go,直到新版本通過 locked suite
實作範例
Orientation 變快,也不能抵銷 recovery failure
證據類型: 具名模擬情境Candidate 比 baseline 更快找到 transition boundary,diff 也較集中,人工介入較少。Happy path 全過;獨立 crash drill 卻發現 resume 沿用 expired approval,重新授權前就準備 dispatch。
Stale-authority critical gate 高於 productivity delta,決策維持 conditional hold。團隊將 authorization validation 移到 resume eligibility 前,failure 加入 development 與 holdout,再由新的 reviewer clean reproduce。
第二版拒 stale approval、保持一筆 audit effect、通過 collision,另一個 worktree 未受影響。決策只允許 evaluated transition task class 的 bounded unattended window;重複功能的 narrative summary generator 因 ledger 與 map 已足夠而移除。
主張限制
Decision 僅適用 recorded commit、harness version、task class、model/tool setup、budgets 與 fixtures。Production data、broader write、repository restructure 或更多 workers 都要新 evidence。
做法
照著做,每一步都有檢查點
現場情境
Completed harness 是否足以支援 proposed unattended window,哪些 layers 要保留、修改或移除?
- 01組裝並驗 artifact manifest
- 02跑 equivalent baseline/candidate
- 03挑戰並簡化 candidate
驗收條件
Fresh reviewer 能重現 task、說明為何 pass、安全停止與恢復、確認 isolated cleanup,並在不信任 builders 敘事的情況下 defend version-bound autonomy decision。
- 01
組裝並驗 artifact manifest
每個模組 artifact 連 source commit、version、owner、health、evidence 與 removal。Holdout 前先修 broken link、expired exception、stale map、dirty branch、missing fixture 與 inconsistent receipt。
檢查點 · Clean clone 用一個 command 驗 manifest;Harness Card 每個 claim 都解析到 executable control 或 evidence。
- 02
跑 equivalent baseline/candidate
同一 locked request-reopen task 分別不使用新 harness 與使用 frozen candidate。保存所有 trials,按 rubric 比 behavior、critical controls、intervention、scope、orientation、recovery、time、cost、context 與 review。
檢查點 · 兩份 report 綁同一 scope,所有 environment/model 差異揭露,critical failure 沒藏在 productivity delta。
- 03
挑戰並簡化 candidate
執行 stale approval、unknown write、secret canary、skipped browser、collision 與 destructive target。逐 layer 寫 benefit、cost、owner、removal trigger,刪一個無證據 layer,重跑 full suite。
檢查點 · Critical fixtures 通過;removed layer 沒 hidden dependency;較小 harness 仍能 cold orient 與 recover。
- 04
交給 reviewer blind reproduce
只給 repository、standard entry 與 fixture access。Reviewer 自行 initialize、檢查或完成 holdout、跑 acceptance、中斷/resume、scoped cleanup、驗 artifacts 並簽 go/hold/no-go。
檢查點 · Reviewer 從 clean environment 重現 evidence,不靠 chat 說明 limits 與 next action,decision 綁 exact versions。
- 05
設定 operating/maintenance contract
定 supported tasks、unattended window、owners、monitoring、review sample、kill authority、incident route、update triggers、scheduled health、maintenance budget、rollback 與 reevaluation facts。
檢查點 · Final memo 有 narrow scope、accountable humans、critical stop、next review date 與 simpler fallback。
實務脈絡
展示版之後
組成可重現 Harness Card
寫 supported task class、excluded work、repository entry、authoritative state、initializer、environments、tools、permissions、rules、evaluator、budgets、terminal reasons、effects、recovery、kill、handoff、owners、evidence retention、health 與 removal commands。每個 claim 都連到能執行或證明它的 artifact。
記 model、tool、runtime、lockfile、fixture、contract、instructions、rule、evaluator 與 generator versions。Current facts、hypotheses 與 course fixture results 分開;reviewer 要能看出哪一層機械執行、哪一層需要 judgment、哪一項仍未驗。
用 delta 與 critical gates 決定
Baseline/candidate 比 correctness、acceptance coverage、completion honesty、intervention、changed scope、orientation、recovery、elapsed time、total cost、context volume 與 review effort。Permission、duplicate effect、secret、destructive action、evidence integrity 與 environment isolation failure 都是 blocker,不能由平均改善抵銷。
逐 layer 列 observed benefit、ongoing cost、owner、failure mode 與 removal trigger。只保留支援 scoped decision 的最小集合。沒有 evidence 或 risk rationale 的層就移除,再跑完整 suite,證明簡化沒有藏著 dependency。
交付補強
Capstone manifest 要從 clean clone 解析,不接受 builder 本機上的 uncommitted file、global package 或手動開啟服務。每個 artifact 記 path、hash、source module、owner、input version、health command、consumer 與 removal。Command 執行前先驗 workspace identity,避免誤把另一個 repository 的同名 `.harness` 當目標。Reproduction receipt 列出任何 unavoidable external variance,不能用『在我電腦正常』補掉缺少的環境合約。
Before/after comparison 要保留同一任務價值。Baseline 不應故意拿掉一般 repository 文件或使用較差環境,candidate 也不能取得 holdout 私人提示。兩者使用 equivalent contract、fixture、model setup、budget 與 reviewer rubric;若 lockfile 或 provider 版本無法相同,要在 report 分欄揭露,避免把外部變更誤算成 harness 改善。所有 trials 都保存,失敗 run 不能以 warm-up 名義刪除。
Layer decision table 是總整的核心。每一列寫它修正哪個 baseline evidence、保護哪個 boundary、由哪個 check 驗、帶來多少 orientation/intervention/failure recovery 改善、每週維護成本、owner、known failure 與 removal trigger。若只有『最佳實務』卻沒有本 repository 的理由,先移除再跑 suite。若移除造成 cold session 走錯路,該 failure 反而補上了保留層的直接證據。
Blind reviewer 不只重跑 happy path。要刻意讓 browser missing、approval expired、write result unknown、secret canary、worktree collision 與 dangerous cleanup target 出現,觀察 harness 是否停在正確 terminal。Reviewer 也要從 receipt 追到 source evidence,驗 commit 與 environment 綁定。只要需要 builder 說『這一關平常不用跑』,就代表 required registry 或課程說明仍有隱藏假設,應回到 candidate 修正。
Scoped decision 要寫允許與不允許。可以批准 request-state transition 類 task 在合成或已授權環境中,最多一個 worker、指定 turns/time/spend、critical gate 全過、named operator 可 kill。Repository restructure、new dependency、production data、外部 write、broader roles、額外 workers 與長期無人監督都在範圍外。當任一版本、權限、工具、資料或 task class 改變,decision 自動進 review,不延續舊 receipt。
Maintenance contract 要指定平日誰看、事故時誰停、多久抽查 trace、何時跑 full holdout、exception 最長多久、map 如何更新、artifacts 保存多久、成本超標怎麼 fallback。Rollback 不只回退 code,也要停 intake、處理 in-flight effects、恢復上一版 rules/contract,並重新驗 environment。若團隊無法負擔這份維護,正確決策可能是縮小 unattended window 或只保留 orientation/verification 層。
最後的證據包要讓決策者看見通過與未解問題。首頁列 exact versions、supported scope、critical gate、clean reproduction、logical effect、collision result、成本範圍與 reviewer decision;後面才附 traces、diff、screenshots 與詳細表格。任何失敗被修復後,原 failure receipt 仍保留並連到修正 commit,不能只呈現最後一次綠燈。Residual risk 要有 owner、期限與會改變決策的事實,避免用『後續持續觀察』當無責任的收尾。
課程完成不等於 production 上線。若真實 repository 含客戶資料、部署 credential、外部 write 或受管制流程,需另做資料授權、威脅模型、供應商行為確認、target-environment eval、incident drill 與 accountable business approval。可以重用 artifacts 的形狀與檢查思路,不能重用 fixture 的結果與閾值。Final memo 應明確寫出這條邊界,避免團隊把 training receipt 當成正式環境的 release proof。
Independent sign-off 要分責任。工程 reviewer 確認 repository、state、rules、tests、recovery 與 cleanup;安全 reviewer 確認 identity、permission、secret、effect 與 destructive boundaries;營運 owner 確認 budgets、alerts、kill、incident、maintenance 與 scope;產品或 domain owner 確認任務合約與使用者結果。人數不足時可以由同一人依序扮演不同角色,但紀錄仍分開,不能一個『看起來沒問題』勾掉所有責任。任何角色選 hold,final decision 就列缺口、owner、期限與重跑條件。
交付後安排第一次 health review,不等到事故才看。檢查 cold-start orientation、rule false positives、exception age、eval consistency、recovery drills、operator burden、cost tail 與實際 task scope 是否漂移。若團隊開始用 harness 做未批准工作,先縮回 policy 與 intake,不以補更多警告文字處理。若使用率低到維護不划算,保留最有價值的 repository map 與 verification command,其餘安全移除。Decision 的價值在於持續守住範圍,也允許根據證據簡化。
結案時將下一次重新評估條件寫成可檢查清單,例如模型或工具升版、權限擴大、工作圖增加節點、資料類別改變、重大規則失效、成本尾端超標或兩次復原演練未過。任何一項出現,原決策就轉為待審。
動手實作
交付 Harness Card 與 blind reproduction
組裝所有 course artifacts,跑 baseline/candidate holdout,只透過 versioned change 修復,移除一個低價值 layer,再由 independent reviewer 驗收與簽 decision。
準備項目
- • Freeze holdout contract、critical gates、reviewer rubric、environment recipe、budgets、manifest 與 baseline commit
- • Reviewer 不可取得 prior chat、private note、production access 或超出 fixture 的 authority
本課產出
Runnable brownfield repository、Harness Card、hashed artifact manifest、baseline/candidate report、holdout receipts、clean reproduction、crash/permission drills、handoff、maintenance budget、layer decision table 與 signed scope memo。
起始模板: 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預期結果
Fresh reviewer 能重現 task、說明為何 pass、安全停止與恢復、確認 isolated cleanup,並在不信任 builders 敘事的情況下 defend version-bound autonomy decision。
留給下一課
將 repository 保留成 reference implementation,不當成 universal template。Task class、codebase、model、tools、data、authority 或 scale 改變時,重新跑 diagnosis、contract、threat boundary、target eval 與 operating review。
驗收條件
- 01Artifact manifest 在 clean clone 通過,綁 files、rules、fixtures、receipts、commands、commit、owners 與 removal
- 02Baseline/candidate scope equivalent,報 correctness、critical、intervention、orientation、recovery、time、cost、context 與 review
- 03Stale approval、unknown write、secret、skipped browser、collision 與 destructive target 都回 safe outcome
- 04Independent reviewer 重現完整 receipt,簽有 limits 與 review date 的 decision
- 05至少移除一個 unsupported layer,full suite 證明 simpler harness 保留所需行為與控制
常見故障
故障診間
F1只有 builder 口頭補 hidden setup,capstone 才能 pass。
- 先檢查
- 比較 committed instructions、initializer、environment receipt、private notes 與 manual actions。
- 可能原因
- Operational knowledge 仍在聊天或個人記憶,不在 system of record。
- 修復方式
- 停止 review,將缺口寫入 repository 或 deterministic setup,新增 cold-start fixture 後重來。
- 下次怎麼避免
- Reviewer 無 prior context,每次 coaching 都算 orientation failure。
F2Productivity 改善,但 permission 或 recovery gate fail。
- 先檢查
- 將 speed delta 和 permission、effect、secret、scope、recovery、receipt 分開看。
- 可能原因
- Decision 用 average outcome,required controls 被當 secondary metrics。
- 修復方式
- 維持 hold/no-go,修 boundary、version candidate,重跑 development/holdout。
- 下次怎麼避免
- 事前寫 critical gates,不被 time 或 cost 改善抵銷。
F3Final harness 檔案很多,沒人能說明幾個 layer 為何存在。
- 先檢查
- 逐 layer 查 benefit、usage、maintenance、failure coverage、owner 與 removal trigger。
- 可能原因
- 從範例累積 artifacts,沒有證據保護此 repository。
- 修復方式
- 逐一移除 unsupported layers,跑 full suite,更新 Harness Card。
- 下次怎麼避免
- 每層都需 observed benefit 或 named risk rationale 與 accountable owner。
展示版之後
正式上線前的邊界
- 01Harness Card 說明 supported/excluded tasks、authority、data、environment、effects、budgets、owners 與 review date
- 02每個 artifact committed、versioned、hashed、evidence-linked、health-checked、owned 且 removable
- 03Baseline/candidate 使用 equivalent contracts、fixtures、critical gates、budgets 與 evidence
- 04Clean reproduction 涵蓋 initialize、task、full verify、interrupt、recover、permission deny 與 scoped cleanup
- 05Critical effect、secret、permission、destructive action、isolation 與 evidence failure 強制 hold/no-go
- 06Final scope 有 monitoring、review sampling、kill、incident、maintenance、rollback 與 reevaluation
- 07Unsupported scaffolding 移除後,較小 candidate 通過 full suite 才 handoff
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。
- [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 資源