Agent Session Handoff Governance
核心概念
1. Session Handoff vs. Project Governance
大多數 handoff 工具解決的是「把這次做了什麼告訴下一次」——這是 session 層的工具問題。
Governance 解決的是更上層的問題：
| 維度 | Session Handoff（工具層） | Project Governance（設計層） |
|---|---|---|
| 問題 | 怎麼把狀態傳給下一個 agent？ | 系統長期不失憶、不污染、不亂接手 |
| 對象 | 單次交接 | 整個 agent 生命週期 |
| 輸出 | handoff message / 摘要 | 治理框架 + 文件體系 |
| 觸發 | session 結束時 | 專案設計階段 |
2. 三個防護目標
AGENT Handoff Kit 提出的框架以「三個防」作為核心設計目標：
- 防失憶（Anti-Amnesia）：確保重要決策、狀態、任務記錄有持久化機制，不因 session 結束或 context 清空而消失。
- 防污染（Anti-Pollution）：確保不相關的上下文不會被帶入新 session，造成 agent 誤判或分心。
- 防錯誤接手（Anti-Mishandoff）：確保接手的 agent 能正確識別「該做什麼」「不該做什麼」「從哪裡繼續」。
3. 五個治理元素
AGENT Handoff Kit 的設計包含五個操作性元素：
- 新手引導：新 agent 進入既有專案時，如何快速獲取背景並開始工作（不問用戶已知的事）
- 交接：跨 session 的結構化交接格式（完成了什麼、識別了什麼、未完成什麼）
- 歸檔：完成狀態的保存方式，確保舊 session 的結論可被後續 agent 召回
- 讀取：文件讀取的優先順序規則（讀哪些文件、按什麼順序、跳過什麼）
- 跨 session 續接：從 handoff 文件恢復任務的標準流程，確保接手點正確
4. Task Continuity、Personal Memory、Learning：三層記憶框架
warmwater.dev「Task Continuity」文章提出一個精準的分類，把 AI 的「記憶問題」拆成三個性質不同的問題——常被混為一談，但解法截然不同：
| 層次 | 問題 | 本質 | 解法 |
|---|---|---|---|
| Task Continuity（任務連續性） | AI 如何在 session 重置後接續上次的任務？ | 狀態傳遞問題 | .tmp 結構化交接文件 |
| Personal Memory（個人記憶） | AI 如何記住「這個人是誰、怎麼工作」？ | 個人化問題 | 規則檔（行為規則）+ 個人化脈絡文件 |
| Learning（學習） | AI 如何從過去失敗中改進行為？ | 系統演化問題 | Ratchet 機制（失敗 → 永久規則） |
為什麼要拆開：三個問題混在一起解決時，解法互相干擾。把「任務進度」塞進 規則檔 會污染行為規則層；期望 handoff 文件承擔「個人化」功能導致每次都要重新解釋工作哲學；把「學習」交給 handoff 文件則讓每份 handoff 都需要帶著歷史失敗的紀錄，不必要地膨脹。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/claude-code-task-continuity）
5. .tmp 交接文件的四段設計原則
warmwater.dev 提出的 .tmp 格式聚焦在最低限度的交接信息——只包含四個段落：
| 段落 | 內容 | 設計邏輯 |
|---|---|---|
| Completed | 已完成的任務清單 | 避免下一個 session 重複做 |
| In Progress | 進行到一半的任務 + 當前狀態描述 | 明確接手點，不需要重新追蹤 |
| Notes for Next Session | 下一個 session 需要知道的注意事項 | 提早注入脈絡，減少探索成本 |
| Context to Load | 下一個 session 開始時應讀哪些文件（路徑列表） | 存的是索引，不是知識本身 |
「交接的是地圖，不是記憶」：第四段（Context to Load）體現了一個核心原則——handoff 文件不試圖複製 context，只告訴下一個 session「從哪裡讀什麼」。知識存在文件系統裡，handoff 只是索引。這讓 handoff 保持精簡，且在 context window 不同的情況下（不同工具、不同 session 長度）都能有效工作。
和 FLUX Vault 的對應：交接-YYYY-MM-DD-sessionN.md 的「識別/待執行」與「未完成」對應 In Progress + Notes；「下次銜接用的提示詞」附加了 Context to Load 功能。.tmp 的設計讓 FLUX Vault 現有格式有了理論依據，同時也指出一個潛在優化點：在交接文件中更明確地分離「索引（指針）」和「說明（脈絡）」兩種信息。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/claude-code-task-continuity）
6. Hook 信號通道原則：Hook 不是指令，是信號
Hook 的行為常被誤解為「Hook 觸發 → 某件事自動發生」。正確理解是：
Hook 只能透過 stderr 發送信號；LLM 決定是否採取行動。
- Hook 輸出到 stderr → Claude Code 讀到 → LLM 自行判斷要不要回應
- Hook 輸出不能強制 LLM 執行指令——它只是提供信號（警告、上下文、狀態更新）
- 唯一能 override LLM 決策的機制：
exit 2（BLOCK）exit 0= 繼續執行exit 2= 強制中斷（只有這個能阻斷執行）- 其他非零值 = 報告錯誤，但繼續執行
Harness 設計影響：
- Hook 的 stderr 輸出應該寫成自然語言提示（給 LLM 看），而非機器碼
- 若某個行為必須被強制（不能依賴 LLM 判斷），用
exit 2，而非 stderr 訊息 - 過度依賴 stderr 而非
exit 2是常見的 Hook 設計錯誤
對 Handoff Governance 的影響：若任何 handoff 流程依賴 Hook 觸發，需要確認用的是 exit 2（真正強制）還是 stderr 訊息（LLM 可能忽略）。防錯誤接手的可靠程度，取決於底層 Hook 設計是否使用了正確的強制機制。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/claude-code-hooks-guide）
核心框架
Governance = Handoff × 讀取順序 × 邊界規則
有效的 session governance 需要三個要素同時成立：
防失憶 = handoff 文件（什麼值得保留）+ 歸檔機制（在哪裡保留）
防污染 = context 邊界規則（哪些不帶入新 session）+ 讀取順序（先讀什麼）
防錯誤接手 = 新手引導文件（agent onboarding）+ 明確的任務邊界定義三個防護目標是環環相扣的：
- 沒有 防失憶，handoff 文件就是無根之木
- 沒有 防污染，即使有完整 handoff，新 agent 也會被舊 context 干擾
- 沒有 防錯誤接手，新 agent 即使讀了正確文件，也可能選錯起點
對 FLUX Vault 的應用
FLUX Vault 的設計已有對應機制，以三個防護目標檢視：
三個防護目標均已到位：防污染原為最弱環節（2026-05-27 建頁時僅靠短 session 習慣），2026-06-01 由 規則檔 v2.4.2 新增「Context 邊界規則（防污染）」正式補上——五類禁入清單（個人識別資料、學生資料、未公開商業資訊、他人私訊、API Keys）+ Subagent 邊界原則。至此三個防護目標均有明確規則支撐。
我的觀點
FLUX Vault 有 handoff 工具，但缺少 governance 框架語言
建頁時（2026-05-27）的結論是：Vault 在防失憶和防錯誤接手做得不錯，但在防污染方面幾乎沒有明確設計——靠的是「不要把 session 拉太長」和「需要換工具就換」的習慣，而不是明確的邊界規則。
防污染已從最弱環節補齊為明確規則（2026-06-01）
上述觀察促成了 規則檔 v2.4.2 新增「Context 邊界規則（防污染）」：五類禁入清單（個人識別資料、學生資料、未公開商業資訊、他人私訊、API Keys）+ Subagent 邊界原則。原本靠習慣的防污染已被制度化——靠明確規則的系統在換工具、換人接手時才能維持一致，這正是當初識別出的風險。
Governance 的本質是「讓 AI 長期工作不需要用戶持續介入維護」
這跟 Vault 的設計哲學高度一致：系統要能在 AI 工具之間無縫轉換，用戶要能在中斷後快速恢復，而不是靠記憶或重新解釋來補救。Governance 框架是這個目標的工程化。
AI 主動交接：Governance 的主動形式（2026-05-28 補充）
Claude Taiwan 社群（羅仁宏，2026-05-28）的案例提供了一個具體的 AI 主動 handoff 場景：Claude Code 在與 Codex 的 Markdown 對話中，主動識別出「這部分交給 Codex 更合適」並提出交接建議；Codex 後來也對 Claude 做了同樣的動作。這是 handoff governance 框架中一個尚未充分討論的形式——AI 主導的交接，而非人工觸發的交接。
相對於現有框架描述的「防錯誤接手」（確保接手者能識別該做什麼），AI 主動交接引入了一個新的治理問題：誰有權決定何時交接？ 在人工觸發的 handoff 中，這個問題由用戶控制；在 AI 主動交接的場景中，這個問題由 AI 自行判斷——這意味著 governance 設計必須回答：AI 在什麼條件下可以主動提議交接，邊界規則是什麼。
對 FLUX Vault 目前的工作流影響：現有的交接設計（handoff 文件、銜接提示詞）是人工觸發、人工確認的。羅仁宏案例暗示未來 AI 可能在長任務中自主提議「這段交給另一個 agent」，FLUX Vault 的 governance 設計是否能處理這種 AI 主動發起的交接，是值得在 session handoff governance 框架完善時預先考慮的問題。
return-by-death：「防失憶」機制的真實實作（2026-05-28 補充）
cutevisor/return-by-death（Weng Visor，Claude Taiwan）是一個把防失憶機制做成可部署工具的本土案例。它的核心設計是「輪迴記憶」——對應本篇的防失憶目標：
- 機制：Claude Code 透過 Telegram 運行，context 接近上限前 AI 被要求把關鍵決策、開放任務、進行中的偏好寫入
past_life_memory.md，然後重啟 session。新 session 讀入這份記憶，從中斷點繼續。這和 FLUX Vault 的 handoff 文件 + 銜接提示詞邏輯一致——差別在 Vault 是人工觸發，return-by-death 是 AI 在 Telegram 對話中自行觸發（用戶說「go reincarnate」）。 - 防失憶三要素在此的對應：
past_life_memory.md= handoff 文件；「go reincarnate」指令 = 手動觸發點；systemd service + auto-restart = 持久化機制（歸檔層）。
安全邊界提示：此架構把 Claude Code 接進 Telegram，本質上是「可以自然語言操控的遠端 shell」，打破了 Claude Code 設計預設的 human-in-the-loop 假設。作為防失憶設計的參考有價值；若要生產部署，需加入操作白名單、強制審計日誌、無人值守期間的暫停機制。（來源：GitHub https://github.com/cutevisor/return-by-death；Claude Taiwan 社群 / Weng Visor）
Task Continuity 框架讓 Vault 的三層記憶設計有了更精確的語言（2026-05-28 補充）
warmwater.dev 的三層拆分（Task Continuity / Personal Memory / Learning）讓我可以更清楚地說出 Vault 在做什麼：交接文件 解決的是任務連續性，不是個人化；規則檔 + 個人化脈絡 解決的是個人記憶；延伸方向.md 踩坑紀錄 + Ratchet 解決的是學習。三個層次之前都存在，但沒有這套語彙就很難向外說明，也很難在設計新機制時確認「這個解法在解哪一層的問題」。
待深化的問題：
- FLUX Vault 的「防污染」缺口應該如何填？→ ✅ 已完成（2026-06-01）：規則檔 v2.4.2 新增「Context 邊界規則（防污染）」，明確五類不應進入 AI context 的資料類型 + Subagent 邊界原則
- [x]
AGENT Handoff Kit的具體實作（repo/文件）→ ✅ 已結案（2026-06-10）：npm 版外部創作者/agent-handoff-kit已於頁內「Agent Handoff Kit — npm 驗證（2026-06-04 補充）」節驗證；skill 生態側 softaworks/agent-toolkit session-handoff 本次 repo 直讀確認屬實（1.6k★／123 forks／MIT），其「觸發條件清單」（context 將滿／milestone 完成／用戶說 save state）可對照校準 Vault 交接模板。
可連結的主題
- 延伸方向 — 三層記憶架構是 handoff governance 的底層理論基礎
- 延伸方向 — 規則檔 四層結構是 Vault 的 governance 文件體系
- 延伸方向 — Context Hygiene 是防污染的工具層實踐
- 延伸方向 — 知識庫「活起來」的前提是有效的記憶治理
Agent Handoff Kit — npm 驗證（2026-06-04 補充）
原「先前未驗證」條目已由 Codex 查核確認。
- npm package：
外部創作者/agent-handoff-kit（v0.3.25，2026-06-03 發布） - license：MIT
- 描述：Lightweight agent harness for project memory, handoff, and multi-session continuity
- 安裝：
npx --yes 外部創作者/agent-handoff-kit@latest init - 核心檔案結構：
dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md、dev/DOC_SYNC_REGISTRY.md、協作規則檔、規則檔、GEMINI.md、START_NEXT_SESSION_PROMPT.txt
定位對應本篇框架：SESSION_HANDOFF.md = 防失憶；PROJECT_INDEX.md = 防錯誤接手；START_NEXT_SESSION_PROMPT.txt = 新手引導入口。
保守邊界：package README 自稱早期可用版本，仍持續完善；不應視為成熟標準工具。
CCB / Claude Codex Bridge — 同場景對比工具（2026-06-04 補充）
- GitHub：https://github.com/SeemSeam/claude_codex_bridge
- GitHub 數據（2026-06-04）：stars 2,878 / forks 283 / open issues 72 / latest release v7.2.11（2026-06-04）
- License：AGPL-3.0（商用/閉源封裝需另外授權）
- 初步採用等級：
watch / lab trial
和 Agent Handoff Kit 的設計差異：
| 工具 | 核心設計 |
|---|---|
| Agent Handoff Kit | 跨 session 可接續文件（SESSION_HANDOFF.md 等）——解決的是任務連續性，本質是文件層治理 |
| CCB | 同一專案內同時啟動多個真 CLI agent 的可視化 tmux orchestration——解決的是多 agent 同步運作，本質是 runtime 層協調 |
| Headroom | agent context compression（CCR 可逆壓縮）——解決的是 context window 資源問題，本質是記憶壓縮層 |
三者互補而非競爭：Handoff Kit 管文件交接 → CCB 管 runtime 拓撲 → Headroom 管 context 壓縮。
CCB 正向信號：active 開發（2026-06-04 同日有 push + release）、有 CI workflows、README 操作清楚、支援 worktree 隔離。
CCB 風險信號：72 open issues、v7.2.x 多版 superseded、無 SECURITY.md、主 contributor 集中（bus factor 偏低）、native Windows 支援需走 WSL。
建議先在 disposable repo / toy project 試 main:codex + reviewer:claude 基本閉環，不直接接正式商業專案。
Trellis — 開發專案跨 session context 持久化（2026-06-05 補充）
和本篇框架的對應：
.trellis/= 防失憶層：需求、任務、進度的持久化- 「先規劃 → 再實現 → 再驗證 → 把經驗寫回專案」工作流 = 防錯誤接手的設計哲學
和 Agent Handoff Kit 的差異：
| 工具 | 核心設計 | 場景 |
|---|---|---|
| Agent Handoff Kit | npm package，跨 session 文件體系（SESSION_HANDOFF.md 等） | 任意專案，輕量導入 |
| Trellis | .trellis/ 目錄，含需求 + 規範 + 任務 + 進度全生命週期 | 深度整合開發工作流 |
對 行動 App / 教學管理系統系統的應用評估：Trellis 的「把開發決策寫進專案目錄」設計和 FLUX Vault 的 規則檔 哲學一致，適合在新一輪 行動 App 開發啟動時試用。保守邊界：先在 feature branch 試，確認格式穩定後再整合進主開發流程。
跨工具交接（Claude Code → Codex）：三層對齊案例（2026-07-11 補充）
來源：Threads 外部創作者（post/DapZV7BGX6C）；danyuchn 部落格〈從 Claude Code 搬家到 Codex〉＋ repo danyuchn/claude-codex-harness-sync（MIT／32★／last push 2026-05-03／Python，查核日 2026-07-11）
把工作從 Claude Code 交到 Codex（或反向）是本篇「防錯誤接手」在跨工具場景的放大版——不同 harness 的規則檔、技能、權限邊界都不同，只交一份對話摘要必然掉東西。社群實作收斂出三層對齊：
| 層 | 交什麼 | 為什麼不能省 |
|---|---|---|
| 任務層 | 先用 spec／完成標準固定「要做什麼」 | 沒有 spec，接手方只能從轉述 prompt 反推意圖 |
| Harness 層 | 同步 AGENTS/CLAUDE、skills、MCP、hooks、權限邊界——不是只交摘要 | 規則與能力不對齊，新 agent 會用錯工具或越界 |
| 狀態層 | progress／task 檔＋git 記錄完成處、未完成處與可回退點 | 沒有 checkpoint，中斷後無法安全接續（對應本頁 .tmp 四段） |
三來源共振：這三層分別由三個實作面佐證——① 規格驅動開發（SDD，見 延伸方向）給任務層；② harness sync 給 harness 層；③ progress.md＋git 給狀態層。三者拼起來才是完整交接，缺一層就退回「傳摘要」的失憶風險。
具體工具案例（harness 層）：danyuchn/claude-codex-harness-sync（MIT／32★／Python，查核日 2026-07-11）是一個 Codex skill，把「Claude Code harness → Codex harness」的遷移做成可稽核流程——不整包複製 .claude，而是先 audit、safe 項自動翻譯、風險項（hooks、MCP、memory、大型指令檔）標記為 model-assisted 手動處理；分 setup（首次遷移計畫）與 maintain（drift 報告）兩模式。誠實邊界：它本身走的是 audit＋「maintain 模式 drift 比對」，不是 progress.md＋git 的狀態傳遞——狀態層要另靠 progress 檔＋git，別把這個 repo 當一站式交接。小型單作者 repo，只當具體工具案例、不升獨立頁。
判斷補充——中介 agent 越多，意圖越容易被重新詮釋：每多一層轉手（人轉述 → agent A → agent B），原始意圖就多一次被重新詮釋的機會。所以跨工具交接要傳的是 spec 與 evidence（可驗證的完成標準、實際產物、git checkpoint），而非只傳「上一個 agent 說了什麼」的轉述 prompt。這是本頁「交接的是地圖，不是記憶」在多 agent 接力下的延伸：地圖要標的是可被獨立核實的座標，不是口述路線。
對 FLUX Vault 的對應：Vault 的 Cowork×Codex 對等協作已內建這三層——任務層＝統一協作任務包（spec＋交付路徑＋機械驗收）、harness 層＝各自的 協作規則檔／規則檔／skills、狀態層＝延伸方向.md＋交接檔＋每日 git snapshot。本案例佐證這套設計方向與外部社群獨立收斂一致。
2026-06-10 通膨重審誤降，同日經 Codex 複查恢復 evergreen：頁內有明確實踐證據（三防檢視表已落地、防污染缺口由本頁分析驅動 規則檔 v2.4.2 結案）。教訓＝證據掃描不能只靠 regex pattern，borderline 一律人工讀頁。