claude-howto 实战：Claude Code Checkpoints 与 Rewind 完全指南——会话快照、安全回退与分支探索-港品优选

claude-howto 实战：Claude Code Checkpoints 与 Rewind 完全指南——会话快照、安全回退与分支探索

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

Checkpoints（检查点）是 Claude Code 内置的会话状态快照机制：每一条用户消息都会自动生成一个 checkpoint，记录消息、文件修改与工具调用历史，让你可以随时rewind（回退）到之前的任意状态。本指南基于 claude-howto 仓库的08-checkpoints模块（对应 vi/08-checkpoints/README.md 与 08-checkpoints/README.md），完整讲解 checkpoint 的访问方式、五种/六种回退选项、配置参数、保留策略与 Git 协同实战，读完后你将掌握用 Claude Code 安全试错、A/B 对比和恢复失误的标准工作流。

概述：Checkpoint 是什么

Checkpoints 允许你保存对话状态并在 Claude Code 会话中回退到之前的任意时间点，从而实现安全实验与多方案探索。它本质上是会话状态的快照（snapshot），包含：

全部消息往来（All messages exchanged）
已完成的文件修改（File modifications made）
工具使用历史（Tool usage history）
会话上下文（Session context）

在探索不同实现方案、从错误中恢复、或对比替代方案时，checkpoints 的价值无可替代——这是整个08-checkpoints模块的核心主张。

核心概念

概念	描述
Checkpoint（检查点）	会话状态快照，包含消息、文件与上下文
Rewind（回退）	返回之前某个 checkpoint，丢弃其后产生的所有变更
Branch Point（分支点）	从某个 checkpoint 出发探索多种不同方案

这三个概念构成了 checkpoint 工作的完整闭环：自动创建快照 → 在快照间回退 → 以某一快照为“分支点”尝试多条路径。

访问 Checkpoints 的两种方式

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

方式一：键盘快捷键

连续按两次Esc（Esc+Esc）即可打开 checkpoint 界面，浏览已保存的 checkpoints 列表。

方式二：Slash 命令

使用/rewind命令（别名：/checkpoint，另有/undo别名，见 CATALOG.md 内置命令表）快速访问：

# 打开 rewind 界面 /rewind # 或使用别名 /checkpoint # 等价别名 /undo

仓库的 QUICK_REFERENCE.md 也确认了这套访问方式：checkpoints 随每次用户 prompt 自动创建，回退用Esc两次或/rewind。

Rewind 选项菜单详解

当你执行 rewind 时，Claude Code 会展示一个选项菜单。根据 08-checkpoints/README.md（2.1.220 版本）的记录，完整菜单包含六项：

恢复代码和对话（Restore code and conversation）—— 将文件与消息同时回退到该 checkpoint。
恢复对话（Restore conversation）—— 仅回退消息，当前代码保持原样。
恢复代码（Restore code）—— 仅回退文件变更，保留完整对话历史。
从这里总结（Summarize from here）—— 将选中点之后到当前的对话压缩为一段 AI 生成的摘要，释放上下文窗口空间；选中点之前的消息保持完整，磁盘上的文件不会改变，原始消息仍保留在会话 transcript 中。你还可以选择性地提供指令，让摘要聚焦特定主题。
总结到此为止（Summarize up to here）—— 与上一项反向：把选中点之前的所有内容压缩为 AI 摘要，保留选中点之后的消息。与“从这里总结”配合，可实现上下文窗口的双向定向压缩；同样不改动磁盘文件，原始消息保留在 transcript 中。
没关系（Never mind）—— 取消并返回当前状态。

提示：恢复对话或执行总结后，选中消息对应的原始 prompt 会恢复到输入框中，方便你重新发送或编辑后再提交。

/clear不再是硬边界（v2.1.191+）：/rewind可以恢复到你执行/clear之前所创建的 checkpoint。清除对话不再永久丢弃其之前的状态——如果需要更早的代码或上下文，你可以跨过 clear 点继续回退。

自动 Checkpoints 机制

Claude Code 会自动为你创建 checkpoints，无需任何手动保存操作：

每条用户 prompt—— 每次用户输入都会创建新的 checkpoint
跨会话持久—— Checkpoints 在会话之间保留
自动清理—— 30 天后自动清理过期 checkpoint

这意味着你总能回退到对话中的任意先前时间点——无论是几分钟前，还是几天前。正因为如此，你可以把全部精力放在当前工作上，而不必操心手动保存状态。

典型使用场景

场景	工作流
探索方案（Exploring Approaches）	保存 → 尝试方案 A → 保存 → Rewind → 尝试方案 B → 对比
安全重构（Safe Refactoring）	保存 → 重构 → 测试 → 若失败：Rewind
A/B 测试（A/B Testing）	保存 → 设计 A → 保存 → Rewind → 设计 B → 对比
失误恢复（Mistake Recovery）	发现问题 → Rewind 到最后一次良好状态

使用 Checkpoints

查看与回退

按Esc两次或使用/rewind打开 checkpoint 浏览器，你会看到所有可用 checkpoints 及时间戳（timestamp）的列表，选中任意一项即可回退到对应状态。

Checkpoint 详情

每个 checkpoint 会显示：

创建时间戳
被修改的文件
对话中的消息数量
使用过的工具

这让你在回退前就能判断“该回到哪一步”，符合最佳实践中“先审查再回退”的要求。

实战示例

示例 1：探索不同实现方案

User: 给 API 加一层缓存 Claude: 我会在你的 API endpoints 上添加 Redis 缓存... [在 checkpoint A 处完成修改] User: 其实，换成 in-memory 缓存试试 Claude: 我会 rewind 去探索另一种方案... [用户按 Esc+Esc 回退到 checkpoint A] [在 checkpoint B 处实现 in-memory 缓存] User: 现在我可以对比两种方案了

示例 2：从失误中恢复

User: 用 JWT 重构认证模块 Claude: 我来重构认证模块... [完成大规模修改] User: 等等，这破坏了 OAuth 集成。我们回退吧。 Claude: 我来帮你 rewind 到重构之前... [用户按 Esc+Esc 选中重构前的 checkpoint] User: 这次换个更保守的方案

示例 3：安全实验

User: 试试用函数式风格重写这部分 [实验前自动创建 checkpoint] Claude: [完成实验性修改] User: 测试挂了。回退吧。 [用户按 Esc+Esc 回退到 checkpoint] Claude: 我已回退这些修改，试试其他方案吧。

示例 4：方案分支对比

User: 我想对比两种数据库设计 [记下 checkpoint —— 命名为 "Start"] Claude: 我来做第一种设计... [实现 Schema A] User: 现在让我回去试第二种方案 [用户按 Esc+Esc 回退到 "Start"] Claude: 现在我来实现 Schema B... [实现 Schema B] User: 太棒了！现在我有了两个 schema 可供选择

Checkpoint 保留策略（Retention）

Claude Code 会自动管理你的 checkpoints：

每条用户 prompt 自动创建 checkpoint
旧 checkpoint 最多保留30 天
自动清理以防止存储无限增长
只保留最近 100 个 checkpoint的快照；即使仍在保留期内，更旧的也会被丢弃

v2.1.117 更新：cleanupPeriodDays现在统一管理磁盘上四类缓存的保留期，而不仅是 checkpoints：
会话 checkpoints（Session checkpoints）
~/.claude/tasks/—— 持久任务列表
~/.claude/shell-snapshots/—— 捕获的 shell 环境快照
~/.claude/backups/—— 滚动保存的 settings / CLAUDE.md 备份
单个设置即可在相同天数后统一清理这四个目录。

Workflow 模式

探索的分支策略

当需要探索多种方案时：

1. 从初始实现开始 → Checkpoint A 2. 尝试方案 1 → Checkpoint B 3. Rewind 到 Checkpoint A 4. 尝试方案 2 → Checkpoint C 5. 对比 B 与 C 的结果 6. 选择最佳方案并继续

安全重构模式

进行大规模变更时：

1. 当前状态 → Checkpoint（自动） 2. 开始重构 3. 运行测试 4. 若测试通过 → 继续工作 5. 若测试失败 → Rewind 并尝试不同方案

最佳实践

由于 checkpoints 自动创建，你可以专注于工作本身，但仍需牢记以下实践：

✅应该：

回退前先审查可用的 checkpoints
想探索不同方向时使用 rewind
保留 checkpoints 以对比不同方案
理解每个 rewind 选项的作用（恢复代码和对话 / 恢复对话 / 恢复代码 / 总结）

❌不应该：

仅依赖 checkpoints 来保全代码
期望 checkpoints 追踪外部文件系统变更
用 checkpoints 替代 git commits

配置项

Checkpoints 是 Claude Code 的内置默认行为，无需任何配置即可启用——每条用户 prompt 都会自动创建 checkpoint。不过有两个设置控制其行为：是否拍照快照、以及保留多久：

{ "fileCheckpointingEnabled": true, "cleanupPeriodDays": 30 }

设置	默认值	作用
`fileCheckpointingEnabled`	`true`	在每次编辑前对文件拍照快照，使`/rewind`可以恢复。要求 v2.1.119+。在`/config`中显示为Rewind code (checkpoints)。等价环境变量：`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`
`cleanupPeriodDays`	`30`	会话历史与 checkpoints 的保留天数

对应的环境变量方式：

# 通过环境变量禁用文件快照（等价于 fileCheckpointingEnabled: false） export CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1

局限性（Limitations）

Checkpoints 存在以下限制：

Bash 命令造成的变更不追踪——rm、mv、cp等文件系统操作不会记录进 checkpoints
外部变更不追踪—— 在 Claude Code 之外（编辑器、终端等）做出的修改不会被记录
不是版本控制的替代品—— 持久化、可审计的代码变更请使用 git

v2.1.216 更新：/rewind不再通过被追踪路径上的符号链接（symlink）或硬链接（hard link）恢复或删除文件。若某个被追踪路径经由 symlink/hard link 解析，rewind 会跳过它而不是跟随链接，并报告因此跳过的路径数量。

故障排查（Troubleshooting）

找不到 Checkpoint

问题：找不到预期的 checkpoint

解决方案：

检查 checkpoints 是否已被清除
检查磁盘空间
确认fileCheckpointingEnabled已在设置中开启
确保cleanupPeriodDays设置得足够高（默认 30 天）

Rewind 失败

问题：无法回退到某个 checkpoint

解决方案：

确保没有冲突的未提交变更
检查 checkpoint 是否损坏
尝试回退到另一个 checkpoint

与 Git 的集成

Checkpoints 是 git 的补充（但并非替代）：

特性	Git	Checkpoints
范围	文件系统	对话 + 文件
持久性	永久	基于会话
粒度	Commits	任意时间点
速度	较慢	即时
共享	可以	有限

将两者结合使用：

用 checkpoints 进行快速实验
用 git commits 固化最终变更
在执行 git 操作前创建 checkpoint
把成功的 checkpoint 状态提交到 git

快速上手指南

基础工作流

正常工作—— Claude Code 自动创建 checkpoints
想回退？—— 按Esc两次或使用/rewind
选择 checkpoint—— 从列表中选中要回退的目标
选择恢复内容—— 从“恢复代码和对话 / 恢复对话 / 恢复代码 / 从这里总结 / 没关系”中挑选
继续工作—— 你已经回到了那个时间点

快捷键速查

Esc+Esc—— 打开 checkpoint 浏览器
/rewind—— 访问 checkpoints 的替代方式
/checkpoint——/rewind的别名
/undo——/rewind的另一别名（v2.1.108 起）

何时该 Rewind：上下文监控（Context Monitoring）

Checkpoints 让你能“回到过去”——但你怎么知道何时应该回退？随着对话变长，Claude 的上下文窗口逐渐填满，模型输出质量会无声地下降。你可能正从一个“半盲”的模型手中发布代码却浑然不觉。

仓库文档推荐通过cc-context-stats为 Claude Code 状态栏添加实时上下文分区（context zones）：从Plan（绿色，可安全规划与编码）→Code（黄色，避免开启新计划）→Dump（橙色，收尾并 rewind）。当你看到分区变化，就知道该 checkpoint 并开启新会话，而不是带着降级的输出硬撑。

总结

Checkpoints 是 Claude Code 的自动功能，让你能安全地探索不同方案而不必担心丢失工作。每条用户 prompt 都会自动创建新 checkpoint，因此你可以随时回退到会话中的任意先前时间点。

核心收益：

放心大胆地尝试多种方案
快速从失误中恢复
并排对比不同解决方案
与版本控制系统安全集成

请记住：checkpoints 不是 git 的替代品。用 checkpoints 做快速实验，用 git 固化最终的代码变更。

文档信息：本文基于仓库08-checkpoints模块整理。英文版文档最后更新于 2026 年 8 月，对应的 Claude Code 版本为 2.1.220；仓库主版本线已推进至 2.1.235（见 CHANGELOG.md），文中配置项与命令以实际安装版本为准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析