跳至主要內容

parallel coding agents work graph repository entropy

專案

先畫工作依賴,再安排平行協作與維護

在啟動多個工作單元前先定依賴、責任歸屬與衝突區域,量完整協調成本,並持續抓過期指引、地圖、測試資料與例外。

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

這一課會完成什麼

  • 用輸入、產出、責任歸屬、衝突區域與驗收門檻表達可啟動工作圖
  • 比較循序/平行的總經過時間、總成本、重疊、串接失敗與審查負擔
  • 設計合併/交接契約,避免兩個工作單元擁有同一可變範圍
  • 建立指令、自動產生的事實、例外、測試資料、規則與驗收憑證的維護複雜度檢查

開始前先準備

  • • 模組 00 到 08 的評測、隔離的 worktrees、台帳、事件與復原控制
  • • 兩個獨立保留評測任務加一個刻意重疊的衝突測試資料

先把定義說清楚

工作圖與維護

工作圖由有版本的任務節點組成,每個節點列出依賴證據、負責產出、受保護路徑、可變資源、預算與驗收門檻。上游憑證齊全、環境健康,且責任不與進行中的工作重疊,才可啟動。維護則持續檢查程式庫指引、產生的地圖、測試資料、規則、例外、連結與憑證是否仍符合目前來源。平行的收益要連同整合、審查和復原成本一起比較,共用資源衝突時就回到循序執行。

平行工作階段在任務真的獨立且環境隔離時可以縮短等待,也可能成倍增加模型與工具成本、重複搜尋、爭用測試資料、產出不相容抽象,最後把工作量推給串接。工作單元次數是需評測的營運選擇,不是架構越多就越先進。

Harness 也會跟程式碼一起老化。套件改名後指引還指舊路徑、自動產生的地圖沒更新、例外超期、測試登錄清單漏掉新路由、台帳連到不存在證據。過期 harness 會讓 agent 很有把握地走錯,所以維護本身要有健康狀態指令與預算。

現場情境

兩個工作單元很快,串接卻壞了

任務工作圖、分支、時間差、成本、衝突與健康狀態發現都是合成測試資料。

負責人
你是判斷 Release Desk 是否能跑兩個同時進行的程式撰寫任務的平台負責人。
要做的決策
兩個任務能否同時跑,要如何改工作圖才能讓下一次平行試跑有證據?
目前狀態
任務 A 加請求變更原因,任務 B 加稽核匯出。兩者都修改共用狀態轉移 schema 和初始資料。各分支的局部測試通過,合併後卻因遷移順序錯誤而失敗,並遺失列舉值。
預期成果
派送執行前抓重疊,共用 schema 成為上游節點,後續獨立 UI/匯出節點才平行,最後比較整合後驗收憑證。

限制條件

  • • 每個工作單元有獨立 worktree、環境、連接埠、資料、快取、紀錄、截圖與程序負責人
  • • 依賴或衝突未通過不得派送執行
  • • 循序與雙工作單元使用等同條件的契約與整合後輸出

實作範例

工作圖移除假的獨立性

證據類型: 具名模擬情境

初版按功能名稱分成兩個工作單元,路徑清單卻顯示兩者都改 transition-schema、遷移中繼資料和同一份初始資料。未檢查衝突的試跑雖縮短編寫時間,整合仍須人工修衝突,而且漏跑一個驗收案例。

新版工作圖建 schema-contract 節點,由單一負責人完成,兩個功能節點等驗收憑證通過才可啟動。後續分別擁有 UI 與匯出套件、獨立測試資料命名空間;串接節點重建地圖、跑整合後資料遷移與完整評測。

第二次試跑沒有重疊寫入或遺失測試。合成案例的經過時間縮短,總運算及協調成本仍高於循序。決策只允許經工作圖驗證可獨立執行的節點用兩個工作單元,共用 schema 維持循序。

主張限制

結果依程式庫架構、任務耗時、模型、工具與審查者流程。其他程式庫要先做自己的衝突與成本比較。

做法

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

Release Desk 工作圖有上游 schema 節點、兩個隔離的工作單元、串接驗證器、成本比較與維護複雜度健康狀態迴圈。

現場情境

兩個任務能否同時跑,要如何改工作圖才能讓下一次平行試跑有證據?

  1. 01宣告節點與衝突範圍
  2. 02跑等同條件的循序/平行
  3. 03驗分支與整合後正式事實

驗收條件

系統拒絕重疊的平行工作,可啟動工作通過整合後驗收,完整報協調取捨,也會在過期 harness 誤導工作階段前抓出五種偏移。

這張圖要幫你看懂什麼依賴圖配責任歸屬與衝突區域,能看出平行資格與整合後驗證位置。
  1. 01

    宣告節點與衝突範圍

    各節點列契約、上游證據、負責及受保護路徑、可變資源、輸出憑證、預算、驗證器與整合者。用靜態分析或產生器找共用 schema、測試資料、遷移與設定。

    檢查點 · 原本的兩節點工作圖因重疊被拒;修正版先讓共用 schema 成為已驗證的上游節點。

  2. 02

    跑等同條件的循序/平行

    同一最終範圍先循序,再以兩個可啟動工作單元跑。記總經過時間、總模型/工具、重試、重複讀取、路徑、衝突、串接修復、審查時間與關鍵失敗。

    檢查點 · 兩次達等同條件的整合後行為;若沒有,就誠實記 no-go,不事後修證據。

  3. 03

    驗分支與整合後正式事實

    核對分支憑證、提交版本及環境,合併符合資格的產出,重建索引,再跑遷移、規則、評測、瀏覽器和操作次數檢查。衝突留下具名決策,最後驗整合後的憑證。

    檢查點 · 整合後驗收憑證涵蓋每個節點、已變更的路徑、衝突、操作效果、測試資料與驗證層。

  4. 04

    埋入並修正 Harness 維護問題

    破壞指令連結、讓例外到期、過期路由地圖、失去對應來源的驗收憑證、移除測試資料目標。跑健康狀態,由負責人修復,記維護時間與觸發條件改動。

    檢查點 · 五個偏移測試資料各回不同程式碼,乾淨狀態通過,地圖驗收憑證帶來源提交版本。

實務脈絡

展示版之後

G1

依責任歸屬與證據排程

節點列任務契約、上游驗收憑證、負責及受保護路徑、環境資源、預算、交付檔案、合併條件與驗證器。啟動資格同時檢查上游結果、環境健康、資源歸屬和契約。分工說明須明確,不能把重疊工作描述成獨立任務。

整合時看驗收憑證與 diffs。每個分支單獨驗,整合後狀態再驗。兩個分支對架構或證據有衝突,要保存雙方並進具名決策,不能請模型把衝突揉成聽起來合理的程式碼。

G2

把 harness 維護納入工程成本

健康檢查涵蓋指令連結、地圖時效、來源查閱日期、測試目標、規則一致性、例外期限、台帳證據及缺少來源的檔案。快速檢查隨變更執行,較慢的重新產生程序依排程或相關路徑觸發。

分開記錄功能開發與 Harness 維護成本,包括維護工時、誤判、過期資訊、重新產生的檔案和審查負擔。支援結構長期花費超過收益時,依證據簡化。

G3

交付補強

工作圖除了 glob 重疊,也檢查共用資源。不同路由可能經產生器修改同一登錄清單,兩份資料遷移共用順序,測試命名空間也可能寫同一筆資料。責任清單納入自動產出、schema 資源、設定鍵值、資料表、快取命名空間與測試登錄。無法可靠隔離時,先列為衝突區,交上游契約節點整理,再考慮平行。

協調器自己也要被預算與評測。它產生工作圖、分派任務、追驗收憑證、取消工作單元、處理失敗與整合輸出,都會花模型呼叫與審查者注意力。比較報告將協調器、工作單元、工具、重複讀取、已取消的工作、合併修復與最終驗證分開計費。若兩個工作單元只省等待,卻讓總成本、關鍵風險或審查增幅超出事前門檻,決策可以回到循序,沒有必要替平行找理由。

工作單元契約要提供足夠脈絡又避免擴權。每個工作單元取得節點契約、上游驗收憑證、負責路徑、受保護路徑、環境地圖、工具允許清單、預算、預期交付檔案、終止規則與交接 schema。它不能順手修另一個節點,即使看到明顯問題;應建立發現交給協調器。這保留責任歸屬,也避免一位工作單元的好意在另一分支造成難以追蹤的衝突。

合併不是把差異套上去就結束。先驗分支驗收憑證與提交版本,再檢責任歸屬、例外、資料遷移順序、自動產生的事實、依賴圖與測試資料版本。衝突決策寫已選定的變更、已拒絕的替代方案、負責人、原因與受影響的測試。整合後提交版本從全新環境跑完整驗證;任何分支 pass 不能替代整合驗收憑證,也不能在合併後刪掉失敗案例來維持綠燈。

維護複雜度發現要能定位負責人與修復。失效連結指向哪份指令、過期地圖差哪個來源提交版本、已到期例外曾匹配哪些檔案、失去對應來源的驗收憑證缺哪個功能、缺漏測試資料由哪個測試集使用,都要清楚。健康狀態指令不應只輸出總分,因為平均健康度會掩蓋一條關鍵啟動連結已斷。阻擋執行的與建議項目分開,門檻變更也保留決策紀錄。

排程維護設時間上限與移除條件。完整健康檢查愈來愈慢時,查重複產生器、可增量檢查的連結,以及無人使用的檔案。沒有任務、規則、評測或審查者使用的產物,先標停用、觀察一個週期,再移出清單和指引。縮小程式庫後,仍要通過全新工作階段的理解測試及完整驗收。

平行取消也要有合約。上游節點失敗、預算用盡或操作人員緊急停止時,尚未派送執行的下游節點直接取消;執行中的工作單元停止新工具,保存交接與尚未完成的操作效果,再由協調器依責任歸屬清理。不能因某個分支已花成本就讓它繼續修改失去前提的程式碼。已取消的交付檔案保留供診斷,但不進合併資格;若要重新使用,必須對新上游驗收憑證做明確 rebase 與完整驗證。

整合審查者需要一張涵蓋表。每個節點的 promised 輸出、驗收憑證、已變更的路徑、測試、操作效果與限制逐列核對,缺一項就不生成完成。兩個工作單元對同一必須成立的條件給相反判斷時,保存兩份證據交給負責人,不用語言模型投票。這張表也顯示哪些來源或探索重複,讓下次工作圖可以調整節點邊界,而不是把協調浪費當成無法避免的額外成本。

擴大工作單元數前,先在相同任務工作圖做二到三種設定。從一個工作單元、兩個可啟動工作單元開始,只有總經過時間有明確業務價值、關鍵失敗不增加、總成本與審查在上限內、復原演練仍通過,才考慮下一級。工作單元上限寫進規則與預算,不由協調器自由決定。遇到共用 schema 或高衝突工作,自動降級到循序是正常控制,不是系統失敗。

工作圖也要支援人工決策節點。當兩個方案牽涉領域取捨、資料遷移不可逆或權限範圍改變時,節點的輸出是決策資料包,不是直接修改來源。資料包列替代方案、證據、受影響的節點、回復版本與期限,由具名負責人選定後產生已簽核的驗收憑證,下游節點才可啟動。若到期沒有決定,工作圖進 blocked,不讓協調器以預設選項繼續。這種節點讓工作圖同時表達技術依賴與權限來源依賴,避免平行工作單元各自猜一個方向。

維護複雜度審查要回看 agent 實際使用哪些交付檔案。執行軌跡顯示某份指引從未被讀取,可能是導航失效,也可能是檔案已無價值;某張地圖每次都被讀卻經常導致人工修正,表示內容可信度不足。將讀取、發現、修正、生成成本與負責人回饋放在一起,再決定改善或移除。不能只用檔案最後修改日期判時效,因為一份昨天更新但來源錯誤的地圖,比半年未變且仍對應穩定必須成立的條件更危險。

工作圖版本要和每個驗收憑證綁定。協調器若在執行中新增依賴、改責任歸屬或放寬預算,進行中的節點不會自動採新設定;先停止受影響工作,保存交接,再由負責人決定取消或以新工作圖重新啟動。這能避免某個工作單元按舊邊界修改,另一個已按新邊界接管相同資源。工作圖差異列新增與移除節點、依賴、路徑、資源、工具、預算與審查者,並重跑重疊測試資料。只有文字說明變更、不影響執行邊界時,才允許不重啟。

維護修復也限制修改範圍。產生器可重建地圖或索引;刪除不明檔案、改負責人、更新例外或重寫指引,須有明確規則或人工審查。健康檢查預設唯讀,先列修復計畫;實際修改用精確目標、Git 差異和可回復版本。超過維護預算就拆成有負責人的任務。修復後再驗導覽與連結,確認程式庫較容易理解。

動手實作

執行雙工作單元工作圖與維護複雜度稽核

建立三個節點,拒預先設計的重疊,將共用 schema 拆上游,跑隔離的分支與串接,再故意讓 harness 交付檔案老化並抓出。

準備項目

  • • 為循序與平行試跑建立明確 worktree/環境,不碰其他本機專案
  • • 凍結契約、整合後行為、關鍵驗收門檻、成本欄位、重疊規則與健康狀態清單

本課產出

已驗證的工作圖、責任歸屬報告、循序/平行驗收憑證、隔離證據、串接證據、決策備忘錄、健康狀態清單、偏移測試資料與維護預算。

起始模板: Work graph manifest

YAML
nodes:
  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 誤導工作階段前抓出五種偏移。

留給下一課

把工作圖、比較報告與健康清單帶入總整專案。擴大協作規模前先量測整合後收益,並保留退回較簡單執行方式的方案。

驗收條件

  1. 01工作圖驗證在派送執行前擋進行中的路徑、資料遷移、測試資料、設定或可變資源重疊
  2. 02比較包等同條件的範圍、總成本、審查、衝突、關鍵與整合後證據
  3. 03每個工作單元的網路、資料、快取、紀錄、截圖、程序、測試資料與清理隔離
  4. 04健康狀態抓失效指引、已到期例外、過期地圖、失去對應來源的驗收憑證與缺漏測試資料

常見故障

故障診間

F1兩個分支單獨 pass,合併後少一個案例。
先檢查
看負責路徑、共用測試資料、資料遷移順序、自動產生的地圖、測試登錄清單與整合驗收憑證。
可能原因
功能標記被當成獨立性,沒有整合後驗證。
修復方式
恢復遺失案例、建立上游 shared-contract 節點、重跑分支/串接。
下次怎麼避免
派送執行前驗路徑/資源衝突,並要求串接節點。
F2平行總經過時間變短,審查與總成本卻翻倍。
先檢查
拆協調器、工作單元、工具、重試、重複來源、衝突修復與審查。
可能原因
決策只看程式撰寫經過,漏掉協調與證據。
修復方式
重算完整比較,降低工作單元或將依賴前一步的任務改回循序。
下次怎麼避免
每次擴大協作實驗前,先定效益、品質、成本、審查負擔與關鍵門檻。
F3地圖很有自信地指向已刪除路由。
先檢查
查產生器版本、來源提交版本、路徑觸發條件與健康狀態驗收憑證。
可能原因
自動產生的知識沒有時效要求,或過期時不會阻擋執行。
修復方式
依目前提交版本重建地圖,修正更新條件,加入過期案例。
下次怎麼避免
相關路徑變更必須通過時效驗證。

展示版之後

正式上線前的邊界

  1. 01節點宣告依賴、輸入、負責產出、衝突、資源、預算、驗證器與整合者
  2. 02啟動前擋住未解依賴、資源重疊、環境異常、契約過期與缺少憑證
  3. 03工作單元隔離網路、資料、快取、紀錄、截圖、程序、測試資料與清理
  4. 04平行決策比等同條件的整合後品質、關鍵、總經過時間、總計成本、審查與復原
  5. 05串接驗分支驗收憑證、衝突、自動產生的事實、資料遷移、規則、評測、瀏覽器與操作效果
  6. 06健康檢查涵蓋指引、地圖、來源、測試資料、規則、例外、台帳、憑證及缺少來源的檔案

證據類型

資料來源與主張限制

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

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

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

    initializer 模式 · feature ledger · session 交接 · 端到端驗證
  3. [3]
    Learn Harness Engineering

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

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

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

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

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

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

延伸的 Tenten 資源

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

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

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