這一課會完成什麼
- 用輸入、產出、責任歸屬、衝突區域與驗收門檻表達可啟動工作圖
- 比較循序/平行的總經過時間、總成本、重疊、串接失敗與審查負擔
- 設計合併/交接契約,避免兩個工作單元擁有同一可變範圍
- 建立指令、自動產生的事實、例外、測試資料、規則與驗收憑證的維護複雜度檢查
開始前先準備
- • 模組 00 到 08 的評測、隔離的 worktrees、台帳、事件與復原控制
- • 兩個獨立保留評測任務加一個刻意重疊的衝突測試資料
先把定義說清楚
工作圖與維護
工作圖由有版本的任務節點組成,每個節點列出依賴證據、負責產出、受保護路徑、可變資源、預算與驗收門檻。上游憑證齊全、環境健康,且責任不與進行中的工作重疊,才可啟動。維護則持續檢查程式庫指引、產生的地圖、測試資料、規則、例外、連結與憑證是否仍符合目前來源。平行的收益要連同整合、審查和復原成本一起比較,共用資源衝突時就回到循序執行。
平行工作階段在任務真的獨立且環境隔離時可以縮短等待,也可能成倍增加模型與工具成本、重複搜尋、爭用測試資料、產出不相容抽象,最後把工作量推給串接。工作單元次數是需評測的營運選擇,不是架構越多就越先進。
Harness 也會跟程式碼一起老化。套件改名後指引還指舊路徑、自動產生的地圖沒更新、例外超期、測試登錄清單漏掉新路由、台帳連到不存在證據。過期 harness 會讓 agent 很有把握地走錯,所以維護本身要有健康狀態指令與預算。
現場情境
兩個工作單元很快,串接卻壞了
任務工作圖、分支、時間差、成本、衝突與健康狀態發現都是合成測試資料。
- 負責人
- 你是判斷 Release Desk 是否能跑兩個同時進行的程式撰寫任務的平台負責人。
- 要做的決策
- 兩個任務能否同時跑,要如何改工作圖才能讓下一次平行試跑有證據?
- 目前狀態
- 任務 A 加請求變更原因,任務 B 加稽核匯出。兩者都修改共用狀態轉移 schema 和初始資料。各分支的局部測試通過,合併後卻因遷移順序錯誤而失敗,並遺失列舉值。
- 預期成果
- 派送執行前抓重疊,共用 schema 成為上游節點,後續獨立 UI/匯出節點才平行,最後比較整合後驗收憑證。
限制條件
- • 每個工作單元有獨立 worktree、環境、連接埠、資料、快取、紀錄、截圖與程序負責人
- • 依賴或衝突未通過不得派送執行
- • 循序與雙工作單元使用等同條件的契約與整合後輸出
實作範例
工作圖移除假的獨立性
證據類型: 具名模擬情境初版按功能名稱分成兩個工作單元,路徑清單卻顯示兩者都改 transition-schema、遷移中繼資料和同一份初始資料。未檢查衝突的試跑雖縮短編寫時間,整合仍須人工修衝突,而且漏跑一個驗收案例。
新版工作圖建 schema-contract 節點,由單一負責人完成,兩個功能節點等驗收憑證通過才可啟動。後續分別擁有 UI 與匯出套件、獨立測試資料命名空間;串接節點重建地圖、跑整合後資料遷移與完整評測。
第二次試跑沒有重疊寫入或遺失測試。合成案例的經過時間縮短,總運算及協調成本仍高於循序。決策只允許經工作圖驗證可獨立執行的節點用兩個工作單元,共用 schema 維持循序。
主張限制
結果依程式庫架構、任務耗時、模型、工具與審查者流程。其他程式庫要先做自己的衝突與成本比較。
做法
照著做,每一步都有檢查點
現場情境
兩個任務能否同時跑,要如何改工作圖才能讓下一次平行試跑有證據?
- 01宣告節點與衝突範圍
- 02跑等同條件的循序/平行
- 03驗分支與整合後正式事實
驗收條件
系統拒絕重疊的平行工作,可啟動工作通過整合後驗收,完整報協調取捨,也會在過期 harness 誤導工作階段前抓出五種偏移。
- 01
宣告節點與衝突範圍
各節點列契約、上游證據、負責及受保護路徑、可變資源、輸出憑證、預算、驗證器與整合者。用靜態分析或產生器找共用 schema、測試資料、遷移與設定。
檢查點 · 原本的兩節點工作圖因重疊被拒;修正版先讓共用 schema 成為已驗證的上游節點。
- 02
跑等同條件的循序/平行
同一最終範圍先循序,再以兩個可啟動工作單元跑。記總經過時間、總模型/工具、重試、重複讀取、路徑、衝突、串接修復、審查時間與關鍵失敗。
檢查點 · 兩次達等同條件的整合後行為;若沒有,就誠實記 no-go,不事後修證據。
- 03
驗分支與整合後正式事實
核對分支憑證、提交版本及環境,合併符合資格的產出,重建索引,再跑遷移、規則、評測、瀏覽器和操作次數檢查。衝突留下具名決策,最後驗整合後的憑證。
檢查點 · 整合後驗收憑證涵蓋每個節點、已變更的路徑、衝突、操作效果、測試資料與驗證層。
- 04
埋入並修正 Harness 維護問題
破壞指令連結、讓例外到期、過期路由地圖、失去對應來源的驗收憑證、移除測試資料目標。跑健康狀態,由負責人修復,記維護時間與觸發條件改動。
檢查點 · 五個偏移測試資料各回不同程式碼,乾淨狀態通過,地圖驗收憑證帶來源提交版本。
實務脈絡
展示版之後
依責任歸屬與證據排程
節點列任務契約、上游驗收憑證、負責及受保護路徑、環境資源、預算、交付檔案、合併條件與驗證器。啟動資格同時檢查上游結果、環境健康、資源歸屬和契約。分工說明須明確,不能把重疊工作描述成獨立任務。
整合時看驗收憑證與 diffs。每個分支單獨驗,整合後狀態再驗。兩個分支對架構或證據有衝突,要保存雙方並進具名決策,不能請模型把衝突揉成聽起來合理的程式碼。
把 harness 維護納入工程成本
健康檢查涵蓋指令連結、地圖時效、來源查閱日期、測試目標、規則一致性、例外期限、台帳證據及缺少來源的檔案。快速檢查隨變更執行,較慢的重新產生程序依排程或相關路徑觸發。
分開記錄功能開發與 Harness 維護成本,包括維護工時、誤判、過期資訊、重新產生的檔案和審查負擔。支援結構長期花費超過收益時,依證據簡化。
交付補強
工作圖除了 glob 重疊,也檢查共用資源。不同路由可能經產生器修改同一登錄清單,兩份資料遷移共用順序,測試命名空間也可能寫同一筆資料。責任清單納入自動產出、schema 資源、設定鍵值、資料表、快取命名空間與測試登錄。無法可靠隔離時,先列為衝突區,交上游契約節點整理,再考慮平行。
協調器自己也要被預算與評測。它產生工作圖、分派任務、追驗收憑證、取消工作單元、處理失敗與整合輸出,都會花模型呼叫與審查者注意力。比較報告將協調器、工作單元、工具、重複讀取、已取消的工作、合併修復與最終驗證分開計費。若兩個工作單元只省等待,卻讓總成本、關鍵風險或審查增幅超出事前門檻,決策可以回到循序,沒有必要替平行找理由。
工作單元契約要提供足夠脈絡又避免擴權。每個工作單元取得節點契約、上游驗收憑證、負責路徑、受保護路徑、環境地圖、工具允許清單、預算、預期交付檔案、終止規則與交接 schema。它不能順手修另一個節點,即使看到明顯問題;應建立發現交給協調器。這保留責任歸屬,也避免一位工作單元的好意在另一分支造成難以追蹤的衝突。
合併不是把差異套上去就結束。先驗分支驗收憑證與提交版本,再檢責任歸屬、例外、資料遷移順序、自動產生的事實、依賴圖與測試資料版本。衝突決策寫已選定的變更、已拒絕的替代方案、負責人、原因與受影響的測試。整合後提交版本從全新環境跑完整驗證;任何分支 pass 不能替代整合驗收憑證,也不能在合併後刪掉失敗案例來維持綠燈。
維護複雜度發現要能定位負責人與修復。失效連結指向哪份指令、過期地圖差哪個來源提交版本、已到期例外曾匹配哪些檔案、失去對應來源的驗收憑證缺哪個功能、缺漏測試資料由哪個測試集使用,都要清楚。健康狀態指令不應只輸出總分,因為平均健康度會掩蓋一條關鍵啟動連結已斷。阻擋執行的與建議項目分開,門檻變更也保留決策紀錄。
排程維護設時間上限與移除條件。完整健康檢查愈來愈慢時,查重複產生器、可增量檢查的連結,以及無人使用的檔案。沒有任務、規則、評測或審查者使用的產物,先標停用、觀察一個週期,再移出清單和指引。縮小程式庫後,仍要通過全新工作階段的理解測試及完整驗收。
平行取消也要有合約。上游節點失敗、預算用盡或操作人員緊急停止時,尚未派送執行的下游節點直接取消;執行中的工作單元停止新工具,保存交接與尚未完成的操作效果,再由協調器依責任歸屬清理。不能因某個分支已花成本就讓它繼續修改失去前提的程式碼。已取消的交付檔案保留供診斷,但不進合併資格;若要重新使用,必須對新上游驗收憑證做明確 rebase 與完整驗證。
整合審查者需要一張涵蓋表。每個節點的 promised 輸出、驗收憑證、已變更的路徑、測試、操作效果與限制逐列核對,缺一項就不生成完成。兩個工作單元對同一必須成立的條件給相反判斷時,保存兩份證據交給負責人,不用語言模型投票。這張表也顯示哪些來源或探索重複,讓下次工作圖可以調整節點邊界,而不是把協調浪費當成無法避免的額外成本。
擴大工作單元數前,先在相同任務工作圖做二到三種設定。從一個工作單元、兩個可啟動工作單元開始,只有總經過時間有明確業務價值、關鍵失敗不增加、總成本與審查在上限內、復原演練仍通過,才考慮下一級。工作單元上限寫進規則與預算,不由協調器自由決定。遇到共用 schema 或高衝突工作,自動降級到循序是正常控制,不是系統失敗。
工作圖也要支援人工決策節點。當兩個方案牽涉領域取捨、資料遷移不可逆或權限範圍改變時,節點的輸出是決策資料包,不是直接修改來源。資料包列替代方案、證據、受影響的節點、回復版本與期限,由具名負責人選定後產生已簽核的驗收憑證,下游節點才可啟動。若到期沒有決定,工作圖進 blocked,不讓協調器以預設選項繼續。這種節點讓工作圖同時表達技術依賴與權限來源依賴,避免平行工作單元各自猜一個方向。
維護複雜度審查要回看 agent 實際使用哪些交付檔案。執行軌跡顯示某份指引從未被讀取,可能是導航失效,也可能是檔案已無價值;某張地圖每次都被讀卻經常導致人工修正,表示內容可信度不足。將讀取、發現、修正、生成成本與負責人回饋放在一起,再決定改善或移除。不能只用檔案最後修改日期判時效,因為一份昨天更新但來源錯誤的地圖,比半年未變且仍對應穩定必須成立的條件更危險。
工作圖版本要和每個驗收憑證綁定。協調器若在執行中新增依賴、改責任歸屬或放寬預算,進行中的節點不會自動採新設定;先停止受影響工作,保存交接,再由負責人決定取消或以新工作圖重新啟動。這能避免某個工作單元按舊邊界修改,另一個已按新邊界接管相同資源。工作圖差異列新增與移除節點、依賴、路徑、資源、工具、預算與審查者,並重跑重疊測試資料。只有文字說明變更、不影響執行邊界時,才允許不重啟。
維護修復也限制修改範圍。產生器可重建地圖或索引;刪除不明檔案、改負責人、更新例外或重寫指引,須有明確規則或人工審查。健康檢查預設唯讀,先列修復計畫;實際修改用精確目標、Git 差異和可回復版本。超過維護預算就拆成有負責人的任務。修復後再驗導覽與連結,確認程式庫較容易理解。
動手實作
執行雙工作單元工作圖與維護複雜度稽核
建立三個節點,拒預先設計的重疊,將共用 schema 拆上游,跑隔離的分支與串接,再故意讓 harness 交付檔案老化並抓出。
準備項目
- • 為循序與平行試跑建立明確 worktree/環境,不碰其他本機專案
- • 凍結契約、整合後行為、關鍵驗收門檻、成本欄位、重疊規則與健康狀態清單
本課產出
已驗證的工作圖、責任歸屬報告、循序/平行驗收憑證、隔離證據、串接證據、決策備忘錄、健康狀態清單、偏移測試資料與維護預算。
起始模板: 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預期結果
系統拒絕重疊的平行工作,可啟動工作通過整合後驗收,完整報協調取捨,也會在過期 harness 誤導工作階段前抓出五種偏移。
留給下一課
把工作圖、比較報告與健康清單帶入總整專案。擴大協作規模前先量測整合後收益,並保留退回較簡單執行方式的方案。
驗收條件
- 01工作圖驗證在派送執行前擋進行中的路徑、資料遷移、測試資料、設定或可變資源重疊
- 02比較包等同條件的範圍、總成本、審查、衝突、關鍵與整合後證據
- 03每個工作單元的網路、資料、快取、紀錄、截圖、程序、測試資料與清理隔離
- 04健康狀態抓失效指引、已到期例外、過期地圖、失去對應來源的驗收憑證與缺漏測試資料
常見故障
故障診間
F1兩個分支單獨 pass,合併後少一個案例。
- 先檢查
- 看負責路徑、共用測試資料、資料遷移順序、自動產生的地圖、測試登錄清單與整合驗收憑證。
- 可能原因
- 功能標記被當成獨立性,沒有整合後驗證。
- 修復方式
- 恢復遺失案例、建立上游 shared-contract 節點、重跑分支/串接。
- 下次怎麼避免
- 派送執行前驗路徑/資源衝突,並要求串接節點。
F2平行總經過時間變短,審查與總成本卻翻倍。
- 先檢查
- 拆協調器、工作單元、工具、重試、重複來源、衝突修復與審查。
- 可能原因
- 決策只看程式撰寫經過,漏掉協調與證據。
- 修復方式
- 重算完整比較,降低工作單元或將依賴前一步的任務改回循序。
- 下次怎麼避免
- 每次擴大協作實驗前,先定效益、品質、成本、審查負擔與關鍵門檻。
F3地圖很有自信地指向已刪除路由。
- 先檢查
- 查產生器版本、來源提交版本、路徑觸發條件與健康狀態驗收憑證。
- 可能原因
- 自動產生的知識沒有時效要求,或過期時不會阻擋執行。
- 修復方式
- 依目前提交版本重建地圖,修正更新條件,加入過期案例。
- 下次怎麼避免
- 相關路徑變更必須通過時效驗證。
展示版之後
正式上線前的邊界
- 01節點宣告依賴、輸入、負責產出、衝突、資源、預算、驗證器與整合者
- 02啟動前擋住未解依賴、資源重疊、環境異常、契約過期與缺少憑證
- 03工作單元隔離網路、資料、快取、紀錄、截圖、程序、測試資料與清理
- 04平行決策比等同條件的整合後品質、關鍵、總經過時間、總計成本、審查與復原
- 05串接驗分支驗收憑證、衝突、自動產生的事實、資料遷移、規則、評測、瀏覽器與操作效果
- 06健康檢查涵蓋指引、地圖、來源、測試資料、規則、例外、台帳、憑證及缺少來源的檔案
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。
- [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 資源