Claude Code SDK #29：Checkpointing 全解——/rewind × Restore × Summarize，把长任务风险降到可撤销

长任务最怕的不是 Claude 写错代码，而是你发现方向错了，却已经让它改了 12 个文件、跑了几轮排障、上下文也塞满了。

Checkpointing 解决的就是这个尴尬：它不是 Git 的替代品，也不是普通聊天记录；它是 Claude Code 在一次 session 里给你准备的「本地撤销栈」。代码、对话、上下文压缩，可以分开处理。

本文按 2026-06-24 抓取到的 Anthropic 官方文档整理，重点讲一个问题：什么时候该用 /rewind，什么时候该用 branch，什么时候必须回到 Git。

01｜先把边界说清：checkpoint 管的是「Claude 亲手改过的文件」

Claude Code 文档对 checkpointing 的定义很直接：它会在你工作时自动跟踪 Claude 的文件编辑，让你在事情跑偏时快速撤销并回到之前的状态。1

这里有两个关键词：Claude 的文件编辑，以及之前的状态。

这意味着 checkpoint 更像一个 session 级别的「时间点」。它不是仓库级版本历史，也不负责记录所有副作用。官方文档明确说，checkpoint 会跟踪 Claude 文件编辑工具造成的变化；每个用户 prompt 会创建一个新 checkpoint，checkpoint 还能跨 session 保留，因此你恢复对话后仍可访问。1

把它放进开发工作流里，可以得到一张简单的分工表：

你要解决的问题	优先用什么	原因
Claude 刚改坏了几个文件	`/rewind` 的 Restore code	回到某个 prompt 前后的代码状态
对话上下文被带偏了	Restore conversation 或 Summarize	不一定要碰磁盘文件
想试另一条实现路线	`/branch` 或 `--fork-session`	保留原路线，另开一条会话分支
要长期保存可协作历史	Git commit / branch	checkpoint 只适合本地、session 级恢复

第一条实践建议：在让 Claude 做大范围改动之前，别急着把指令写成一大坨。把任务拆成几个 prompt，等于主动增加可回滚点。

02｜`/rewind` 打开的不是一个按钮，而是一组动作

进入 rewind 的方式有两个：运行 /rewind，或者在输入框为空时按两次 Esc。如果输入框里已经有文字，双击 Esc 会先清空输入框，而不是打开菜单；被清掉的文本会进入输入历史，之后可以按 Up 找回。1

打开菜单后，你看到的是本 session 里发过的 prompt 列表。选中一个点后，可以做六类操作：

动作	会改代码吗	会改对话吗	适合场景
Restore code and conversation	会	会	方向彻底错了，代码和上下文一起退回
Restore conversation	不会	会	文件当前还行，但对话被错误假设污染了
Restore code	会	不会	想撤销文件改动，但保留后面讨论出来的判断
Summarize from here	不会	压缩选中点之后	后半段调试太啰嗦，想释放上下文
Summarize up to here	不会	压缩选中点之前	前期铺垫太长，只保留近期细节
Never mind	不会	不会	返回列表，不做任何变化

这些动作不是同义词。官方文档把 restore 和 summarize 分得很清楚：restore 是还原状态，会撤销代码、对话或两者；summarize 是把对话的一部分压缩成 AI 生成的摘要，不改变磁盘上的文件。1

Checkpointing 回滚边界示意 — 自制示意图：checkpoint 更像 session 内的时间线，restore、summarize 和 Git 负责的边界不同。依据官方 Checkpointing 文档整理。1

03｜三种 Restore，别混用

我建议把 restore 当成三个不同工具，而不是一个「撤销」按钮。

三种 Restore 的决策差别 — 自制决策图：Restore code、Restore conversation 和 Restore code and conversation 改动的对象不同，依据 Checkpointing 官方文档整理。

Restore code and conversation：整段回到过去

这个动作会把代码和对话都退回到你选中的点。它适合在任务方向完全错掉时使用，比如你让 Claude 按错误的架构拆模块，结果它已经沿着错误假设改了多处文件。

这种情况下，只恢复代码不够。因为后续对话里已经积累了错误前提，Claude 还会继续沿着那条路想。Restore code and conversation 的价值，就是连那条对话路径也一起切掉。官方菜单里把它描述为「revert both code and conversation to that point」。1

Restore conversation：保留文件，清掉错误上下文

这个动作更细。它会把对话退回到某条消息，但保留当前代码。

典型场景是：Claude 最后改出的代码还可以，但中间那段对话已经堆了很多错误解释、误判原因、临时猜测。你想让它基于当前文件重新分析，而不是继续被旧上下文牵着走，就用 Restore conversation。官方文档把它列为「rewind to that message while keeping current code」。1

Restore code：撤文件，不撤讨论

这个动作会还原文件变化，但保留对话。它适合「分析有用，落地代码不满意」的情况。

比如 Claude 已经帮你比较了三种方案，也定位出真正的问题；只是它写出的 patch 太激进。你可以 Restore code，留下那段分析，然后让它按更小的改动重写。官方文档把这个动作描述为「revert file changes while keeping the conversation」。1

04｜Summarize 不是回滚，它是更精确的 `/compact`

很多人会把 summarize 当成「轻量回滚」。这个理解不准。

Summarize from here 会保留选中消息之前的内容，把选中点和之后的消息压缩成摘要；Summarize up to here 则会压缩选中消息之前的内容，保留选中点之后的消息，并让你停在对话末尾。官方文档还说明，原始消息仍保存在 session transcript 里，Claude 需要时仍可引用细节。1

这就给了你一个很实用的上下文管理方式：

早期需求讨论很长，但后面 patch 细节很关键：用 Summarize up to here。
后半段排障走偏了，但开头需求还要保留：用 Summarize from here。
整个上下文都太长，只想压成一份总摘要：再考虑 /compact [instructions]。Sessions 文档把 /compact [instructions] 描述为用摘要替换历史，并且可以按你的指令聚焦。2

注意，这一步不会改磁盘文件。所以它不能替你撤销坏 patch，只能让对话重新变轻。

05｜什么时候不要 rewind，而要 branch

Checkpointing 文档里有一句容易被忽略的话：如果你想在保留原 session 完整的同时尝试另一种方法，应该用 fork，而不是 summarize；命令示例是 claude --continue --fork-session。1

Sessions 文档对 branch 的解释也很清楚：branch 会复制到目前为止的对话，并切换到新分支，原 session 保持不变；你可以在 session 内运行 /branch，也可以在命令行把 --continue 或 --resume 与 --fork-session 组合使用。2

我的使用规则是：

情况	用 rewind	用 branch
已经知道当前路线错了	是	不一定
想保留当前路线，同时试另一版	不建议	是
只是想释放上下文	用 Summarize	不需要
要把实验路线长期保留	先 branch，再配合 Git	是

还有一个安全细节：Sessions 文档说明，原 session 中「allow for this session」批准过的权限不会带到新 branch。2 这很好，尤其是你在新路线里要让 Claude 跑脚本、改更多文件时，权限应该重新过一遍脑子。

06｜最容易踩坑的边界：Bash、手改、并发 session

Checkpointing 有三个边界，必须记住。

Checkpointing 的三个边界 — 自制边界图：Bash、外部改动和长期历史是使用 checkpointing 时最容易误判的三类情况，依据 Checkpointing 官方文档整理。

第一，Bash 改文件不在 checkpoint 的可靠覆盖范围里。官方文档直接举了 rm file.txt、mv old.txt new.txt、cp source.txt dest.txt 这类例子，并说明这些文件修改不能通过 rewind 撤销；只有 Claude 文件编辑工具直接做的编辑会被跟踪。1

第二，外部改动通常不被跟踪。你自己在编辑器里手动改文件，或者另一个并发 session 改文件，checkpoint 一般不会捕捉，除非它们碰巧改了当前 session 也在编辑的文件。1

第三，它不是版本控制。官方文档建议继续用 Git 保存 commits、branches 和长期历史，并把 checkpoint 理解成「local undo」，把 Git 理解成「permanent history」。1

所以，别把 /rewind 当保险箱。它更像座位旁边的撤销键，方便你在一次 Claude Code 工作流里快速掉头；真正要留档、协作、上线前审计，还是回到 Git。

07｜一套可以照做的使用顺序

如果你今天要把 checkpointing 用进真实项目，可以按这个顺序来：

大任务先拆 prompt。 不要一次性丢「重构整个鉴权模块」。先让 Claude 读结构、列 plan、改第一小块。每个 prompt 都会形成一个 checkpoint，这样回滚点更细。1
危险改动前先提交 Git。 checkpoint 只负责 session 级本地撤销，Git 才负责长期历史。1
Claude 改坏文件，用 Restore code。 如果讨论过程还有价值，就别连对话一起清掉。
Claude 被错误假设带偏，用 Restore conversation。 代码保留，让它重新基于当前文件分析。
方向彻底错，用 Restore code and conversation。 这时不要恋战，直接回到错误出现前。
上下文太吵，用 Summarize。 只压对话，不动文件；需要保留最近细节时，用 Summarize up to here。1
想试另一种方案，用 branch。 Sessions 文档里的 /branch 和 --fork-session 更适合平行实验，而不是把原路线压成摘要。2

最后给一个判断句：如果你想「撤销刚才」，先看 checkpoint；如果你想「保存历史」，先看 Git；如果你想「另开路线」，先看 branch。把这三件事分清，Claude Code 的长任务会稳很多。