harness engineering capstone brownfield coding agent

專案

總整專案:改造棕地 repository,替自治決策負責

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

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

這一課會完成什麼

  • 整合 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。

做法

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

Release Desk brownfield repository 外圍連 task contract、knowledge、initializer、state、tools、rules、eval、events、recovery、graph、receipts、owners 與 scoped decision。

現場情境

Completed harness 是否足以支援 proposed unattended window,哪些 layers 要保留、修改或移除?

  1. 01組裝並驗 artifact manifest
  2. 02跑 equivalent baseline/candidate
  3. 03挑戰並簡化 candidate

驗收條件

Fresh reviewer 能重現 task、說明為何 pass、安全停止與恢復、確認 isolated cleanup,並在不信任 builders 敘事的情況下 defend version-bound autonomy decision。

這張圖要幫你看懂什麼Capstone system map 將每個 retained layer 連回 evidence、owner、health check 與 removal path。
  1. 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。

  2. 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。

  3. 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。

  4. 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。

  5. 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。

實務脈絡

展示版之後

G1

組成可重現 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、哪一項仍未驗。

G2

用 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。

G3

交付補強

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。

驗收條件

  1. 01Artifact manifest 在 clean clone 通過,綁 files、rules、fixtures、receipts、commands、commit、owners 與 removal
  2. 02Baseline/candidate scope equivalent,報 correctness、critical、intervention、orientation、recovery、time、cost、context 與 review
  3. 03Stale approval、unknown write、secret、skipped browser、collision 與 destructive target 都回 safe outcome
  4. 04Independent reviewer 重現完整 receipt,簽有 limits 與 review date 的 decision
  5. 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。

展示版之後

正式上線前的邊界

  1. 01Harness Card 說明 supported/excluded tasks、authority、data、environment、effects、budgets、owners 與 review date
  2. 02每個 artifact committed、versioned、hashed、evidence-linked、health-checked、owned 且 removable
  3. 03Baseline/candidate 使用 equivalent contracts、fixtures、critical gates、budgets 與 evidence
  4. 04Clean reproduction 涵蓋 initialize、task、full verify、interrupt、recover、permission deny 與 scoped cleanup
  5. 05Critical effect、secret、permission、destructive action、isolation 與 evidence failure 強制 hold/no-go
  6. 06Final scope 有 monitoring、review sampling、kill、incident、maintenance、rollback 與 reevaluation
  7. 07Unsupported scaffolding 移除後,較小 candidate 通過 full suite 才 handoff

證據類型

資料來源與主張限制

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

  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 要接進真實 repository

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

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