AI·系统·创造·人将如何自处

Checkpointing 与 /rewind

8分钟阅读

⚠️ 源单薄性声明 本条目只有 1 份官方 doc（checkpointing.md 95 行 + agent-sdk/file-checkpointing.md）。没有社群救场案例、没有 checkpoint 失效事故。 已讲清楚：checkpoint 是什么、怎么 rewind、三种恢复选项 还没听到：什么时候 checkpoint 不够用、和 git 怎么配合 本条目是基础功能说明，不是最佳实践。

一句话

Checkpointing = Claude 在改文件之前自动存一份快照，你随时可以 /rewind 回到某个时刻。

它自己做的

来源：checkpointing.md 的 “How checkpoints work” 段。

Claude Code 默认就开着：

  • 每个用户 prompt 之前创建一个新 checkpoint
  • 跨 session 持久化——下次 resume 还在
  • 自动清理——30 天后随 session 一起清掉（可配）
  • 只跟踪 Claude 文件编辑工具的改动（不是你手动改的）

不用你配置任何东西。

怎么用（/rewind）

按 Esc 两次 或输入 /rewind——弹出你这次 session 的所有 prompt 列表，选一个点执行恢复。

四个动作

checkpointing.md 列的选择菜单：

动作作用
Restore code and conversation代码和对话都回到那个点
Restore conversation只回滚对话，保留当前代码
Restore code只回滚代码，保留对话
Summarize from here把选中点之后的对话压成摘要（腾 context）

三种 restore 的区别非常重要——代码和对话可以独立回滚。常见场景：

  • “我写的东西还行但对话讲歪了” → Restore conversation
  • “代码改错了但对话讨论的思路还有用” → Restore code
  • “整个都不对” → Restore code and conversation

Summarize from here（很容易被忽略的一手）

和 /compact 有区别：/compact 压整个对话；summarize from here 只压你选的点之后的内容，前面保留完整。

用途：session 开头的需求分析你想保留，但中间的 20 次试错不想再占 context——选开头之后的点 → Summarize from here → 中间那段变成一个摘要。

Restore vs. Fork（重要对比）

doc 结尾有一句提醒：

“Restore 让你在同一个 session 里。如果你想分支出去试不同方法，同时保留原 session 完整，用 fork（claude --continue --fork-session）。”

  • Restore = 覆盖当前 session
  • Fork = 复制一份 session 到分支，两个都保留

想”试试另一种方案，不行就回来”用 fork。想”这次走错了重来”用 restore。

和 git 的关系

doc 没明说，但从社群实践推：

  • checkpoint 粒度比 git commit 细——每个 prompt 一个 checkpoint，commit 通常一段功能一个
  • checkpoint 30 天自动清，commit 永久
  • checkpoint 是 Claude 的 safety net，git 是 你 的 safety net
  • 不互相替代——都要

怎么用（5 步）

第 1 步：先确认你在用哪一种 checkpoint

交互式 Claude Code 里，这个功能默认就开着，你不用先敲任何 /checkpoint on 之类的命令。直接开 session、开始提需求，就已经在生成 checkpoint 了。
如果你是走 Agent SDK，才需要显式打开：enable_file_checkpointing=True（Python）或 enableFileCheckpointing: true（TypeScript）。如果你后面想按 UUID 精确回滚，还要加 extra_args={"replay-user-messages": None} / extraArgs: { "replay-user-messages": null } 来拿到 checkpoint UUID。

反过来说，SDK 里把这个选项去掉或设成 false，就等于关闭文件 checkpointing；而交互式文档目前没有单独的”关闭 checkpoint”开关。

第 2 步：在大改前，故意打一个好找的”起跑点”

虽然每个 user prompt 都会自动建 checkpoint，但真到回滚时，很多人发现列表里全是”帮我试试""继续""再改一下”，根本认不出来。更稳的做法是：大改前先发一条短而明确的 anchor prompt，例如：

先只重构 auth 模块，不要动数据库 schema。

这条 prompt 本身就会生成一个 checkpoint，而且回头在 /rewind 列表里也好找。
如果你在 SDK 里做自动化，同理：把每个 message.uuid 存下来，至少保留”改之前”和”改之后”两个 restore point。

第 3 步：出事时，不要先手忙脚乱地 git checkout

交互式里最直接：

  1. 按 Esc 两次或输入 /rewind
  2. 选中出问题之前的那条 prompt
  3. 选对动作：
    • 代码坏了 → Restore code
    • 对话方向歪了 → Restore conversation
    • 两个都歪了 → Restore code and conversation

如果你在 SDK / CLI 自动化里做文件回滚，则用官方给的 CLI 形式：

claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

这个命令只回文件，不回对话历史。

第 4 步：把 checkpoint 当短期缓存，不要把它当仓库

官方的清理逻辑是：checkpoint 跟 session 绑在一起，30 天后一起自动清。所以别花时间找”删第 17 个 checkpoint”这种精细管理入口，当前文档没有这套工作流。

你真正该做的是：

  • 中途对话太臃肿：用 Summarize from here
  • 任务已经换题：用 /clear 开一个新 session
  • 还想保留旧线索：先 /rename，以后 /resume

一句话：checkpoint 的管理单位是 session，不是单个快照。

第 5 步：把 git 放在 checkpoint 前面，而不是后面

最容易踩的坑是：以为 /rewind 能兜一切。它兜不住 bash 改的文件。 官方文档明确说了：rm、mv、cp、echo > file 这类 bash 造成的改动，不在 checkpoint 跟踪里。

所以最佳实践其实很简单：

  1. Bash-heavy 操作前先 git commit 或至少开分支
  2. 让 checkpoint 负责 prompt 级的小步后悔药
  3. 让 git 负责 Bash、批量 codegen、长期历史和协作

把两层分工想清楚，才不会在关键时刻发现：/rewind 能倒回 Claude 的 Edit，却救不回你那次 rm -rf build && mv old new。

陈彬视角

这个功能容易被忽略但价值很高——尤其是 Claude 走偏时。新手的反应是手动 Ctrl+Z 或 git checkout，其实 /rewind 更精细（能单独回滚代码或对话，不用两个都牺牲）。

一个小习惯值得建立：大改之前先 git commit 一下。这样 checkpoint（短期救急）和 git（长期兜底）两层防护都在。Claude 搞崩了——/rewind 回一步；/rewind 也救不回来——git reset --hard。

这是 thin 级条目——官方 doc 只讲了”功能是什么”，没讲”什么时候 rewind 不够”。等社群里有人真的用 rewind 救场/失败一次，再补。

关联

needs_sources（明确待补）

  • 真实 /rewind 救场/失败案例
  • checkpoint 和 git commit 配合的社群实践
  • checkpoint 被自动清除带来的坑

关系图谱

反向链接