建立完整的交接文件，讓 AI 代理能無縫銜接工作，消除歧義。觸發時機：(1) 使用者要求交接/記憶/儲存上下文、(2) 上下文視窗接近容量、(3) 完成重大任務里程碑、(4) 工作階段結束、(5) 使用者說「儲存狀態」、「建立交接」、「我需要暫停」、「上下文快滿了」、(6) 恢復工作時說「載入交接」、「從…繼續」、「從上次中斷處繼續」。在大量工作（多次檔案編輯、複雜除錯、架構決策）後主動建議建立交接。解決長時間運作代理的上下文耗盡問題，讓新代理能零歧義地繼續工作。
交接
建立完整的交接文件，讓新的 AI 代理能無縫銜接工作，消除歧義。解決長時間運作代理的上下文耗盡問題。
模式選擇
判斷適用哪種模式：
建立交接？ 使用者想儲存當前狀態、暫停工作，或上下文快滿了。
- 遵循：下方的「建立」工作流程
從交接恢復？ 使用者想繼續先前的工作、載入上下文，或提到現有的交接文件。
- 遵循：下方的「恢復」工作流程
主動建議？ 在大量工作（5 次以上檔案編輯、複雜除錯、重大決策）後，建議：
「我們已經取得顯著進展。建議建立交接文件，為未來的工作階段保留此上下文。準備好時請說『建立交接』。」
建立工作流程
步驟 1：產生框架
執行智慧框架腳本，建立預填的交接文件：
python scripts/create_handoff.py [task-slug]
範例：python scripts/create_handoff.py implementing-user-auth
用於延續交接（連結到先前工作）：
python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
腳本會：
- 必要時建立
.claude/handoffs/目錄 - 產生含時間戳記的檔名
- 預填：時間戳記、專案路徑、Git 分支、近期提交、修改過的檔案
- 如果是延續先前交接，加入交接鏈結
- 輸出檔案路徑供編輯
步驟 2：完成交接文件
開啟產生的檔案，填寫所有 [TODO: ...] 區段。優先處理以下區段：
- 當前狀態摘要 - 現在正在進行什麼
- 重要上下文 - 下一個代理「必須」知道的關鍵資訊
- 立即下一步 - 清楚、可執行的第一步
- 已做的決策 - 附帶理由的選擇（不只是結果）
使用 references/handoff-template.md 中的範本結構作為指引。
步驟 3：驗證交接
執行驗證腳本，檢查完整性和安全性：
python scripts/validate_handoff.py <handoff-file>
驗證器檢查：
- [ ] 沒有遺留的
[TODO: ...]佔位符 - [ ] 必要區段已存在且已填寫
- [ ] 未偵測到潛在機密（API 金鑰、密碼、令牌）
- [ ] 引用的檔案存在
- [ ] 品質分數（0-100）
若偵測到機密或分數低於 70，請勿完成交接。
步驟 4：確認交接
向使用者回報：
- 交接檔案位置
- 驗證分數及任何警告
- 已擷取的上下文摘要
- 下一個工作階段的第一個行動項目
恢復工作流程
步驟 1：尋找可用的交接
列出目前專案中的交接：
python scripts/list_handoffs.py
這會顯示所有交接的日期、標題和完成狀態。
步驟 2：檢查時效性
在載入前，檢查交接的時效性：
python scripts/check_staleness.py <handoff-file>
時效性等級：
- FRESH：安全恢復 - 交接後變更極少
- SLIGHTLY_STALE：檢視變更後再恢復
- STALE：恢復前仔細驗證上下文
- VERY_STALE：考慮建立新的交接
腳本檢查：
- 交接建立以來的時間
- 交接以來的 Git 提交
- 交接以來變更的檔案
- 分支分歧
- 遺失的引用檔案
步驟 3：載入交接
在採取任何行動前，完整讀取相關的交接文件。
如果交接是鏈結的一部分（有「延續自」連結），也請閱讀連結的前一個交接以獲得完整上下文。
步驟 4：驗證上下文
遵循 references/resume-checklist.md 中的檢查清單：
- 確認專案目錄和 Git 分支相符
- 檢查阻礙是否已解決
- 驗證假設仍然成立
- 檢視修改過的檔案是否有衝突
- 檢查環境狀態
步驟 5：開始工作
從交接文件中的「立即下一步」第 1 項開始。
工作時參考這些區段：
- 「關鍵檔案」了解重要位置
- 「發現的關鍵模式」了解要遵循的慣例
- 「潛在陷阱」避免已知問題
步驟 6：更新或鏈結交接
工作時：
- 在「待辦工作」中標記已完成項目
- 將新發現加入相關區段
- 對於長時間的工作階段：使用
--continues-from建立新的交接以形成鏈結
交接鏈結
對於長期專案，將交接鏈結在一起以維護上下文脈絡：
handoff-1.md (初始工作)
↓
handoff-2.md --continues-from handoff-1.md
↓
handoff-3.md --continues-from handoff-2.md
鏈結中的每個交接：
- 連結到前一個
- 可將較舊的交接標記為已取代
- 為新代理提供上下文線索
從鏈結恢復時，先讀取最新的交接，再視需要參考前一個。
儲存位置
交接儲存在：.claude/handoffs/
命名慣例：YYYY-MM-DD-HHMMSS-[slug].md
範例：2024-01-15-143022-implementing-auth.md
資源
scripts/
| 腳本 | 用途 |
|---|---|
create_handoff.py [slug] [--continues-from <file>] |
使用智慧框架產生新的交接 |
list_handoffs.py [path] |
列出專案中可用的交接 |
validate_handoff.py <file> |
檢查完整性、品質和安全性 |
check_staleness.py <file> |
評估交接上下文是否仍為最新 |
references/
- handoff-template.md - 完整的範本結構與指引
- resume-checklist.md - 恢復代理的驗證檢查清單
