AI Coding 詞典拆解（05）：用 Handoff 讓工程工作跨 Session 延續

工程工作常比一段對話長。今天的 Session 可能找到問題、比較方案並改了一半程式，明天才有人有空接著做。若下一個 Session 只收到「延續昨天的工作」，它其實沒有昨天的脈絡，只能重新探索，或根據零碎線索猜測原本的決定。

這是 Handoff 要處理的核心：把必要狀態從短暫的 Context 移到接手者能讀取的地方，再說清楚哪些內容是已確認事實、哪些只是前一位工作者的摘要。本文沿著《Dictionary of AI Coding》第五單元，拆解清除、交接、壓縮摘要、Spec 與 Ticket 的界線，最後用一個工程情境走完整個流程。

先分清楚清除、交接和壓縮

一段 Session 會留下程式碼閱讀結果、工具輸出、討論、錯誤嘗試和決策。當這些內容累積到干擾下一步時，Clearing 是結束目前 Session，再以空白 Context 開始。它清掉的是新 Session 的工作脈絡；Harness 可能仍把舊對話保存在本機，但新 Session 不會因此自動知道舊對話寫過什麼。要延續工作，仍須明確指出檔案、工單或其他可讀資料。

Compaction 則是把既有 Session 的歷史濃縮成摘要，讓摘要進入後續 Context。它試著保留已選出的重點，因此比清除多帶一些脈絡；代價是原始細節不一定留下。若摘要寫了「重試邏輯已改成指數退避」，卻沒保留修改到哪個函式、測試覆蓋了什麼，接手者可能把一段未驗證的描述當成已完成的事。

Autocompact 是 Harness 根據 Context 容量自動啟動的 Compaction。它省去手動安排，但觸發時間通常由產品機制決定，可能剛好落在重構中途。上一個決策若只存在對話裡，就必須期待摘要選中它。不同工具會採用不同觸發條件、摘要格式和保存方式；不要把某個產品的容量門檻或行為當成通用規則。

Handoff 是把工作交給另一個 Session、代理或人。原詞典特別強調，新 Session 和舊 Session 之間沒有來回問答的返回路徑。接手者開始時只有明確交付的材料，因此不能靠「它大概知道我們之前討論過什麼」來安排工作。Handoff 可以用寫入環境的文件完成，也可以透過 Compaction 在同一工作流中傳遞摘要，兩者保留的內容和可檢查程度不同。

一手來源回答現況，次級來源說明脈絡

Primary Source 是要確認的事物本身。若問題是「目前程式怎麼處理重試」，程式碼和實際測試結果是一手證據；若問題是「上一個 Session 為什麼選這個方案」，原始討論紀錄或決策記錄才直接保存當時的理由。來源是否為一手，取決於你要回答哪個問題。

需求意圖和系統現況也可能分別由不同來源負責。若要確認團隊同意交付什麼，以目前核准的 Spec 或 Ticket 為準；若要確認服務現在實際怎麼執行，則回到程式碼、測試、日誌或線上讀回。Spec 對意圖可以是權威記錄，但它不能取代現行程式作為行為證據。交接時要把問題和證據來源配對，不要把「哪份文件永遠最權威」當成固定排序。

Secondary Source 是對一手資料的描述或摘要。Spec、Ticket、交接筆記、會議紀錄和 Compaction 摘要都可能扮演這個角色。它們把大量內容濃縮成接手者容易載入的資訊，卻也必然經過選擇。寫文件的人決定保留什麼，沒寫下來的細節對只讀文件的人就不可見。文件也會隨時間和現況分離，舊 Spec 可以準確描述上個月的架構，卻不一定能描述現在的程式。

這不表示 Secondary Source 不可靠或不該使用。沒有摘要和文件，大型工作很難塞進有限 Context，也很難在多人之間流轉。實際做法是先用它們快速理解目標，再按主張的重要性回到對應的一手來源核對。工單寫「登入測試已通過」，就重新跑相關檢查或讀取最新結果；文件寫「資料表已遷移」，就查看 migration、部署紀錄和實際資料狀態。交接文字提供路徑，不替路徑上的證據背書。

Handoff Artifact 要讓零背景的讀者能開工

Handoff Artifact 是一份由目前 Session 寫出、供下一個工作者讀取的交接資料。它可以是單獨的 Markdown 檔、Spec、Ticket 或計畫文件。好的文件假設讀者完全不認識這段工作，會使用具體的檔案路徑、提交編號和工單連結，而不是「改剛才那個檔案」或「照前面的討論」。

交接文件至少要讓讀者回答幾個問題：

• 目標是什麼？ 描述預期行為和驗收條件，避免只列「改 API」這種執行動作。
• 哪些決定已經做出？ 記錄選擇和理由，也寫出仍未解決的選項。只寫結論，接手者可能再次討論同一題。
• 現況在哪裡？ 列出分支、檔案、相關程式入口、最近一次提交和有用的工具輸出。
• 哪些工作已完成，哪些尚未完成？ 用可核對的狀態表述，例如「測試尚未執行」，不要用「差不多完成」代替證據。
• 下一步和停止條件是什麼？ 說明先做哪件事、何時需要回報，或哪些外部動作不能自行執行。

交接文件的價值在於可檢查和可重用。另一個 Session 能先讀懂內容，也能在依賴文件前發現錯誤或過時資訊。若同一份摘要要交給多個並行 Session，寫入環境的文件比只存在單次 Context 裡的摘要更容易共用。

Spec 管一段跨 Session 的工作，Ticket 管一個可執行範圍

Spec 是一段跨多個 Session 的工作的持續說明。它回答要打造什麼、為什麼做、有哪些限制、已選方案為何，以及目前有哪些 Ticket 和狀態。它會隨工作進展更新。Spec 可以是產品需求文件、設計文件、RFC，或一份短計畫。格式不是重點，能不能讓新的 Session 讀到目前意圖和進度才是。

Ticket 把一段工作縮到可交付的任務。它可獨立存在，也可隸屬某份 Spec，並列出目標、驗收條件、背景文件和 Context Pointer。Ticket 之間可以標示阻塞關係，工作順序因此由依賴圖決定，而不是硬塞成一條線。

把 Ticket 大致切成一個 Session 可完成的範圍，是詞典作者提出的工作尺度，不是所有專案都適用的硬性時間限制。判斷太大或太小，可以看實際 Session 的表現：如果 Session 經常還沒完成就失去必要脈絡，就拆小；如果每次開工都花大部分時間重讀背景，才做幾分鐘就結束，可能是切得太細。互不相依的 Ticket 可以交給不同 Session；有依賴的任務則先處理上游，避免平行修改互相等待或覆蓋。

用修改重試邏輯示範交接

假設一個 Session 要改善訂單服務的重試行為。它發現錯誤可能出現在網路中斷，也可能出現在伺服器回傳拒絕；團隊還不確定哪些錯誤適合重試。若 Session 即將結束，先不要只留下「加入退避，之後補測試」。先把仍未知的問題和已確認的現況拆開。

一份實用 Ticket 可以寫成：目標是避免暫時性網路失敗造成連續重送；驗收條件是可重試錯誤有上限和間隔，永久性錯誤不重試，測試涵蓋兩種情況。Context Pointer 指向 src/orders/retry.ts、呼叫端與現有測試。狀態記錄「已定位重試入口，尚未修改程式；錯誤分類規則待產品確認」。下一步是先確認錯誤分類，再實作和執行測試。若討論曾排除「所有 5xx 一律重試」，也寫出理由和決策來源。

下一個 Session 讀取 Ticket 後，先確認分支裡的程式碼是否仍相同，再讀測試和相關的當前 Spec。若程式已被其他提交改過，就按現在的一手來源調整計畫。它不應把交接寫的「已定位入口」讀成「已完成修改」，也不應把待確認的錯誤分類當成既定產品規則。

若交接內容和目前程式或測試結果衝突，不要把差異悄悄改寫成其中一方的敘述。先指出哪個主張過期、哪份證據不同，再確認這項變更是否已被另一項工作取代。接著更新 Ticket 或 Spec 的狀態和來源指標，讓第三個 Session 不會繼承相同誤差。這種回讀也能揭露工作期間有其他人改過程式、需求已改版，或前一份交接把「推測」誤記成「決定」。

交接常見的失敗來自模糊狀態和斷掉的脈絡

第一種失敗是把預定工作寫成已完成。「修好了」可能表示已改程式、已通過測試、已合併，甚至只是已經找出問題。這些狀態不能互換。交接時要說明完成到哪一層，並附上足以回讀的證據，例如變更檔案、測試命令和實際輸出。若檢查沒跑，明確寫「尚未執行」比省略測試狀態更有用。

第二種失敗是留下結論，沒留下理由。下一個 Session 看見「採用佇列，不直接重試」時，不知道這是因為服務契約、重複扣款風險，還是當時只是暫時沒時間做。記錄一兩句決策依據和被排除的方案，能避免後續重複推翻已確認的選擇，也能讓新證據出現時知道何時該重新討論。

第三種失敗是指標無法帶人找到正確資料。短期分支名稱、過期行號、無權限的儀表板網址，或只寫「去看 log」都可能讓接手者停住。提供穩定檔案路徑、Ticket ID、commit 或可搜尋的日誌條件，並標出來源適用的環境和時間。讀者仍須確認該版本和環境是不是目前要處理的對象。

最後要避免把交接做成完整逐字稿。探索過程有價值，但不必把每次失敗呼叫都搬進 Spec。保留會影響下一步的結果即可：確認過的事實、放棄方案的理由、尚未回答的問題、驗收條件和原始資料入口。若所有細節都留在文件裡，重點也可能被另一種形式的雜訊蓋過。

依工作階段選擇交接方法

手動 Clearing 適合目前對話已混入錯誤假設或多次失敗嘗試，而關鍵決策已經寫到環境中的時候。Compaction 適合同一工作還要繼續，且摘要能保留近期操作所需脈絡的時候。若希望控制摘要內容，可在自然階段邊界先整理決策，再手動壓縮；不要等到任務正改一半才發現 Autocompact 已經觸發。

跨天、跨人、跨代理或跨工作區時，優先使用可讀回的 Handoff Artifact。這份文件不必逐字保存整段探索過程，應保留結論、理由、狀態、未決問題和原始證據入口。下一個工作者從它出發，但重要事實仍回到程式碼、測試、日誌或需求來源確認。

一個簡單的交接檢查是把自己當成全新的 Session：只讀交接文件，能否知道要改什麼、哪些選擇已定、從哪裡查現況，以及怎麼證明完成？若仍需要問「昨天你說的那個檔案是哪個」，交接還沒有完成。

本文依據《Dictionary of AI Coding》固定快照的 Section 5 — Handoffs，並以其 Handoff、Primary source、Secondary source、Spec 和 Ticket 詞條為框架。產品實作請以當前文件為準，例如 OpenAI Compaction、Claude Code sessions 和 Claude Code context window。本文是依詞條重組的教學，不是逐句翻譯。