跳至主要內容

harness engineering capstone brownfield coding agent

專案

總整專案:替既有程式庫補上可驗收的 Harness

將完整 harness 套到未見過的功能,從乾淨環境重現證據,只留下量得出價值的層,最後提出有範圍的自治決策。

難度
進階
預估時間
5 到 7 小時
更新日期
2026-10-02
文案複核
speak-human-tw
兩輪
本課內容
  1. 01先把定義說清楚
  2. 02現場情境
  3. 03實作範例
  4. 04照著做,每一步都有檢查點
  5. 05實務脈絡
  6. 06動手實作
  7. 07故障診間
  8. 08正式上線前的邊界
  9. 09資料來源與主張限制

這一課會完成什麼

  • 整合任務契約、知識、初始化程序、隔離、狀態、工具、規則、評測、可觀測性、復原與工作圖規則
  • 在相同範圍執行改造前後的保留評測,保存全部試跑
  • 用 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 版本、任務類型、模型/工具設定、預算與測試資料。正式環境資料、更廣的寫入、程式庫重整或更多工作單元都要新證據。

做法

照著做,每一步都有檢查點

Release Desk 既有系統的程式庫外圍連任務契約、知識、初始化程序、狀態、工具、規則、評測、事件、復原、工作圖、驗收憑證、負責人與限定範圍的決策。

現場情境

完成的 Harness 是否足以支援提議的無人看守時間?哪些層有證據應保留、哪些要修改或移除?

  1. 01組裝並驗交付檔案清單
  2. 02跑等同條件的基準版本/候選版本
  3. 03挑戰並簡化候選版本

驗收條件

全新審查者能重現任務,依證據說明通過原因,測試安全停止、恢復及隔離清理,再簽只適用於精確版本和範圍的自治決策。

這張圖要幫你看懂什麼總整專案系統地圖將每個保留的層連回證據、負責人、健康狀態檢查與移除路徑。
  1. 01

    組裝並驗交付檔案清單

    各模組的檔案連到來源提交版本、版本、負責人、健康檢查、證據與移除方式。保留評測前先處理失效連結、到期例外、過期地圖、未提交變更、缺測試資料與憑證不一致。

    檢查點 · 乾淨複製程式庫用一個指令驗清單;Harness Card 每個主張都解析到可執行的控制或證據。

  2. 02

    跑等同條件的基準版本/候選版本

    同一固定 request-reopen 任務分別不使用新 harness 與使用已凍結的候選版本。保存所有試跑,按評分規準比行為、關鍵控制、人工介入、範圍、理解程式庫、復原、時間、成本、脈絡與審查。

    檢查點 · 兩份報告綁同一範圍,所有環境/模型差異揭露,關鍵失敗沒藏在工作效率變化量。

  3. 03

    挑戰並簡化候選版本

    執行過期核准、unknown 寫入、機密 canary、skipped 瀏覽器、衝突與破壞性目標。逐層寫收益、成本、負責人、移除條件,刪一個無證據層,重跑完整測試集。

    檢查點 · 關鍵案例通過,移除的層沒有隱藏依賴;縮小後的 Harness 仍能讓全新工作階段理解現況並安全復原。

  4. 04

    交給獨立審查者重現

    只給程式庫、標準入口和測試資料權限。審查者自行初始化、檢查或完成保留任務,跑驗收、中斷恢復、指定範圍清理及檔案核對,再簽 go、hold 或 no-go。

    檢查點 · 審查者從乾淨環境重現證據,不靠對話說明上限與下一個操作,決策綁精確版本。

  5. 05

    設定營運/維護契約

    定支援任務、無人看守時間、負責人、監測、抽查、緊急停止權責、事故處理、更新條件、健康檢查排程、維護預算、回復方案與重新評估條件。

    檢查點 · 最終備忘錄列受限範圍、具名負責人、關鍵停止條件、下次審查日期與較簡單的備援方式。

實務脈絡

展示版之後

G1

組成可重現 Harness Card

Harness Card 列支援及排除的任務、程式庫入口、正式狀態、初始化程序、環境、工具、權限、規則、評測、預算、停止原因、操作效果、復原、緊急停止與交接。另列負責人、證據保存期限、健康檢查及移除指令。每項主張連到能執行或驗證它的檔案。

記錄模型、工具、環境、lockfile、測試資料、契約、指引、規則、評測器和產生器版本。分開呈現已驗證事實、假設與合成測試結果。審查者應能看出哪些規則由程式執行、哪些判斷仍靠人,以及哪些項目未驗。

G2

用變化量與關鍵驗收門檻決定

基準版本/候選版本比正確性、驗收涵蓋程度、完成如實回報、人工介入、已變更的範圍、理解程式庫、復原、經過時間、總計成本、脈絡數量與審查工時。權限、重複操作效果、機密、破壞性操作、證據完整性與環境隔離失敗都是阻礙,不能由平均改善抵銷。

逐層列已觀察到的收益、持續成本、負責人、失敗情況與移除條件。只保留支援限定範圍的決策的最小集合。沒有證據或風險理由的層就移除,再跑完整測試集,證明簡化沒有藏著依賴。

G3

交付補強

交付清單要能從乾淨複製的程式庫解析,不依賴建置者未提交的檔案、全域套件或手動服務。每份交付檔案記路徑、雜湊、來源模組、負責人、輸入版本、健康檢查指令、使用端與移除方式。執行前核對工作區身分,避免操作另一個程式庫的同名 `.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

預期結果

全新審查者能重現任務,依證據說明通過原因,測試安全停止、恢復及隔離清理,再簽只適用於精確版本和範圍的自治決策。

留給下一課

保留程式庫作為參考實作。任務類型、程式庫、模型、工具、資料、權限或規模改變時,重新診斷,檢查契約及威脅邊界,再做目標環境評測與營運審查。

驗收條件

  1. 01交付檔案清單在乾淨複製程式庫通過,綁檔案、規則、測試資料、驗收憑證、指令、提交版本、負責人與移除
  2. 02基準與候選範圍相同,報正確性、關鍵失敗、人工介入、理解現況、復原、時間、成本、脈絡與審查負擔
  3. 03過期核准、unknown 寫入、機密、skipped 瀏覽器、衝突與破壞性目標都回安全結果
  4. 04獨立審查者重現完整驗收憑證,簽有上限與審查日期的決策
  5. 05至少移除一個不受支持的層,完整測試集證明更簡單的 harness 保留所需行為與控制

常見故障

故障診間

F1只有建置者口頭補隱藏設定,總整專案才能 pass。
先檢查
比較已提交的指引、初始化程序、環境驗收憑證、私有筆記與人工操作。
可能原因
營運知識仍在聊天或個人記憶,不在正式紀錄。
修復方式
停止審查,將缺口寫入程式庫或確定性的設定,新增全新環境啟動測試資料後重來。
下次怎麼避免
審查者無先前脈絡,每次個別提示都算理解程式庫失敗。
F2工作效率改善,但權限或復原驗收門檻 fail。
先檢查
將速度變化量和權限、操作效果、機密、範圍、復原、驗收憑證分開看。
可能原因
決策用平均結果,必要控制被當次要指標。
修復方式
維持 hold 或 no-go,修正邊界、建立新候選版本,再重跑開發及保留評測。
下次怎麼避免
事前寫關鍵驗收門檻,不被時間或成本改善抵銷。
F3最終 harness 檔案很多,沒人能說明幾個層為何存在。
先檢查
逐層查收益、用量、維護、失敗涵蓋程度、負責人與移除條件。
可能原因
從範例累積交付檔案,沒有證據保護此程式庫。
修復方式
逐一移除不受支持的層,跑完整測試集,更新 Harness Card。
下次怎麼避免
各層都要有已觀察的收益或明確風險理由,以及具名負責人。

展示版之後

正式上線前的邊界

  1. 01Harness Card 說明已支援的/排除的任務、權限來源、資料、環境、操作效果、預算、負責人與審查日期
  2. 02各檔案已提交、有版本和雜湊,附證據、通過健康檢查,並指定負責人及移除方式
  3. 03基準版本/候選版本使用等同條件的契約、測試資料、關鍵驗收門檻、預算與證據
  4. 04乾淨重現涵蓋初始化、任務、完整驗證、中斷、復原、權限拒絕與限定範圍的清理
  5. 05關鍵操作效果、機密、權限、破壞性操作、隔離與證據失敗強制 hold/no-go
  6. 06最終範圍附監測、審查抽樣、緊急停止、事故處理、維護、回復與重新評估方式
  7. 07不受支持的支援結構移除後,較小候選版本通過完整測試集才交接

證據類型

資料來源與主張限制

資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。

  1. [1]知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
  2. [2]
    長時間執行 agent 的有效 harness

    Anthropic · 已發表研究 · 2026-08-26

    initializer 模式 · feature ledger · session 交接 · 端到端驗證
  3. [3]
    長時間應用程式開發的 harness 設計

    Anthropic · 已發表研究 · 2026-08-26

    planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨
  4. [4]
    Learn Harness Engineering

    Walking Labs · 公開案例 · 2026-08-26

    專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
  5. [5]
    Andrej Karpathy 的 AI Engineering Playbook

    AI Builder Club · 公開案例 · 2026-08-26

    Software 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
  6. [6]
    Harness Engineering 學習指南

    deusyu · 公開案例 · 2026-08-26

    repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理

延伸的 Tenten 資源

當本機 harness 要接進真實程式庫

帶著驗收憑證、失敗案例,以及那條還拿不準的控制邊界來。

在團隊拉長 agent 自治時間前,Tenten 可以一起檢查程式庫可讀性、權限、評測器涵蓋、worktree 隔離、復原與上線證據。