這一課會完成什麼
- 用 inputs、outputs、ownership、conflict zone 與 gate 表達 eligible work graph
- 比較 sequential/parallel 的 wall time、總成本、overlap、integration failure 與 reviewer burden
- 設計 merge/handoff contract,避免兩個 worker 擁有同一 mutable surface
- 建立 instruction、generated facts、exception、fixture、rule 與 receipt 的 entropy checks
開始前先準備
- • 模組 00 到 08 的 eval、isolated worktrees、ledger、events 與 recovery controls
- • 兩個獨立 holdout task 加一個刻意 overlap 的 collision fixture
先把定義說清楚
Graph、平行與 entropy
Work graph 是一組 versioned task nodes,每個 node 宣告 dependency evidence、owned outputs、protected paths、mutable resources、budget 與 verification gate。只有 upstream receipt 齊全、環境健康、ownership 不和 active work 重疊的 node 才 eligible。Entropy control 則持續檢查 repository instructions、generated maps、fixtures、rules、exceptions、links 與 receipts 是否仍描述目前 source。
平行 session 在任務真的獨立且環境隔離時可以縮短等待,也可能成倍增加 model 與 tool 成本、重複搜尋、爭用 fixture、產出不相容抽象,最後把工作量推給 integration。Worker count 是需評測的 operating choice,不是架構越多就越先進。
Harness 也會跟 code 一起老化。Package 改名後 instructions 還指舊路徑、generated map 沒更新、exception 超期、test registry 漏掉新 route、ledger 連到不存在 evidence。Stale harness 會讓 agent 很有把握地走錯,所以維護本身要有 health command 與預算。
現場情境
兩個 worker 很快,integration 卻壞了
Task graph、branches、timing、cost、conflict 與 health findings 都是合成 fixture。
- 負責人
- 你是判斷 Release Desk 是否能跑兩個 concurrent coding tasks 的 platform lead。
- 要做的決策
- 兩個 task 能否同時跑,要如何改 graph 才能讓下一次 parallel trial 有證據?
- 目前狀態
- Task A 加 request-change reasons,Task B 加 audit export。兩者都改 shared transition schema 與 seed。分支 focused tests 通過,combined branch 的 migration order 失敗並遺失 enum。
- 預期成果
- Dispatch 前抓 overlap,shared schema 成為 upstream node,後續獨立 UI/export nodes 才平行,最後比較 integrated receipts。
限制條件
- • 每個 worker 有獨立 worktree、environment、port、data、cache、log、screenshot 與 process owner
- • Dependency 或 conflict 未通過不得 dispatch
- • Sequential 與 two-worker 使用 equivalent contract 與 integrated output
實作範例
Graph 移除假的獨立性
證據類型: 具名模擬情境初版按 feature 名稱分兩個 worker。Path declarations 顯示兩者都碰 transition-schema、migration metadata 與同一 seed。Unguarded trial 雖然 coding wall time 較短,integration 要人工修 conflict,且少跑一個 acceptance case。
新版 graph 建 schema-contract node,由單一 owner 完成,兩個 feature nodes 等 receipt 通過才 eligible。後續分別擁有 UI 與 export package、獨立 fixture namespace;integration node 重建 map、跑 combined migration 與完整 eval。
第二次 fixture trial 沒有 overlapping writes 或 lost tests。Wall time 在合成案例改善,總 compute 與 coordination 仍比 sequential 高。決策只允許 graph-certified nodes 使用兩個 worker,共用 schema 維持 sequential。
主張限制
結果依 repository topology、task duration、model、tool 與 reviewer 流程。其他 codebase 要先做自己的 collision 與 cost comparison。
做法
照著做,每一步都有檢查點
現場情境
兩個 task 能否同時跑,要如何改 graph 才能讓下一次 parallel trial 有證據?
- 01宣告 nodes 與 conflict zones
- 02跑 equivalent sequential/parallel
- 03驗 branch 與 integrated truth
驗收條件
系統拒絕 overlapping parallel work,eligible work 通過 integrated acceptance,完整報 coordination tradeoff,也會在 stale harness 誤導 session 前抓出五種 drift。
- 01
宣告 nodes 與 conflict zones
每個 node 記 contract、upstream evidence、owned/protected paths、mutable resources、output receipt、budget、verifier 與 merger。用 static/generated analysis 找 shared schema、fixture、migration 與 config。
檢查點 · 原 two-node graph 因 overlap 被拒;revised graph 將 shared schema 變成 verified upstream。
- 02
跑 equivalent sequential/parallel
同一 final scope 先 sequential,再以兩個 eligible workers 跑。記 wall time、總 model/tool、retry、duplicate read、paths、conflict、integration repair、review time 與 critical failure。
檢查點 · 兩次達 equivalent integrated behavior;若沒有,就誠實記 no-go,不事後修 evidence。
- 03
驗 branch 與 integrated truth
驗每個 branch receipt、commit、environment,merge eligible outputs,重建 facts,再跑 migrations、rules、eval、browser、effects 與 receipt。Conflict 留成 named decision。
檢查點 · Integrated receipt 涵蓋每個 node、changed path、conflict、effect、fixture 與 verification layer。
- 04
Seed 並修 harness entropy
破壞 instruction link、讓 exception 到期、stale route map、orphan receipt、移除 fixture target。跑 health,由 owner 修復,記 maintenance time 與 trigger 改動。
檢查點 · 五個 drift fixtures 各回 distinct code,clean state 通過,map receipt 帶 source commit。
實務脈絡
展示版之後
依 ownership 與 evidence 排程
Node 寫 task contract、dependency receipts、owned paths、protected paths、environment resources、budget、artifacts、merge conditions 與 verifier。Eligibility 同時檢查 upstream、health、ownership 與 contract。Coordinator 不能用一段模糊 assignment 讓重疊工作看似獨立。
整合時看 receipts 與 diffs。每個 branch 單獨驗,combined state 再驗。兩個分支對 architecture 或 evidence 有衝突,要保存雙方並進 named decision,不能請模型把衝突揉成聽起來合理的 code。
把 harness maintenance 納入工程成本
Health command 檢查 instruction links、map freshness、source access date、fixture target、rule parity、exception expiry、ledger evidence 與 orphan artifact。快檢查放每次 change,較慢 regeneration 依 schedule 或 relevant path 觸發。
報 harness change 與 feature change:maintenance time、false positive、stale finding、regenerated artifact 與 reviewer burden。若 scaffolding 長期比它節省的時間更貴,就應簡化,不用為了完整感保留。
交付補強
Graph validator 不能只比 glob 是否字面重疊。Route package 可能透過 generator 共同修改 registry,兩個 migration 雖在不同檔名仍共享 sequence,fixture namespace 也可能寫同一 record。Ownership manifest 應納入 generated outputs、schema resources、configuration keys、database tables、cache namespace 與 test registry。無法可靠判斷的 shared surface 先設 conflict zone,由 upstream contract node 整理後再考慮平行。
Coordinator 自己也要被預算與評測。它產生 graph、分派 task、追 receipts、取消 worker、處理 failure 與整合 output,都會花 model calls 與 reviewer attention。Comparison report 將 coordinator、workers、tools、duplicate reads、cancelled work、merge repair 與 final verification分開計費。若兩個 worker 只省等待,卻讓總成本、critical risk 或 review 增幅超出事前門檻,decision 可以回到 sequential,沒有必要替 parallel 找理由。
Worker contract 要提供足夠脈絡又避免擴權。每個 worker 取得 node contract、upstream receipts、owned paths、protected paths、environment map、tool allowlist、budget、expected artifacts、terminal policy 與 handoff schema。它不能順手修另一個 node,即使看到明顯問題;應建立 finding 交給 coordinator。這保留 ownership,也避免一位 worker 的好意在另一分支造成難以追蹤的 conflict。
Merge 不是把 diff 套上去就結束。先驗 branch receipt 與 commit,再檢 ownership、exception、migration order、generated facts、dependency graph 與 fixture versions。Conflict decision 寫 chosen change、rejected alternative、owner、reason 與 affected tests。Combined commit 從 fresh environment 跑 full verification;任何 branch pass 不能替代 integration receipt,也不能在 merge 後刪掉失敗 case 來維持綠燈。
Entropy finding 要能定位 owner 與 repair。Broken link 指向哪份 instruction、stale map 差哪個 source commit、expired exception 曾 match 哪些 files、orphan receipt 缺哪個 feature、missing fixture 由哪個 suite 使用,都要清楚。Health command 不應只輸出總分,因為平均健康度會掩蓋一條關鍵 startup link 已斷。Blocking 與 advisory 分開,threshold 變更也保留 decision record。
Scheduled maintenance 應有上限與刪除策略。每週 full health 若花費持續上升,先看 generator 是否重複、links 是否能 incremental、artifact 是否已無 consumer。沒有 task、rule、eval 或 reviewer 使用的產物,可以先標 deprecated、觀察一個週期,再從 manifest 與 instructions 移除。Repository 變得較小且仍通過 cold-start 與 full suite,是 entropy control 的正向結果。
平行取消也要有合約。Upstream node 失敗、budget 用盡或 operator kill 時,尚未 dispatch 的 children 直接取消;執行中的 worker 停止新工具,保存 handoff 與 outstanding effects,再由 coordinator 依 ownership 清理。不能因某個 branch 已花成本就讓它繼續修改失去前提的 code。Cancelled artifact 保留供診斷,但不進 merge eligibility;若要重新使用,必須對新 upstream receipt 做明確 rebase 與完整驗證。
整合 reviewer 需要一張 coverage table。每個 node 的 promised output、receipt、changed paths、tests、effects 與 limitation 逐列核對,缺一項就不生成 complete。兩個 worker 對同一 invariant 給相反判斷時,保存兩份證據交給 owner,不用語言模型投票。這張表也顯示哪些來源或探索重複,讓下次 graph 可以調整 node 邊界,而不是把協調浪費當成 unavoidable overhead。
擴大 worker 數前,先在相同 task graph 做二到三種設定。從一個 worker、兩個 eligible workers 開始,只有 wall time 有明確業務價值、critical failures 不增加、總成本與 review 在上限內、recovery drill 仍通過,才考慮下一級。Worker limit 寫進 policy 與 budget,不由 coordinator 自由決定。遇到 shared schema 或高衝突工作,自動 downgrade 到 sequential 是正常控制,不是系統失敗。
Graph 也要支援人工決策節點。當兩個方案牽涉 domain 取捨、資料遷移不可逆或權限範圍改變時,node 的 output 是 decision packet,不是直接修改 source。Packet 列 alternatives、evidence、affected nodes、rollback 與 deadline,由具名 owner 選定後產生 signed receipt,children 才 eligible。若到期沒有決定,graph 進 blocked,不讓 coordinator 以預設選項繼續。這種節點讓工作圖同時表達技術 dependency 與 authority dependency,避免平行 worker 各自猜一個方向。
Entropy review 要回看 agent 實際使用哪些 artifacts。Trace 顯示某份 instructions 從未被讀取,可能是導航失效,也可能是檔案已無價值;某張 map 每次都被讀卻經常導致 manual correction,表示內容可信度不足。將讀取、finding、correction、generation cost 與 owner feedback 放在一起,再決定改善或移除。不能只用檔案最後修改日期判 freshness,因為一份昨天更新但來源錯誤的地圖,比半年未變且仍對應穩定 invariant 更危險。
工作圖版本要和每個 receipt 綁定。Coordinator 若在執行中新增 dependency、改 ownership 或放寬 budget,active nodes 不會自動採新設定;先停止受影響工作,保存 handoff,再由 owner 決定取消或以新 graph 重新啟動。這能避免某個 worker 按舊邊界修改,另一個已按新邊界接管相同資源。Graph diff 列新增與移除節點、依賴、路徑、資源、工具、預算與 reviewer,並重跑 overlap fixtures。只有文字說明變更、不影響執行邊界時,才允許不重啟。
Entropy 修復也要防止自動化造成大範圍修改。Generator 可重建 map 或索引,但刪除 unknown artifact、改 owner、更新 exception、重寫 instructions 都需要明確規則或人工 review。Health command 預設只讀並輸出 repair plan;真正 mutation 使用 exact targets、Git diff 與 rollback。若修復後變更超出 maintenance budget,拆成多個 owned tasks,不讓清理工作趁機重構產品 source。最後跑 cold-start orientation 與 full links,證明 repository 更容易理解,而非只是檔案時間都變新。
動手實作
執行 two-worker graph 與 entropy audit
建立三個 nodes,拒 seeded overlap,將 shared schema 拆 upstream,跑 isolated branches 與 integration,再故意讓 harness artifacts 老化並抓出。
準備項目
- • 為 sequential 與 parallel trial 建立 explicit worktree/environment,不碰其他本機專案
- • Freeze contracts、integrated behavior、critical gates、cost fields、overlap policy 與 health manifest
本課產出
Validated graph、ownership report、sequential/parallel receipts、isolation proof、integration evidence、decision memo、health manifest、drift fixtures 與 maintenance budget。
起始模板: Work graph manifest
YAMLnodes:
schema-contract:
dependsOn: []
owns: ["src/domain/transition-schema.ts", "migrations/rd-transition/**"]
outputs: ["receipt:schema-contract"]
request-reasons:
dependsOn: ["schema-contract"]
owns: ["src/app/requests/**"]
verify: ["npm run harness:eval -- --case RD-REASONS"]可下載的實作檔
Work graph manifest
work-graph.yml · YAML
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-09-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:graph -- --manifest .harness/work-graph.yml --compare --entropy預期 receipt
PASS he-09 graph-and-entropy
eligibleWorkers=2 overlapsAccepted=0 integrationCriticalFailures=0
entropyFixturesCaught=5 decision=bounded-parallel預期結果
系統拒絕 overlapping parallel work,eligible work 通過 integrated acceptance,完整報 coordination tradeoff,也會在 stale harness 誤導 session 前抓出五種 drift。
留給下一課
Graph、comparison 與 health manifest 會進 capstone。Scaling 只能建立在 measured integrated value 上,並保留回到 simpler execution 的 rollback。
驗收條件
- 01Graph validation 在 dispatch 前擋 active path、migration、fixture、config 或 mutable resource overlap
- 02Comparison 包 equivalent scope、總成本、review、conflicts、critical 與 integrated evidence
- 03每個 worker 的 network、data、cache、log、screenshot、process、fixture 與 cleanup 隔離
- 04Health 抓 broken instructions、expired exception、stale map、orphan receipt 與 missing fixture
常見故障
故障診間
F1兩個 branch 單獨 pass,merge 後少一個 case。
- 先檢查
- 看 owned paths、shared fixtures、migration order、generated maps、test registry 與 integration receipt。
- 可能原因
- Feature label 被當成獨立性,沒有 combined verification。
- 修復方式
- 恢復 lost case、建立 upstream shared-contract node、重跑 branch/integration。
- 下次怎麼避免
- Dispatch 前驗 path/resource conflict,並要求 integration node。
F2Parallel wall time 變短,review 與總成本卻翻倍。
- 先檢查
- 拆 coordinator、workers、tools、retry、duplicate source、conflict repair 與 review。
- 可能原因
- 決策只看 coding elapsed,漏掉 coordination 與 evidence。
- 修復方式
- 重算完整 comparison,降低 workers 或將 dependent tasks 改回 sequential。
- 下次怎麼避免
- 每次 scaling experiment 預先定 value、quality、cost、review 與 critical gates。
F3Map 很有自信地指向 deleted route。
- 先檢查
- 查 generator version、source commit、path trigger 與 health receipt。
- 可能原因
- Generated knowledge 沒有 freshness contract 或 fail 不 blocking。
- 修復方式
- 從 current commit regenerate、修 trigger、加 stale fixture。
- 下次怎麼避免
- Relevant path change 必須通過 freshness verification。
展示版之後
正式上線前的邊界
- 01Node 宣告 dependencies、inputs、owned outputs、conflicts、resources、budgets、verifier 與 merger
- 02Eligibility 擋 unresolved dependency、overlap、unhealthy environment、stale contract 與 missing receipt
- 03Worker 隔離 network、data、cache、log、screenshot、process、fixture 與 cleanup
- 04Parallel decision 比 equivalent integrated quality、critical、wall time、total cost、review 與 recovery
- 05Integration 驗 branch receipts、conflict、generated facts、migration、rules、eval、browser 與 effects
- 06Harness health 查 instructions、maps、sources、fixtures、rules、exceptions、ledgers、receipts 與 orphan artifacts
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。
- [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]Learn Harness Engineering專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
Walking Labs · 公開案例 · 2026-08-26
- [4]Andrej Karpathy 的 AI Engineering PlaybookSoftware 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
AI Builder Club · 公開案例 · 2026-08-26
- [5]Harness Engineering 學習指南repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理
deusyu · 公開案例 · 2026-08-26
延伸的 Tenten 資源