SpyBara
Go Premium

checkpointing.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 20 additions and 48 deletions.

2026
Tue 6 23:59 Sat 10 23:01 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Wed 28 23:57

Checkpointing

追蹤、回溯和總結 Claude 的編輯和對話以管理會話狀態。

Claude Code 會自動追蹤 Claude 在您工作時所做的檔案編輯，讓您可以快速撤銷變更並回溯到先前的狀態，以防任何事情出現偏差。

Checkpointing 的運作方式

當您與 Claude 合作時，checkpointing 會自動捕捉每次使用者提示開始一個回合前的程式碼狀態。

自動追蹤

Claude Code 追蹤由其檔案編輯工具所做的所有變更：

  • 每個使用者提示開始一個回合都會建立一個新的 checkpoint
  • Claude Code 在一個會話中保留最近 100 個 checkpoint 的檔案快照。捨棄較舊的 checkpoint 會刪除沒有其他 checkpoint 參考的快照檔案，除了每個檔案的第一個快照，VS Code 擴充功能將其用作會話差異的基準。
  • Claude Code 將 checkpoints 與對話一起儲存，因此您可以在恢復會話後仍然執行 /rewind
  • Claude Code 在保留掃描中刪除會話的檔案快照，預設情況下約在會話最後一次儲存後 30 天。回溯到快照已消失的 checkpoint 可能會失敗，並出現 No files were restored 錯誤。若要保留快照更久，請設定 cleanupPeriodDays。

回溯和總結

執行 /rewind，或在提示輸入為空時按兩次 Esc，以開啟回溯選單。

[!NOTE]

如果提示輸入包含文字，雙 Esc 會清除它而不是開啟選單。清除的文字會儲存到您的輸入歷史記錄中，因此在您完成回溯選單後，按 Up 可以召回它。

回溯選單列出您在工作階段期間傳送的提示詞。選擇您想要操作的點，然後選擇一個動作：

  • 恢復程式碼和對話：將程式碼和對話都回復到該點
  • 恢復對話：回溯到該訊息，同時保持目前程式碼
  • 恢復程式碼：回復檔案變更，同時保持對話
  • 從此處總結：將此點之後的對話壓縮為摘要，釋放 context window 空間
  • 從此處之前總結：將此點之前的對話壓縮為摘要，保持後續訊息完整
  • 算了：返回訊息清單而不進行任何變更

兩個程式碼還原選項只在所選 checkpoint 有追蹤的檔案變更可以回復時出現。如果該點之後沒有捕捉到檔案編輯，選單只會提供恢復對話、總結選項和算了。

恢復對話或選擇「從此處總結」後，所選訊息的原始提示會恢復到輸入欄位中，以便您可以重新傳送或編輯它。

選擇「從此處之前總結」會讓您留在對話末尾，輸入為空。使用任一總結選項，已總結對話標記會出現在對話中被壓縮訊息的位置。

回溯過去已清除的對話

如果您在同一個 Claude Code 程序中較早執行了 /clear，回溯選單會在清單頂部顯示一個額外的項目，標記為 /resume <session-id> (previous session)。選擇它以恢復在 /clear 執行前活躍的對話。該項目在您退出 Claude Code 或恢復不同會話之前可用。

引導摘要

總結不會改變磁碟上的檔案，原始訊息保留在會話記錄中，因此 Claude 仍然可以參考詳細資訊。若要引導摘要的重點，請用方向鍵反白總結選項，並在該列顯示**新增上下文（選用）**的位置輸入指示，然後按 Enter。使用其數字鍵選擇選項會立即總結，不需要指示。

[!NOTE]

總結讓您保持在同一會話中並壓縮上下文，就像有針對性的 /compact。若要分支並嘗試不同的方法，同時保持原始會話完整，請改用 /branch 或 claude --continue --fork-session。

常見使用案例

Checkpoints 在以下情況下特別有用：

  • 探索替代方案：嘗試不同的實現方法，而不會失去起點
  • 從錯誤中恢復：快速撤銷引入錯誤或破壞功能的變更
  • 迭代功能：進行變化實驗，同時知道您可以回復到工作狀態
  • 釋放上下文空間：從中點開始總結冗長的除錯會話，保持初始指示完整

限制

Bash 命令變更未追蹤

Checkpointing 不追蹤由 Bash 命令修改的檔案。例如，如果 Claude Code 執行：

rm file.txt
mv old.txt new.txt
cp source.txt dest.txt

這些檔案修改無法透過回溯撤銷。只有透過 Claude 的檔案編輯工具進行的直接檔案編輯才會被追蹤。

子代理編輯未復原

子代理使用 Claude 的檔案編輯工具進行編輯，但 Claude Code 通常不會在您的會話檢查點中捕捉這些編輯。回溯是否復原這些編輯取決於子代理的執行方式：

  • 前景分叉技能：具有 context: fork 的技能在前景執行，在您自己的回合期間編輯您的工作樹，因此回溯會照常復原其編輯。設定 background: false 以在前景執行分叉；有幾種情況（列在技能頁面上）無論設定如何都會在那裡執行。
  • 任何其他 subagent：回溯只會復原 Claude 在您的對話中已經編輯過的檔案。subagent 對其他檔案的編輯會保留，因此請使用 git 來還原它們。這包括在背景執行的分叉 skill（預設值）和背景 /code-review --fix 執行。

外部變更未追蹤

Checkpointing 只追蹤在目前會話中已編輯的檔案。您在 Claude Code 外部對檔案所做的手動變更以及來自其他並行會話的編輯通常不會被捕捉，除非它們碰巧修改與目前會話相同的檔案。

訊息在回合中途傳送未進行檢查點

在回溯功能表中，您在 Claude 仍在工作時輸入的訊息可能會被標記為不復原程式碼。Claude 在其回合結束前讀取了該訊息。檢查點是為開始回合的提示詞建立的，因此此訊息沒有自己的檢查點。Claude 讀取該訊息後所做的編輯會計入開始該回合的提示詞。

您不需要對訊息本身做任何處理。若要撤銷工作階段中該部分的檔案變更，請選擇開始該回合的提示詞，然後選擇復原程式碼或復原程式碼和對話。這會還原 Claude 在整個回合中的檔案編輯，包括您的訊息到達之前所做的編輯。選擇被標記的訊息仍會提供復原對話，這會將對話回溯到該訊息，並保持您的檔案原樣。

符號連結和硬連結路徑未復原

檢查點功能不會回溯符號連結或硬連結檔案。當您從 /rewind 功能表中選擇復原程式碼或復原程式碼和對話時，Claude Code 會跳過任何是符號連結或硬連結的追蹤路徑，並顯示 Restored the code, but skipped N files 警告。跳過的檔案保持其目前內容。若要撤銷工作階段對其中一個檔案的變更，請要求 Claude 反轉編輯或自己編輯檔案。dotfile 管理器符號連結到您的專案中的設定檔以及 pnpm 硬連結到位置的檔案都屬於此類別。

若要查看復原跳過的路徑，請在復原前使用 /debug 開啟偵錯記錄：~/.claude/debug/<session-id>.txt 中的偵錯記錄會列出每個跳過的路徑。如需每個跳過原因和復原步驟，請參閱錯誤參考中的 skipped-files 項目。

不是版本控制的替代品

Checkpoints 設計用於快速的會話級恢復。對於永久版本歷史和協作，請繼續使用版本控制（例如 Git）進行提交、分支和長期歷史。

另請參閱