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-howtoCheckpoints检查点是 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方式一键盘快捷键连续按两次EscEscEsc即可打开 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.md2.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保存 → 重构 → 测试 → 若失败RewindA/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 去探索另一种方案... [用户按 EscEsc 回退到 checkpoint A] [在 checkpoint B 处实现 in-memory 缓存] User: 现在我可以对比两种方案了示例 2从失误中恢复User: 用 JWT 重构认证模块 Claude: 我来重构认证模块... [完成大规模修改] User: 等等这破坏了 OAuth 集成。我们回退吧。 Claude: 我来帮你 rewind 到重构之前... [用户按 EscEsc 选中重构前的 checkpoint] User: 这次换个更保守的方案示例 3安全实验User: 试试用函数式风格重写这部分 [实验前自动创建 checkpoint] Claude: [完成实验性修改] User: 测试挂了。回退吧。 [用户按 EscEsc 回退到 checkpoint] Claude: 我已回退这些修改试试其他方案吧。示例 4方案分支对比User: 我想对比两种数据库设计 [记下 checkpoint —— 命名为 Start] Claude: 我来做第一种设计... [实现 Schema A] User: 现在让我回去试第二种方案 [用户按 EscEsc 回退到 Start] Claude: 现在我来实现 Schema B... [实现 Schema B] User: 太棒了现在我有了两个 schema 可供选择更多真实场景08-checkpoints/checkpoint-examples.md 提供了 8 个贴近生产的完整示例包括数据库迁移MySQL 直迁方案 15 个测试失败后回退到 checkpoint A 改走双写dual-write渐进迁移全部测试通过后提交。性能优化从 Baseline checkpoint 出发依次尝试 Redis 缓存280ms、查询优化180ms、压缩 CDN320ms再回退到查询优化后的 checkpoint 叠加缓存最终拿到 79% 的响应时间改善。UI/UX 迭代以 Start 为分支点逐一尝试侧边栏、顶部导航、卡片网格最后把顶部导航与卡片网格组合成终稿。调试会话针对内存泄漏以 Before debugging 为锚点依次验证事件监听器、数据库连接、循环引用三个假设最终定位缓存层循环引用。API 设计演进RESTCRUD → 分页过滤 → HATEOAS与 GraphQL 两条路线反复横跳最终回到 HATEOAS 分支定稿。配置管理环境变量方案在生产部署失败后回退改用 YAML JSON Schema 校验并叠加 env var 覆盖敏感值。测试策略单元测试 → 集成测试 → 并行优化3 分钟压到 35 秒→ E2E 测试逐步叠加。使用“从这里总结”20 条消息的调试长会话后选中早期 checkpoint 执行 Summarize可附带指令如“聚焦于我们尝试过什么、什么有效”压缩可见对话以释放上下文窗口。Checkpoint 保留策略RetentionClaude Code 会自动管理你的 checkpoints每条用户 prompt 自动创建 checkpoint旧 checkpoint 最多保留30 天自动清理以防止存储无限增长只保留最近 100 个 checkpoint的快照即使仍在保留期内更旧的也会被丢弃v2.1.117 更新cleanupPeriodDays现在统一管理磁盘上四类缓存的保留期而不仅是 checkpoints会话 checkpointsSession 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 }设置默认值作用fileCheckpointingEnabledtrue在每次编辑前对文件拍照快照使/rewind可以恢复。要求 v2.1.119。在/config中显示为Rewind code (checkpoints)。等价环境变量CLAUDE_CODE_DISABLE_FILE_CHECKPOINTINGcleanupPeriodDays30会话历史与 checkpoints 的保留天数对应的环境变量方式# 通过环境变量禁用文件快照等价于 fileCheckpointingEnabled: false export CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING1局限性LimitationsCheckpoints 存在以下限制Bash 命令造成的变更不追踪——rm、mv、cp等文件系统操作不会记录进 checkpoints外部变更不追踪—— 在 Claude Code 之外编辑器、终端等做出的修改不会被记录不是版本控制的替代品—— 持久化、可审计的代码变更请使用 gitv2.1.216 更新/rewind不再通过被追踪路径上的符号链接symlink或硬链接hard link恢复或删除文件。若某个被追踪路径经由 symlink/hard link 解析rewind 会跳过它而不是跟随链接并报告因此跳过的路径数量。故障排查Troubleshooting找不到 Checkpoint问题找不到预期的 checkpoint解决方案检查 checkpoints 是否已被清除检查磁盘空间确认fileCheckpointingEnabled已在设置中开启确保cleanupPeriodDays设置得足够高默认 30 天Rewind 失败问题无法回退到某个 checkpoint解决方案确保没有冲突的未提交变更检查 checkpoint 是否损坏尝试回退到另一个 checkpoint与 Git 的集成Checkpoints 是 git 的补充但并非替代特性GitCheckpoints范围文件系统对话 文件持久性永久基于会话粒度Commits任意时间点速度较慢即时共享可以有限将两者结合使用用 checkpoints 进行快速实验用 git commits 固化最终变更在执行 git 操作前创建 checkpoint把成功的 checkpoint 状态提交到 git快速上手指南基础工作流正常工作—— Claude Code 自动创建 checkpoints想回退—— 按Esc两次或使用/rewind选择 checkpoint—— 从列表中选中要回退的目标选择恢复内容—— 从“恢复代码和对话 / 恢复对话 / 恢复代码 / 从这里总结 / 没关系”中挑选继续工作—— 你已经回到了那个时间点快捷键速查EscEsc—— 打开 checkpoint 浏览器/rewind—— 访问 checkpoints 的替代方式/checkpoint——/rewind的别名/undo——/rewind的另一别名v2.1.108 起何时该 Rewind上下文监控Context MonitoringCheckpoints 让你能“回到过去”——但你怎么知道何时应该回退随着对话变长Claude 的上下文窗口逐渐填满模型输出质量会无声地下降。你可能正从一个“半盲”的模型手中发布代码却浑然不觉。仓库文档推荐通过cc-context-stats为 Claude Code 状态栏添加实时上下文分区context zones从Plan绿色可安全规划与编码→Code黄色避免开启新计划→Dump橙色收尾并 rewind。当你看到分区变化就知道该 checkpoint 并开启新会话而不是带着降级的输出硬撑。相关概念与模块Checkpoints 并非孤立功能它与你正在学习的其他 Claude Code 能力紧密关联可在 claude-howto 仓库中按模块深入学习09-advanced-features —— 规划模式等高级能力02-memory —— 对话历史与上下文管理01-slash-commands —— 用户调用的快捷命令含/rewind相关命令说明06-hooks —— 基于事件驱动的自动化07-plugins —— 打包的扩展集合在仓库的模块化学习路径中checkpoints 被编号为08模块——06-hooks/session-end.sh 的 SessionEnd 钩子就把短编号08映射到08-checkpoints用于把每次学习会话的进度记录到~/.claude-howto-progress.json可见该模块在 10 大模块体系中的固定位置。完整功能目录参见 CATALOG.md。总结Checkpoints 是 Claude Code 的自动功能让你能安全地探索不同方案而不必担心丢失工作。每条用户 prompt 都会自动创建新 checkpoint因此你可以随时回退到会话中的任意先前时间点。核心收益放心大胆地尝试多种方案快速从失误中恢复并排对比不同解决方案与版本控制系统安全集成请记住checkpoints 不是 git 的替代品。用 checkpoints 做快速实验用 git 固化最终的代码变更。文档信息本文基于仓库08-checkpoints模块整理。英文版文档最后更新于 2026 年 8 月对应的 Claude Code 版本为 2.1.220仓库主版本线已推进至 2.1.235见 CHANGELOG.md文中配置项与命令以实际安装版本为准。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考