這一課會完成什麼
- 分清可持久保存的任務狀態、對話脈絡、摘要與一般進度筆記
- 用證據保護待處理、進行中的、blocked、implemented、verified 的轉換
- 讓啟動與關閉同步檢查契約、Git、環境與台帳
- 在脈絡重設或程序崩潰後接續未完成工作，不重複效果也不偷開新功能
開始前先準備
- • 模組 01 到 03 的合約、程式庫地圖與健康環境驗收憑證
- • 一個只含課程測試資料的 Git 分支，可在實作中刻意中斷工作階段
先把定義說清楚
工作狀態與交接
可持久保存的工作狀態，是能跨越脈絡重設、程序失敗與人員交接的版本化紀錄。它保存任務範圍、目前狀態、提交版本、證據、阻礙、決策與唯一下一步。摘要幫助接手者快速理解，完成與否仍要核對證據。每次狀態轉移都符合 schema 與驗收門檻，並和 Git、環境健康、契約版本及操作台帳一致。恢復工作前重新檢查這些條件，才不會沿用已失效的判斷。
長時間程式撰寫任務會跨脈絡時段、工作日與不同審查者。若進度只在聊天裡，新工作階段會重新搜尋、重做設定、把半成品當成已完成，或因摘要寫著『差不多好了』便開下一個功能。脈絡壓縮可以節省 token，卻可能省略正卡住的重試案例。
功能台帳和固定交接流程能減少重建脈絡的成本。開始時先驗環境、讀 Git、載入契約與進行中的項目；結束時跑檢查，留下可理解的提交或明確未完成狀態，附上證據及一項下一步。接手者因此可以核對紀錄，不必仰賴前一人的記憶。
現場情境
功能做到一半時脈絡重設
工作階段重設、台帳、分支與結果都是確定性的 Release Desk 測試資料。
- 負責人
- 你是接手請求變更持久保存的第二個 coding-agent 工作階段。
- 要做的決策
- 目前正式可信的狀態是什麼，新工作階段唯一安全的下一步是哪一項？
- 目前狀態
- API 分支已存在且單元測試通過；瀏覽器持久化檢查未跑，分支有一筆未提交的資料遷移。摘要只寫『大致完成』，沒有提到寫入結果未知時的重試問題。
- 預期成果
- 新工作階段判斷持久保存與重試尚未完成，整理分支後繼續缺少的案例，沒有重複稽核操作效果。
限制條件
- • 新工作階段只能讀程式庫與 Git，不能取得舊對話紀錄或私人口述
- • 未對齊健康狀態、台帳、分支與未完成驗收前，不得開始新功能
- • Verified 必須由契約的完整處理流程與驗收憑證建立
實作範例
摘要寫 done，台帳只到 implemented
證據類型: 具名模擬情境第一個工作階段的摘要強調 API 完成與單元測試綠燈。功能台帳保持 implemented，因為重新整理與逾時重試尚未執行；Git 另有一筆摘要沒提到的資料遷移差異。
接手流程先核對台帳與 Git。新工作階段驗環境、保存資料遷移，把差異連到進行中的功能，再跑缺少的測試案例，發現寫入結果未知後重試會重複寫入稽核。
修復後，交接附最終提交版本、完整驗收憑證、已知限制與下一項獨立任務。第三個全新工作階段不用打開舊聊天，也能說清功能狀態、證據與復原過程；開始下一項工作前，仍重新核對環境和契約版本，避免沿用過期證據。
主張限制
課程以檔案保存狀態。分散式正式系統可能需要交易一致性、租約、事件紀錄與並行控制，必須依目標系統設計，不能直接套用教材門檻。
做法
照著做，每一步都有檢查點
現場情境
目前正式可信的狀態是什麼，新工作階段唯一安全的下一步是哪一項？
- 01定義受保護的狀態轉移
- 02用固定儀式開始工作
- 03在已知檢查點中斷
驗收條件
沒有舊對話紀錄的工作階段能重建目前工作、保存半成品、完成正確案例，並留下下一位可稽核的證據。
- 01
定義受保護的狀態轉移
建立待處理、進行中的、blocked、implemented、verified，為每條轉換列契約版本、分支條件、檢查證據、執行者與原因。Schema 要拒 verified 缺證據與所有未知轉換。
檢查點 · 直接從待處理到 verified、缺提交版本或少任一關鍵驗收憑證都會 fail。
- 02
用固定儀式開始工作
執行初始化程序，讀 Git 歷史，載入目前契約和台帳，核對已提交及未提交變更，再選可啟動項目。保存工作階段 ID、起始提交版本與環境證據。
檢查點 · 進行中的項目、提交版本、健康狀態驗收憑證、預算與預計下一個狀態轉移一致。
- 03
在已知檢查點中斷
完成部分實作後停止，保留已提交或未提交狀態。記錄通過及失敗的檢查、正在修改的檔案、決策、阻礙和唯一下一步；未完成驗收時不能標 verified。
檢查點 · 交接能解釋未完成工作，不依賴舊聊天，也沒有隱藏分支狀態。
- 04
全新恢復並核對實際結果
新工作階段按固定啟動流程核對已存狀態，完成缺少的驗收，只經合法狀態轉移更新台帳，最後留下可接手的提交與驗收憑證。
檢查點 · 全新工作階段選對下一步、沒有重複已完成效果，並由具名證據到 verified。
實務脈絡
展示版之後
讓 verified 成為受保護狀態
已實作代表已有對應提交版本，verified 則要通過契約指定的完整處理流程。狀態轉換保存起點、終點、執行者、原因、時間戳記、契約、提交版本與證據 IDs；不允許待處理直接跳 verified，也不允許 agent 自己引用一句完成宣告當證據。
Blocked 要說明缺少哪個權限來源或外部條件、誰能解、已嘗試什麼、最後健康檢查點、目前分支狀態，以及等待期間還有哪些工作安全。它不是把不確定工作丟進角落的標籤。
交接先對齊程式庫正式事實
啟動要比較台帳、Git 狀態、最近提交版本、環境驗收憑證與操作台帳。台帳若寫 verified 但提交版本不存在，或分支有未記錄資料遷移，就先核對實際結果，不能開新任務。關閉則留下乾淨提交版本，或將有未提交變更的差異、失敗的檢查與下一步寫清楚。
進度紀錄不需要保存完整對話。留下目前決策、狀態變更、證據、失敗、阻礙與下一個操作即可。被推翻的假設可放決策歷史紀錄，但不應混進目前狀態，讓新工作階段誤以為仍有效。
交付補強
工作台帳分開保存觀察與已驗證事實。Agent 可以記下『懷疑 retry 會重複 audit』，實際操作次數則由驗證器或正式台帳寫入。混成一段文字，接手者容易把假設當結論，或忽略失敗證據。每個證據 ID 對應特定執行、提交版本、環境與契約；可被覆寫的 latest 截圖，無法單獨支持 verified 狀態。
Blocked 狀態也需要健康檢查。等待產品負責人時，核准期限可能過期、分支可能被合併、測試資料可能升版。恢復不能直接把舊阻礙清掉；要重新讀外部條件，確認執行者仍有權、契約未改、工作中提交版本可重放，再產生新的狀態轉移事件。等待期間若有不相依工作可做，台帳應列可啟動條件，不讓 agent 自行判斷哪個相鄰任務可以順手開始。
交接資料包應讓接手者在短時間內回答六件事：正在做哪一份契約、目前哪個狀態、哪個提交版本或有未提交變更的差異、哪些檢查已跑且綁哪個版本、最後一個失敗與證據、唯一安全下一個操作。若資料包還要讀完整對話才能回答，表示欄位不足；若資料包充滿每輪嘗試細節，表示目前正式事實被歷史紀錄淹沒。兩者都用全新恢復時間與錯誤假設來調整。
程序崩潰與正常關閉要走同一個一致性檢查，只是程序崩潰允許未完成驗收憑證。程序收到中斷時先停止新派送執行，保存尚未完成的租約、預算預留額度、已知操作效果、open 檔案與上一個檢查點；若無法完成提交版本，就將有未提交變更的目錄樹雜湊和復原指令寫入台帳。下一個工作階段先核對實際結果，不要為了追求乾淨 Git 而把未知差異丟掉或重設。
狀態紀錄也要處理多人同時寫入。每次更新帶前一版序號，儲存時採條件式寫入；版本不符就重新讀取，不覆蓋另一個工作階段的阻礙或證據。若任務已由別人移到 verified，舊工作階段不能再送出 completed 事件；它只能保存自己的過期結果並結束。這項檢查能防止兩個背景工作各自相信手上的快照，最後讓較晚寫入的人把較新的證據洗掉。
交接驗收應包含反例。把台帳中一個提交版本改成不存在、將分支留下未記錄檔案、移除一筆必要驗收憑證、讓環境身分指向另一個 worktree，再看新工作階段是否在啟動驗收門檻停下。只有正常交接成功，無法證明系統會對不一致誠實。每個反例要回不同診斷與修復責任，不能用一個『狀態有問題』要求 agent 自由猜測。
完成交接後，讓接手者用自己的話指出目前證據與限制，再由程式核對他引用的識別碼。若說法正確但引用不存在，仍不可進入下一個狀態；若引用完整但接手者誤解阻礙，也要保留為交接品質問題。
動手實作
中斷工作階段，再從程式庫狀態恢復
建立功能台帳與交接資料，在第三個檢查點中斷，再開沒有舊對話的新工作階段。量測理解現況所需時間、錯誤假設、重工與證據復原。
準備項目
- • 先提交初始化程序與任務契約，確認基準環境健康
- • 準備另一個全新工作階段，只提供程式庫路徑與標準啟動指令
本課產出
機器可讀的功能台帳、簡短進度紀錄、交接資料、中斷執行的證據，以及全新工作階段的恢復驗收憑證。
起始模板: Feature ledger
JSON{
"contractVersion": "1.0.0",
"features": [{
"id": "RD-REQUEST-CHANGES",
"status": "pending",
"eligibleNext": true,
"commit": null,
"evidence": [],
"blocker": null,
"nextAction": "implement authorized transition"
}]
}可下載的實作檔
Feature ledger
feature-list.json · JSON
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-04-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:handoff -- --ledger .harness/feature-list.json --fresh-session預期 receipt
PASS he-04 fresh-session-handoff
transcriptShared=false repeatedEffects=0
state=verified git=clean evidence=complete預期結果
沒有舊對話紀錄的工作階段能重建目前工作、保存半成品、完成正確案例，並留下下一位可稽核的證據。
留給下一課
功能台帳會成為工具回饋、由程式強制執行的規則、驗證、復原與工作圖的狀態輸入。後續每個狀態轉移都要連契約與證據 ID。
驗收條件
- 01狀態轉移明確，缺完整證據不能到 verified
- 02啟動對齊契約、台帳、Git、分支、環境與優先順序
- 03中斷紀錄寫明進度、失敗、阻礙負責人與唯一安全下一步
- 04全新恢復不重複操作效果，最終交接綁提交版本與驗收憑證
常見故障
故障診間
F1新工作階段在有未提交變更的分支上開始另一個功能。
- 先檢查
- 比較 Git 狀態、近期提交版本、健康狀態、台帳與 eligible-next 計算。
- 可能原因
- 啟動信任摘要或優先順序清單，沒有對齊程式庫狀態。
- 修復方式
- 停止新工作，保存差異並連回進行中的項目，再恢復健康檢查點。
- 下次怎麼避免
- 將 Git、健康狀態與台帳結果核對設為啟動驗收門檻。
F2只通過單元測試，就把功能改成 verified。
- 先檢查
- 檢查狀態轉移證據要求與驗收憑證 ID。
- 可能原因
- 已實作與 verified 合併成由 agent 自信決定的狀態。
- 修復方式
- 退回 implemented，跑缺少處理流程，由驗證器建立 verified。
- 下次怎麼避免
- Schema 與 CI 一起執行狀態轉移防護。
F3進度檔案變成很長的對話，新工作階段反而看不懂。
- 先檢查
- 分開查看目前決策、狀態、證據、阻礙、下一步與原始對話。
- 可能原因
- 保存聊天量，而不是當前任務正式事實。
- 修復方式
- 依操作 schema 重寫交接，只留避免重犯所需的歷史。
- 下次怎麼避免
- 限制交接欄位，額外文字敘述另行歸檔。
展示版之後
正式上線前的邊界
- 01任務狀態能跨脈絡重設保存；完成事實以契約、台帳與證據核對
- 02待處理、進行中的、blocked、implemented、verified 有合法受保護的狀態轉移
- 03狀態變更記執行者、原因、契約、提交版本、時間戳記與證據 IDs
- 04啟動對齊 Git、健康狀態、分支、優先順序、租約與操作台帳
- 05Blocked 狀態指出缺少條件、負責人、上一個檢查點與安全等待工作
- 06關閉留下乾淨提交版本或另一工作階段可復原的明確未完成狀態
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [1]長時間執行 agent 的有效 harnessinitializer 模式 · feature ledger · session 交接 · 端到端驗證
Anthropic · 已發表研究 · 2026-08-26
- [2]Harness engineering：在 agent-first 開發環境中運用 Codex知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
OpenAI · 公開案例 · 2026-08-26
- [3]Learn Harness Engineering專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
Walking Labs · 公開案例 · 2026-08-26
- [4]Harness Engineering Guide執行環境邊界 · 工具系統 · sandbox · 復原模式
Nexu · 公開案例 · 2026-08-26
- [5]Harness Engineering 學習指南repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理
deusyu · 公開案例 · 2026-08-26
延伸的 Tenten 資源