Claude Code 教程系列：检查点与回溯（Checkpoints）

检查点允许你保存对话状态并回溯到之前的点。这对于探索不同的方法、从错误中恢复或比较替代方案非常有用。

核心概念

#

什么是检查点？

#

检查点保存对话状态，包括：

• 所有交换的消息
• 对文件所做的修改
• 工具使用历史
• 会话上下文

检查点对于探索不同的方法、从错误中恢复或比较替代方案非常有价值。

图：检查点系统的数据流和存储架构，展示从用户交互到持久化存储的完整流程。

访问检查点

#

你可以通过两种主要方式访问和管理检查点：

使用键盘快捷键

#

按两次Esc（Esc + Esc）打开检查点界面并浏览保存的检查点。

使用斜杠命令

#

使用/rewind命令（别名：/checkpoint）进行快速访问：

# 打开回溯界面
/rewind

# 或使用别名
/checkpoint

回溯选项

#

当你回溯时，你会看到一个包含五个选项的菜单：

1. 恢复代码和对话 – 将文件和消息都还原到该检查点
2. 仅恢复对话 – 仅回溯消息，保持当前代码不变
3. 仅恢复代码 – 仅还原文件更改，保留完整的对话历史
4. 从这里总结 – 从该点开始压缩对话，释放上下文窗口空间。选定点之前的消息保持完整。不更改磁盘上的文件。原始消息保留在会话记录中。你可以选择性地提供说明以将总结聚焦于特定主题。
5. 算了 – 取消并返回当前状态

注意：恢复对话或总结后，所选消息的原始提示词会恢复到输入字段中，以便你可以重新发送或编辑。

图：五种回溯选项及其效果，选择不同的选项会产生不同的恢复行为。

自动检查点

#

Claude Code自动为你创建检查点：

• 每个用户提示 - 每次用户输入都会创建一个新的检查点
• 持久化 - 检查点跨会话持久化
• 自动清理 - 检查点在30天后自动清理

这意味着你总是可以回溯到对话中之前的任何一点，从几分钟前到几天前。

使用场景

#

检查点保留

#

Claude Code自动管理你的检查点：

• 每个用户提示自动创建检查点
• 旧检查点最多保留30天
• 检查点自动清理以防止无限存储增长

工作流模式

#

探索的分支策略

#

当探索多种方法时：

1. 初始实现 → 检查点A
2. 尝试方法1 → 检查点B
3. 回溯到检查点A
4. 尝试方法2 → 检查点C
5. 比较B和C的结果
6. 选择最佳方法并继续

安全重构模式

#

进行重大更改时：

1. 当前状态 → 检查点（自动）
2. 开始重构
3. 运行测试
4. 如果测试通过 → 继续工作
5. 如果测试失败 → 回溯并尝试不同的方法

检查点回溯流程

#

检查点的创建和使用流程如下：

flowchart TB
    A["用户发送消息"] --> B["自动创建检查点"]
    B --> C["保存: 消息"]
    B --> D["保存: 文件修改"]
    B --> E["保存: 工具历史"]
    B --> F["保存: 会话上下文"]

    C --> G["持久化存储"]
    D --> G
    E --> G
    F --> G

    G --> H["跨会话保存<br/>30天自动清理"]

    I["用户触发回溯"] --> J["打开检查点界面<br/>Esc+Esc 或 /rewind"]
    J --> K["选择检查点"]

    K --> L{选择回溯选项}
    L -->|恢复代码和对话| M["还原文件和消息"]
    L -->|仅恢复对话| N["仅回溯消息<br/>保持当前代码"]
    L -->|仅恢复代码| O["仅还原文件<br/>保留对话历史"]
    L -->|从这里总结| P["压缩对话<br/>释放上下文"]
    L -->|取消| Q["返回当前状态"]

    M --> R["继续工作"]
    N --> R
    O --> R
    P --> R
    Q --> R

    style A fill:#4dabf7,stroke:#1864ab
    style B fill:#69db7c,stroke:#2b8a3e
    style G fill:#ffd43b,stroke:#f08c00
    style I fill:#ff6b6b,stroke:#c92a2a
    style M fill:#da77f2,stroke:#862e9c
    style N fill:#da77f2,stroke:#862e9c
    style O fill:#da77f2,stroke:#862e9c
    style P fill:#da77f2,stroke:#862e9c

配置

#

检查点是Claude Code中默认启用的内置行为，不需要任何配置即可启用。每个用户提示会自动创建检查点。

与检查点相关的唯一设置是cleanupPeriodDays，它控制会话和检查点保留的时间：

{
  "cleanupPeriodDays": 30
}

• cleanupPeriodDays：保留会话历史和检查点的天数（默认：30）

限制

#

检查点具有以下限制：

• Bash命令更改不跟踪 - 文件系统上的rm、mv、cp等操作不捕获在检查点中
• 外部更改不跟踪 - 在Claude Code之外所做的更改（在你的编辑器、终端等）不捕获
• 不是版本控制的替代品 - 使用git进行永久、可审计的代码库更改

与Git集成

#

检查点补充（但不替换）git：

一起使用两者：

1. 使用检查点进行快速实验
2. 使用git提交进行最终确定的更改
3. 在git操作之前创建检查点
4. 将成功的检查点状态提交到git

快速入门指南

#

基本工作流

#

1. 正常工作 - Claude Code自动创建检查点
2. 想回去？ - 按两次Esc或使用/rewind
3. 选择检查点 - 从列表中选择以回溯
4. 选择要恢复的内容 - 选择恢复代码和对话、仅恢复对话、仅恢复代码、从这里总结或取消
5. 继续工作 - 你回到了那个点

键盘快捷键

#

• Esc + Esc - 打开检查点浏览器
• /rewind - 访问检查点的替代方式
• /checkpoint - /rewind的别名

何时回溯：上下文监控

#

检查点让你可以回去——但你怎么知道何时应该回去？随着对话的增长，Claude的上下文窗口被填满，模型质量会默默下降。你可能在一个半盲的模型下运送代码而没有意识到。

cc-context-stats通过向你的Claude Code状态栏添加实时上下文区域来解决这个问题。它跟踪你在上下文窗口中的位置——从Plan（绿色，可以安全地规划和编码）到Code（黄色，避免开始新计划）到Dump（橙色，完成并回溯）。当你看到区域转换时，你知道是时候检查点并开始新的，而不是在输出质量下降的情况下继续推进。

最佳实践

#

有效使用检查点

#

✅ Do:

• 回溯前审查可用的检查点
• 当你想探索不同的方向时使用回溯
• 保留检查点以比较不同的方法
• 理解每个回溯选项的作用（恢复代码和对话、恢复对话、恢复代码或总结）

❌ Don’t:

• 仅依赖检查点进行代码保留
• 期望检查点跟踪外部文件系统更改
• 使用检查点作为git的替代品

相关资源

#

• 官方检查点文档
• 高级功能指南 - 扩展思考和其他能力
• 内存管理 - 管理对话历史和上下文
• 斜杠命令 - 用户调用的快捷方式
• 钩子 - 事件驱动的自动化

总结

#

检查点是Claude Code中的自动功能，让你可以安全地探索不同的方法，而不必担心失去工作。每个用户提示都会自动创建一个新的检查点，所以你可以回溯到会话中的任何先前点。

主要好处：

• 无惧地尝试多种方法进行实验
• 快速从错误中恢复
• 并排比较不同的解决方案
• 与版本控制系统安全集成

记住：检查点不是git的替代品。将检查点用于快速实验，将git用于永久的代码更改。

这是Claude Code 教程系列的第八篇文章。下一篇文章将介绍Claude Code的高级功能。