Communitygithub.com

工作階段交接技巧

當情境使用量接近上限(>60%)、在執行 /clear 或 /compact 之前、切換任務或結束編碼工作階段時(支援 Claude Code、Cursor 或 Codex),使用此技巧來產生結構化的交接文件,將執行狀態轉移到全新的代理工作階段,避免遺失情境或產生偏離。

工作階段交接技巧 是什麼?

「工作階段交接」技巧旨在解決大型語言模型工作階段因 token 累積導致效能衰減的問題。當上下文視窗接近容量、任務切換或工作階段結束時,代理會產出一份結構化的交接文件,將目前的工作狀態(包括目標、已實作內容、決策記錄、未完成項目及下一步動作)精確地傳遞給新的代理工作階段。此技巧支援 Claude Code、Cursor 和 Codex 等平台,其核心價值在於防止因重置工作階段而導致的狀態遺失、幻覺進度或重複錯誤。具體工作流程包含六個步驟:審查 Git 與工作區狀態、比對目標與實際成果、記錄決策與放棄路徑、整理受影響的檔案與符號、標記未解決問題及其擁有者與驗證方式,以及指定明確的下一步行動。該技巧強調事實與推測分離、禁止模糊描述,並要求所有參考皆使用真實工作區標識符。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/alapha888/session-handoff-kit/tree/master

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

工作階段交接技巧 是做什麼的?

目的

大型上下文視窗會隨著 token 數量累積,導致指令遵循度、推理精確度與工具準確度下降。長時間的工作階段充滿了已被取代的計畫、中斷的草稿以及重複的錯誤追蹤。重置為全新的工作階段可以恢復效能,但盲目地丟棄上下文會導致狀態遺失、產生幻覺的進度以及重複的錯誤。

session-handoff 技巧標準化了代理如何快照當前狀態。它將短期的運作記憶轉換為一份可行、可驗證的橋接文件,供下一個工作階段使用。


工作流程:結束工作階段(6 個步驟)

當代理工作階段達到操作極限或暫停工作時,請執行以下步驟:

  1. 審查 Git 與工作區狀態 執行 git status -s 和 git diff --stat 以建立基於現實的依據。切勿依賴聊天記錄來判斷哪些檔案被修改過。識別已修改、未追蹤以及已暫存的檔案。

  2. 捕捉目標狀態與實際實作狀態 用一句話定義原始目標。精確記錄哪些內容已驗證為可運作(附上通過的測試指令或執行時期檢查),哪些仍為部分完成或未經驗證。

  3. 記錄已做出的決策與放棄的路徑 列出在工作階段中確定的架構與設計選擇,並附上具體的理由。明確記錄負面決策(嘗試過但放棄的方法),以防止下一個代理重新嘗試失敗的解決方案。

  4. 整理受影響的檔案與相關符號 列出被修改或參照的關鍵檔案路徑、函式、類別與 schema 定義。必要時包含行號參考。

  5. 標記未解決的問題及其擁有者與驗證方式 列出所有未解決的邊界情況、失敗的測試、延遲的任務以及環境限制。每個未解決的問題必須指定由誰解決(人類或代理)以及如何驗證完成。

  6. 指定立即的下一步行動 草擬一個單一、原子、明確的指令,供下一個代理在第一次互動時執行。不要提供廣泛的列表;請指定要運行的確切指令或要編輯的第一個檔案。


操作規則

  • 區分事實與推測:通過的測試是事實;假設程式碼能編譯就代表能運作是推測。將未經驗證的假設明確標示為 [UNVERIFIED]。
  • 強制要求未解決問題的擁有者與驗證方式:每個未解決的問題必須指定擁有者(Human 或 Agent)以及確定性的驗證標準(例如 pytest tests/auth/test_token.py:test_refresh_rotation passes)。
  • 禁止模糊的延續指示:切勿撰寫「繼續處理驗證功能」或「完成前端元件」。請指出確切的符號、檔案以及失敗模式。
  • 參考真實工作區識別碼:所有對程式碼的參考必須使用確切的檔案路徑與符號名稱。請勿使用通用化的虛擬碼描述。

範例:工作階段交接備忘錄

# 工作階段交接:JWT 輪換實作

### 目標與當前狀態
- **目標**:在 FastAPI 驗證服務中實作 refresh token 輪換與撤銷。
- **當前狀態**:Refresh token 資料庫遷移已完成,輪換端點已建立。Token 產生與資料庫持久化功能正常運作。撤銷黑名單快取尚未接入依賴驗證器。
- **驗證**:`pytest tests/test_auth_tokens.py` 通過(4/4 測試)。

### 已做出的決策(附理由)
- **使用 Redis 存放 Token 撤銷清單**:選擇 Redis 而非 Postgres 查詢來處理已撤銷的 JTI token,目的是將受保護路由的延遲保持在 5ms 以下。
- **拒絕無狀態 Refresh Token**:我們最初評估了在 JWT 聲明中使用滑動有效期而不持久化的方案,但由於被盜用的 token 在自然到期前無法被撤銷而放棄。
- **Token 格式**:選擇 UUIDv4 作為 `jti` 聲明,以維持與現有 session 儲存 schema 的相容性。

### 已變更的檔案
- `src/services/auth.py`:新增 `rotate_refresh_token(old_token: str)` 函式與 Redis 無效化呼叫。
- `src/models/tokens.py`:新增 `RefreshTokenRecord` SQLModel 表格,用於追蹤 token 家族。
- `alembic/versions/20261005_add_token_families.py`:用於建立 `token_records` 表格的遷移腳本。
- `tests/test_auth_tokens.py`:新增 token 家族產生與輪換的單元測試。

### 未解決的問題
- [Agent] 將 `verify_token_not_revoked` 接入 `src/api/deps.py` -> 驗證方式:檢查 `tests/test_auth_deps.py` 在 token 被列入黑名單時會失敗。
- [Agent] 處理輪換時 Redis 無法連接的資料庫回滾情況 -> 驗證方式:在單元測試中模擬 Redis 連線失敗。
- [Human] 在 `.env.test` 中為 CI 執行設定 `REDIS_AUTH_URL` 密鑰。

### 下一步行動
開啟 `src/api/deps.py`,從 `src.services.auth` 匯入 `is_token_blacklisted`。在 `get_current_user` 中,於 JWT 解碼驗證後立即插入該檢查。

### 注意事項
- 請勿修改 `src/core/config.py` 中現有的 `access_token` 到期時間(目前為 15 分鐘)。
- 在本地啟動 API 伺服器之前,必須先執行 Alembic 遷移腳本 `20261005_add_token_families.py`(`alembic upgrade head`)。

反模式

  • 聊天記錄傾印:將原始對話記錄直接貼進交接備忘錄。你會立刻用本來想要逃脫的對話雜訊污染下一個工作階段的上下文視窗。
  • 虛假完成:將某個模組標記為「已完成」,但實際上它僅被撰寫,並未執行或測試過。
  • 遺漏的絕路:省略那些失敗的方案。下一個代理會讀取程式碼庫,看到同樣明顯的路徑,然後重新實作那個已失敗的方法。
  • 抽象的下一個步驟:以「下一步:實作剩餘測試」結尾。新的代理會浪費 3-5 次不必要的互動來發現需要測試什麼。

限制

  • 此技巧僅能產生書面交接文件;無法保留即時狀態,例如正在執行的程序、未提交的終端機輸出或記憶體中的除錯上下文——請在備忘錄中明確記錄任何重要的項目。
  • 交接品質受限於結束工作階段所記錄的內容:未被寫下的決策、死路或檔案變更,無法被下一個工作階段還原。
  • 它不能取代版本控制或問題追蹤系統;請先提交工作成果,並在備忘錄中參考提交記錄或票證,而非重複記載。

相關技能