Claude Code SDK #29：Checkpointing 全解——/rewind × Restore × Summarize，把长任务风险降到可撤销
Checkpointing 是 Claude Code 的 session 级本地撤销机制。本篇拆解 /rewind、三种 Restore、两种 Summarize、branch 与 Git 的边界，并给出一套长任务中可直接照做的回滚顺序。
长任务最怕的不是 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
03｜三种 Restore，别混用
我建议把 restore 当成三个不同工具，而不是一个「撤销」按钮。
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。1Sessions 文档对 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 有三个边界，必须记住。
第一，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 的长任务会稳很多。
References
- 1Checkpointing - Claude Code Docs
docs.anthropic.com
- 2Manage sessions - Claude Code Docs
docs.anthropic.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.