把工作狀態留在 repository：全新 context 也接得回來：實作與驗收指南

本課內容

01先把定義說清楚
02現場情境
03實作範例
04照著做，每一步都有檢查點
05實務脈絡
06動手實作
07故障診間
08正式上線前的邊界
09資料來源與主張限制

這一課會完成什麼

分清 durable task state、conversation context、摘要與一般進度筆記
用證據保護 pending、in-progress、blocked、implemented、verified 的轉換
讓 startup 與 shutdown 同步檢查 contract、Git、環境與 ledger
在 context reset 或 crash 後接續未完成工作，不重複效果也不偷開新功能

開始前先準備

• 模組 01 到 03 的合約、repository map 與健康 environment receipt
• 一個只含課程 fixture 的 Git branch，可在 lab 中刻意中斷 session

先把定義說清楚

持久狀態與交接

Durable work state 是能跨過 context reset、程序失敗與人員交接的版本化工作紀錄。它保存 task scope、目前狀態、commit、證據、blocker、決策與唯一下一步。聊天摘要有助於快速理解，卻不能建立完成事實。每次 state transition 都要符合 schema 與 gate，並和 Git、環境 health、contract version 及 effect ledger 一致。

長時間 coding task 會跨 context window、工作日與不同 reviewer。若進度只在聊天裡，新 session 會重新搜尋、重做 setup、把半成品當成已完成，或因摘要寫著『差不多好了』便開下一個功能。Compaction 可以節省 token，卻可能省略正卡住的 retry case。

Feature ledger 與固定交接儀式能降低重建成本。Session 開始時先驗環境、讀 Git、載入 contract 與 active item；結束時跑檢查、留下 coherent commit 或明確 incomplete state、連證據並指向一個 next action。工作真相因此不依賴某個人還記得什麼。

現場情境

功能做到一半時 context reset

Session reset、ledger、branch 與結果均為 deterministic Release Desk fixture。

負責人: 你是接手 request-change persistence 的第二個 coding-agent session。
要做的決策: 目前 authoritative state 是什麼，新 session 唯一安全的下一步是哪一項？
目前狀態: API 分支已存在且 unit test 通過；browser persistence 未跑，branch 有一筆未 commit migration，摘要只寫『大致完成』，沒有提到 unknown outcome retry。
預期成果: 新 session 判斷 persistence 與 retry 尚未完成，整理 branch 後繼續缺少的 case，沒有重複 audit effect。

限制條件

• 新 session 只能讀 repository 與 Git，不能取得舊 transcript 或私人口述
• 未對齊 health、ledger、branch 與未完成驗收前，不得開始新 feature
• Verified 必須由 contract 的完整 pipeline 與 receipt 建立

實作範例

摘要寫 done，ledger 只到 implemented

證據類型: 具名模擬情境

第一個 session 的摘要強調 API 完成與 unit test 綠燈。Feature ledger 保持 implemented，因為 refresh 與 timeout retry 尚未執行；Git 另有一筆摘要沒提到的 migration diff。

Takeover ritual 信任 ledger 與 Git，不信任過度簡化的摘要。新 session 先驗 health、保存 migration、將 diff 連到 active feature，再執行缺少 fixture，發現 unknown outcome 後 duplicated audit insert。

修復後交接包含 final commit、完整 acceptance receipts、已知限制與下一個無關 task。第三個全新 session 不開舊聊天，也能說明功能狀態、證據與復原過程。

主張限制

課程使用 file-based state。分散式 production 系統可能需要 transactional state、lease、event log 與 concurrency control，不能直接複製教材閾值。

做法

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

現場情境

目前 authoritative state 是什麼，新 session 唯一安全的下一步是哪一項？

01定義 guarded transitions
02用固定儀式開始工作
03在已知 checkpoint 中斷

驗收條件

沒有舊 transcript 的 session 能重建目前工作、保存半成品、完成正確案例，並留下下一位可稽核的證據。

這張圖要幫你看懂什麼Guarded state machine 能直接看出 implemented 與 verified 差異，以及每條 transition 所需 evidence。

01
定義 guarded transitions
建立 pending、in-progress、blocked、implemented、verified，為每條轉換列 contract version、branch 條件、check evidence、actor 與 reason。Schema 要拒 verified 缺 evidence 與所有未知轉換。
檢查點 · 直接從 pending 到 verified、缺 commit 或少任一 critical receipt 都會 fail。
02
用固定儀式開始工作
執行 initializer、讀 Git history、載入 active contract 與 ledger、比對 branch cleanliness，再選一個 eligible item。保存 session ID、starting commit 與 environment evidence。
檢查點 · Active item、commit、health receipt、budget 與預計下一個 state transition 一致。
03
在已知 checkpoint 中斷
部分實作後停止，誠實保留 dirty 或 committed state。記錄完成與失敗檢查、open files、decision、blocker 和唯一 next action，不得標 verified。
檢查點 · Handoff 能解釋 incomplete work，不依賴舊聊天，也沒有隱藏 branch 狀態。
04
Cold resume 並 reconcile
新 session 依 startup ritual 比較 saved state，完成缺少的驗收，僅透過合法 transition 更新 ledger，最後留下 clean commit 與 receipt。
檢查點 · Fresh session 選對下一步、沒有重複已完成效果，並由 named evidence 到 verified。

實務脈絡

展示版之後

讓 verified 成為受保護狀態

Implemented 代表已有對應 commit，verified 則要通過 contract 指定的完整 pipeline。狀態轉換保存 from、to、actor、reason、timestamp、contract、commit 與 evidence IDs；不允許 pending 直接跳 verified，也不允許 agent 自己引用一句完成宣告當 evidence。

Blocked 要說明缺少哪個 authority 或外部條件、誰能解、已嘗試什麼、最後健康 checkpoint、目前 branch 狀態，以及等待期間還有哪些工作安全。它不是把不確定工作丟進角落的標籤。

交接先對齊 repository truth

Startup 要比較 ledger、Git status、最近 commit、environment receipt 與 effect ledger。Ledger 若寫 verified 但 commit 不存在，或 branch 有未記錄 migration，就先 reconcile，不能開新 task。Shutdown 則留下 clean commit，或將 dirty diff、failed check 與下一步寫清楚。

Progress log 不需要保存完整對話。留下 current decision、state change、evidence、failure、blocker 與 next action 即可。被推翻的假設可放 decision history，但不應混進 current state，讓新 session 誤以為仍有效。

交付補強

Ledger schema 要把觀察與事實拆開。Agent 可以記『懷疑 retry 會重複 audit』作為 hypothesis；真正 effect count 只由 verifier 或 authoritative ledger 寫入。若兩者混成自由文字，新 session 可能把推測當已證實，或把失敗 evidence 當成待辦備註而忽略。每個 evidence ID 都要能解析到特定 run、commit、environment 與 contract，不接受一張名為 latest 的可變截圖支撐 verified。

Blocked 狀態也需要健康檢查。等待產品 owner 時，approval deadline 可能過期、branch 可能被合併、fixture 可能升版。Resume 不能直接把舊 blocker 清掉；要重新讀 external condition，確認 actor 仍有權、contract 未改、working commit 可重放，再產生新的 transition event。等待期間若有不相依工作可做，ledger 應列 eligible 條件，不讓 agent 自行判斷哪個 adjacent task 可以順手開始。

Handoff packet 應讓接手者在短時間內回答六件事：正在做哪一份 contract、目前哪個 state、哪個 commit 或 dirty diff、哪些 checks 已跑且綁哪個版本、最後一個失敗與證據、唯一安全 next action。若 packet 還要讀完整 chat 才能回答，表示欄位不足；若 packet 充滿每輪嘗試細節，表示 current truth 被 history 淹沒。兩者都用 cold resume 時間與錯誤假設來調整。

Crash 與正常 shutdown 要走同一個一致性檢查，只是 crash 允許 incomplete receipt。程序收到 interrupt 時先停止新 dispatch，保存 outstanding lease、budget reservation、known effect、open files 與 last checkpoint；若無法完成 commit，就將 dirty tree hash 和 recovery command 寫入 ledger。下一個 session 先 reconcile，不要為了追求 clean Git 而把未知 diff 丟掉或重設。

狀態紀錄也要處理多人同時寫入。每次更新帶前一版序號，儲存時採條件式寫入；版本不符就重新讀取，不覆蓋另一個 session 的 blocker 或 evidence。若 task 已由別人移到 verified，舊 session 不能再送出 completed event；它只能保存自己的過期結果並結束。這項檢查能防止兩個背景工作各自相信手上的 snapshot，最後讓較晚寫入的人把較新的證據洗掉。

交接驗收應包含反例。把 ledger 中一個 commit 改成不存在、將 branch 留下未記錄檔案、移除一筆必要 receipt、讓 environment identity 指向另一個 worktree，再看新 session 是否在 startup gate 停下。只有正常交接成功，無法證明系統會對不一致誠實。每個反例要回不同診斷與修復責任，不能用一個『狀態有問題』要求 agent 自由猜測。

完成交接後，讓接手者用自己的話指出目前證據與限制，再由程式核對他引用的識別碼。若說法正確但引用不存在，仍不可進入下一個狀態；若引用完整但接手者誤解 blocker，也要保留為交接品質問題。

動手實作

中斷 session，再從 repository state 恢復

建立 feature ledger 與 handoff，做到第三個 checkpoint 時中斷，再開無 transcript 的新 session，量 orientation、錯誤假設、重工與 evidence recovery。

準備項目

• Commit initializer 與 task contract，確認 baseline environment healthy
• 準備另一個全新 session，只提供 repository path 與標準 startup 指令

本課產出

Machine-readable feature ledger、簡潔 progress log、handoff record、interrupted-run evidence 與 fresh-session resume receipt。

起始模板: 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

預期結果

沒有舊 transcript 的 session 能重建目前工作、保存半成品、完成正確案例，並留下下一位可稽核的證據。

留給下一課

Feature ledger 會成為工具回饋、mechanical rules、verification、recovery 與 work graph 的狀態輸入。後續每個 transition 都要連 contract 與 evidence ID。

驗收條件

01State transitions 明確，缺完整 evidence 不能到 verified
02Startup 對齊 contract、ledger、Git、branch、environment 與 priority
03中斷紀錄寫明進度、失敗、blocker owner 與唯一安全下一步
04Fresh resume 不重複 effect，最終 handoff 綁 commit 與 receipt

常見故障

故障診間

F1新 session 在 dirty branch 上開始另一個功能。

先檢查: 比較 Git status、recent commits、health、ledger 與 eligible-next 計算。
可能原因: Startup 信任摘要或 priority list，沒有對齊 repository state。
修復方式: 停止新工作，保存 diff 並連回 active item，再恢復 healthy checkpoint。
下次怎麼避免: 將 Git、health 與 ledger reconciliation 設為 startup gate。

F2Unit command 通過便把 feature 改成 verified。

先檢查: 檢查 transition evidence requirement 與 receipt ID。
可能原因: Implemented 與 verified 合併成由 agent 自信決定的狀態。
修復方式: 退回 implemented，跑缺少 pipeline，由 verifier 建立 verified。
下次怎麼避免: Schema 與 CI 一起執行 transition guard。

F3Progress file 變成很長的對話，新 session 反而看不懂。

先檢查: 分開 current decision、state、evidence、blocker、next action 與 raw dialogue。
可能原因: 保存聊天量，而不是當前 task truth。
修復方式: 依 operation schema 重寫 handoff，只留避免重犯所需的歷史。
下次怎麼避免: 限制 handoff 欄位，額外 narrative 另行歸檔。

展示版之後

正式上線前的邊界

01Durable state 跨 context reset 存在，authority 高於聊天摘要
02Pending、in-progress、blocked、implemented、verified 有合法 guarded transitions
03State change 記 actor、reason、contract、commit、timestamp 與 evidence IDs
04Startup 對齊 Git、health、branch、priority、lease 與 effect ledger
05Blocked state 指出缺少條件、owner、last checkpoint 與安全等待工作
06Shutdown 留下 clean commit 或另一 session 可復原的 explicit incomplete state

證據類型

資料來源與主張限制

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

[1]
長時間執行 agent 的有效 harness
Anthropic · 已發表研究 · 2026-08-26
initializer 模式 · feature ledger · session 交接 · 端到端驗證
[2]
Harness engineering：在 agent-first 開發環境中運用 Codex
OpenAI · 公開案例 · 2026-08-26
知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
[3]
Learn Harness Engineering
Walking Labs · 公開案例 · 2026-08-26
專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
[4]
Harness Engineering Guide
Nexu · 公開案例 · 2026-08-26
執行環境邊界 · 工具系統 · sandbox · 復原模式
[5]
Harness Engineering 學習指南
deusyu · 公開案例 · 2026-08-26
repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理