Claude How To 实战用 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在 Claude Code 中Checkpoints检查点是随每一次用户输入自动生成的会话状态快照它记录了全部消息、文件修改、工具调用历史与上下文让你可以随时回退Rewind到任意历史节点。本文以仓库中的 vi/08-checkpoints/checkpoint-examples.md 为核心骨架结合 08-checkpoints/README.md 的完整机制说明与仓库内配置样例通过 8 个真实场景的端到端演练带你掌握大胆实验、随时回退、对比择优的 Checkpoint 工作流并理解它与 git、上下文管理如何协同。Checkpoints 核心机制全自动的会话快照Checkpoints 允许你保存会话状态并回退到 Claude Code 会话中的先前节点。它不需要手动保存——每次用户 prompt 都会自动创建一个 checkpoint。按Esc两次EscEsc或使用/rewind即可打开 checkpoint 浏览器。每次快照捕获的内容包括所有已交换的消息All messages exchanged所做的文件修改File modifications made工具使用历史Tool usage history会话上下文Session context三个核心概念构成了理解整个机制的基础概念描述Checkpoint包含消息、文件与上下文的会话状态快照Rewind回退到之前的 checkpoint丢弃后续更改Branch Point分支点从该 checkpoint 出发探索多种方案的节点这些快照在会话之间持续存在Persistent默认保留 30 天后自动清理意味着你可以回退到几分钟前乃至数天前的任意节点。访问 Checkpoints 的三种方式仓库 CATALOG.md 中汇总了 checkpoints 相关的命令入口键盘快捷键连按两次EscEscEsc打开 checkpoint 浏览器浏览已保存的检查点。Slash 命令/rewind快速打开回退界面别名/checkpoint。/undo根据 CATALOG.md 的记载/undo是/rewind的别名v2.1.108 起reverts to the previous checkpoint即撤销到上一个 checkpoint可与/rewind互换使用。# 打开 rewind 界面 /rewind # 或使用别名 /checkpoint每个 checkpoint 会显示创建时间戳、被修改的文件、会话中的消息数量、使用过的工具。Rewind 的六个选项精确控制恢复范围当你执行 rewind 时会看到一个选项菜单08-checkpoints/README.md 中记载为六项Restore code and conversation恢复代码与会话—— 将文件和消息都回退到该 checkpoint。Restore conversation恢复会话—— 仅回退消息保持当前代码不变。Restore code恢复代码—— 仅回退文件更改保留完整会话历史。Summarize from here从此处汇总—— 将从该点往后的会话压缩为 AI 生成的摘要释放上下文窗口空间所选点之前的消息保持完整磁盘文件不变原始消息保留在会话 transcript 中你还可以提供指令如focus on what we tried and what worked让摘要聚焦特定主题。Summarize up to here汇总到此为止—— 与上一项方向相反将所选点之前的所有内容压缩为摘要保留该点之后的消息。它与 Summarize from here 共同构成双向、定向的上下文窗口压缩能力同样不改动磁盘文件原始消息保留在 transcript 中。Never mind算了—— 取消并返回当前状态。两个值得注意的细节恢复会话或汇总后所选消息的原始 prompt 会被恢复进输入框方便你重新发送或编辑而从 v2.1.191 起/clear不再是一道硬边界——/rewind可以恢复到执行/clear之前的 checkpoint清除会话不再永久丢弃其前置状态。配置与保留策略Checkpoints 是 Claude Code 的内置默认行为无需额外配置即可启用。两个设置控制其行为——是否拍照快照以及保留多久{ fileCheckpointingEnabled: true, cleanupPeriodDays: 30 }设置项默认值作用fileCheckpointingEnabledtrue在每次编辑前对文件拍照使/rewind可以恢复。要求 v2.1.119。在/config中显示为Rewind code (checkpoints)。环境变量等价形式CLAUDE_CODE_DISABLE_FILE_CHECKPOINTINGcleanupPeriodDays30会话历史与 checkpoints 的保留天数Claude Code 会保留最近 100 个 checkpoint的快照更旧的快照即使在保留窗口内也会被丢弃。仓库的 09-advanced-features/config-examples.json 展示了fileCheckpointingEnabled在真实场景配置中的用法。例如Learning Modeprompt before every action, checkpoint often显式开启了文件快照{ model: claude-sonnet-5, permissions: { defaultMode: manual }, fileCheckpointingEnabled: true }类似的配置还出现在production、performance_optimization、refactoring等场景中——凡是涉及大型改动或高风险操作都会显式确保文件快照开启为 rewind 提供恢复基础。另外根据 08-checkpoints/README.md 的 v2.1.117 更新记录cleanupPeriodDays现在统一治理四个磁盘缓存的保留期而不仅是 checkpoints——包括会话 checkpoints、~/.claude/tasks/持久任务列表、~/.claude/shell-snapshots/shell 环境快照和~/.claude/backups/设置 / CLAUDE.md 滚动备份。单个设置会在相同天数后统一清理这四个目录。八大实战场景Checkpoint 工作流完整演练以下全部场景取自 vi/08-checkpoints/checkpoint-examples.md展示了 Checkpoints 在真实开发任务中的典型用法。请注意其中标出的[Checkpoint ... created automatically]都无需手动保存。例 1数据库迁移——直迁方案失败后回退改走双写场景需要从 MySQL 迁移到 PostgreSQL但希望同时探索直接迁移与渐进式双写dual-write两种方案。工作流User: Lets implement a direct migration from MySQL to PostgreSQL [Checkpoint A created automatically] Claude: Ill implement the direct migration... [Changes database driver, updates queries, modifies schema] User: Run the tests [Checkpoint B created automatically] Claude: Running tests... ❌ 15 tests failing - connection pool issues User: This approach has issues. Lets try the dual-write pattern instead. [User presses EscEsc, selects Checkpoint A, chooses Restore code and conversation] User: Now implement a dual-write pattern where we write to both databases Claude: Ill implement dual-write migration... [Implements dual-write layer, gradual migration strategy] User: Run the tests Claude: Running tests... ✅ All tests passing User: The dual-write approach is clearly safer. Lets commit this.这个场景揭示了 Checkpoints 的核心价值回退不需要重新来过。当直迁方案在测试阶段暴露 15 个失败用例连接池问题时直接回退到 Checkpoint A迁移开始前代码和对话一并还原然后在干净的基础上切换到双写方案。对比之后安全且通过全部测试的双写方案被提交。例 2性能优化——三条路线对比后叠加出最优解场景API 响应时间优化基线 450ms需要尝试多种优化策略。工作流User: Lets optimize the API response time. Current: 450ms [Checkpoint Baseline created automatically] Claude: Ill add database query caching... [Implements Redis caching] User: Run performance tests Claude: Results: 280ms average response time (38% improvement) User: Let me try a different approach. [User presses EscEsc, selects Baseline checkpoint, chooses Restore code and conversation] User: Try database query optimization instead Claude: Ill optimize database queries... [Adds indexes, optimizes N1 queries] User: Run performance tests Claude: Results: 180ms average response time (60% improvement) User: Let me also try a third approach. [User presses EscEsc, selects Baseline checkpoint, chooses Restore code and conversation] User: Try response compression and CDN Claude: Ill add compression and CDN... [Implements gzip, sets up CDN] User: Run performance tests Claude: Results: 320ms average response time (29% improvement) User: Query optimization was the best. Let me go back and combine it with caching. [User presses EscEsc, selects the checkpoint after query optimization, chooses Restore code and conversation] User: Now add Redis caching on top of these optimized queries Claude: [Adds Redis caching on top of optimized queries] User: Run performance tests Claude: Results: 95ms average response time (79% improvement) User: Perfect! This is the winner. Lets commit this.这是一个教科书级的分支探索案例Redis 缓存38%→ 回退 → 查询优化60%→ 回退 → 压缩 CDN29%。更重要的是最后一步——回退到查询优化完成的 checkpoint而非 Baseline在最优单方案之上叠加缓存最终取得 79% 的改进。Checkpoints 不仅支持从头对比还支持从任意历史节点继续叠加优化。例 3UI/UX 迭代——多布局方案与组合设计场景为 dashboard 尝试不同布局。工作流User: Lets redesign the dashboard with a sidebar layout [Checkpoint Start created automatically] Claude: [Implements sidebar layout] User: Show me a screenshot Claude: [Shows screenshot] User: The sidebar feels cramped. Lets try a top navigation instead. [User presses EscEsc, selects Start checkpoint, chooses Restore code and conversation] User: Try a top navigation layout Claude: [Implements top navigation] User: Show me a screenshot Claude: [Shows screenshot] User: Better, but lets try a card-based grid layout [User presses EscEsc, selects Start checkpoint, chooses Restore code and conversation] User: Try a card-based grid layout Claude: [Implements card grid] User: Show me a screenshot Claude: [Shows screenshot] User: This is great! But can we combine the top nav with the card grid? [User presses EscEsc, selects the checkpoint after the card grid, chooses Restore code and conversation] User: Add top navigation to the card grid layout Claude: [Adds top navigation to card grid] User: Perfect! This is the final design.UI 迭代的典型节奏是截图 → 评估 → 回退 → 换方案。每次回退都回到 Start checkpoint保证三种布局从同一基线出发、互不污染。最终组合方案card grid top nav同样是从card grid 完成的中间 checkpoint 继续而非重新实现。例 4调试会话——多假设排查内存泄漏场景应用存在内存泄漏需要逐一验证多个假设。工作流User: Theres a memory leak in the application [Checkpoint Before debugging created automatically] Claude: Let me investigate... [Analyzes code] User: I think its in the event listeners. Lets fix those. Claude: [Fixes event listener cleanup] User: Run memory profiler Claude: Still leaking memory - event listeners werent the issue User: Let me go back and try a different hypothesis. [User presses EscEsc, selects Before debugging checkpoint, chooses Restore code and conversation] User: Maybe its the database connections? Claude: [Implements connection pooling fixes] User: Run memory profiler Claude: Still leaking - not the connections either User: Let me go back and try another angle. [User presses EscEsc, selects Before debugging checkpoint, chooses Restore code and conversation] User: Lets check for circular references Claude: [Finds and fixes circular references in cache] User: Run memory profiler Claude: ✅ Memory leak fixed! The circular references in the caching layer were the culprit. User: Excellent! Lets commit this fix.调试是最能体现 Rewind 价值的使用场景之一。三个假设事件监听器、数据库连接、循环引用从同一个 Before debugging checkpoint 出发前两个被证明无效后一键回退不会把失败修复的残留代码混入下一轮排查最终精确定位到缓存层的循环引用。例 5API 设计演进——REST 与 GraphQL 的技术选型场景为博客平台设计 API经历多轮迭代与技术路线切换。工作流User: Create a REST API for our blog platform [Checkpoint Before API design created automatically] Claude: [Creates basic CRUD API] User: This is too simple. Lets add pagination and filtering Claude: [Adds pagination and filtering] User: We need better resource relationships Claude: [Implements HATEOAS links] User: Actually, lets try GraphQL instead of REST [User presses EscEsc, selects Before API design checkpoint, chooses Restore code and conversation] User: Implement a GraphQL API for our blog platform instead Claude: [Implements GraphQL API] User: I think REST is better for our use case. [User presses EscEsc, selects the checkpoint after HATEOAS, chooses Restore code and conversation] User: Lets finalize the REST approach.此例展示了 Checkpoints 在架构级技术选型中的应用REST 方案演进到 HATEOAS 后用户临时决定试 GraphQL回退到 Before API design 重新实现当发现 REST 更贴合需求时再回退到HATEOAS 完成后的那个 checkpoint而非从头开始无缝接回之前的所有 REST 工作。两套设计完整保留随时可对照。例 6配置管理——env vars 与 YAML 校验方案的对比与融合场景测试不同的配置管理方案。工作流User: Move configuration to environment variables [Checkpoint Original config created automatically] Claude: [Implements env var configuration] User: Test in development Claude: Works locally but deployment issues in production User: Let me try a different approach. [User presses EscEsc, selects Original config checkpoint, chooses Restore code and conversation] User: Try a config file approach with validation Claude: [Implements YAML config with JSON schema validation] User: Test in development Claude: ✅ Works well, good validation errors User: Can we also support env vars for sensitive values? Claude: [Adds env var override for secrets] User: Test deployment Claude: ✅ All environments working correctly User: Perfect! This is production-ready.当第一种方案纯环境变量在生产部署暴露问题后回退到 Original config 检查点改走YAML JSON Schema 校验路线随后又在其基础上叠加环境变量以覆盖敏感值secrets。最终方案是两种思路的融合产物——这正是分支探索后择优叠加的典型形态。例 7测试策略——覆盖率的渐进式构建与提速场景为项目构建全面的测试体系。工作流User: Add unit tests for the auth module [Checkpoint created automatically] Claude: [Adds Jest unit tests] User: Run tests Claude: 45 tests passing, 78% coverage User: Add integration tests too Claude: [Adds integration tests] User: Run tests Claude: 89 tests passing, 92% coverage, but tests are slow (3 minutes) User: The tests are too slow. Lets optimize. Claude: [Optimizes test setup, adds parallel execution] User: Run tests Claude: 89 tests passing, 92% coverage, 35 seconds ✅ User: Great! Now add E2E tests for critical paths Claude: [Adds Playwright E2E tests] User: Run all tests Claude: 112 tests passing, 94% coverage, 2 minutes User: Perfect balance of coverage and speed!此例不需要回退展示的是 Checkpoints 在增量演进中的保障作用单元测试45 个 / 78%→ 集成测试89 个 / 92%→ 并行化提速35 秒→ E2E 测试112 个 / 94%。每一步都自动生成 checkpoint任何一步出现意外都可以回退到上一步的稳定测试基线。例 8从 Checkpoint 使用 Summarize——压缩长会话释放上下文场景一段 20 条消息的调试探索之后希望压缩对话同时保留上下文。工作流User: [After 20 messages of debugging and exploration] [User presses EscEsc, selects an early checkpoint, chooses Summarize from here] [Optionally provides instructions: Focus on what we tried and what worked] Claude: [Generates a summary of the conversation from that point forward] [Original messages are preserved in the transcript] [The summary replaces the visible conversation, reducing context window usage] User: Now lets continue with the approach that worked.这是唯一不需要回退代码的用法长调试会话会迅速占满上下文窗口、降低模型质量。选择早期 checkpoint 并执行Summarize from hereAI 会从该点往后生成摘要替代可见对话原始消息仍保存在 transcript 中你还可以附带指令让摘要聚焦尝试过什么、什么有效。压缩后可以继续顺着有效路线推进而不是被迫硬撑或从头开始。从示例提炼可复用的 Workflow Patterns08-checkpoints/README.md 将上述示例背后的通用模式归纳为四种使用场景与两种流程模板场景工作流探索多种方案Exploring ApproachesSave → Try A → Save → Rewind → Try B → Compare安全重构Safe RefactoringSave → Refactor → Test → If fail: RewindA/B 测试A/B TestingSave → Design A → Save → Rewind → Design B → Compare错误恢复Mistake RecoveryNotice issue → Rewind to last good state分支探索策略例 2、例 5 的抽象1. Start with initial implementation → Checkpoint A 2. Try Approach 1 → Checkpoint B 3. Rewind to Checkpoint A 4. Try Approach 2 → Checkpoint C 5. Compare results from B and C 6. Choose best approach and continue安全重构模式例 1、例 6 的抽象1. Current state → Checkpoint (auto) 2. Start refactoring 3. Run tests 4. If tests pass → Continue working 5. If tests fail → Rewind and try different approach与 git 的协同分工明确而非互相替代Checkpoints 补充但不替代 git。08-checkpoints/README.md 给出了二者的对比特性GitCheckpoints作用范围文件系统会话 文件持久性永久基于会话粒度Commits任意节点速度较慢即时共享可以有限两者配合使用的最佳实践用 checkpoints 做快速实验与探索用 git commits 固化定稿的代码变更在 git 操作前创建 checkpoint将成功的 checkpoint 状态提交到 git。四个实战示例也遵循这一原则探索、对比、试错全部在 checkpoint 内完成一旦确定方案立即 commit——例 1、例 2、例 4、例 6 都以Lets commit this收尾。注意事项与限制Checkpoints 并非万能以下限制需要牢记08-checkpoints/README.mdBash 命令更改不被追踪文件系统上的rm、mv、cp等操作不会记录进 checkpoints。外部更改不被追踪在 Claude Code 之外编辑器、终端等的修改不会被捕获。不能替代版本控制codebase 的永久性、可审计变更应使用 git。从 v2.1.216 起/rewind不会通过符号链接或硬链接恢复/删除受追踪路径下的文件若某路径经由 symlink/hardlink 解析rewind 会跳过它并报告跳过的路径数量。最佳实践Do 与 Dont✅应当Rewind 之前先浏览可用的 checkpoints确认目标节点想探索不同方向时果断使用 rewind保留 checkpoints 以便对比不同方案理解每个 rewind 选项的确切含义恢复代码与会话 / 恢复会话 / 恢复代码 / 汇总。❌不应仅依赖 checkpoints 来保全代码期待 checkpoints 追踪外部文件系统变更用 checkpoints 替代 git commits。故障排查Checkpoint 缺失找不到预期 checkpoint 时——检查是否已被清理、检查磁盘空间、确认cleanupPeriodDays是否足够高默认 30 天。Rewind 失败无法回退到某 checkpoint 时——确保没有冲突的未提交更改、检查 checkpoint 是否损坏、尝试回退到其他 checkpoint。何时该 Rewind上下文窗口监控Checkpoints 解决能不能回去的问题但何时该回去同样关键。随着会话增长Claude 的上下文窗口会被填满模型质量会悄然下降。仓库 README 介绍了一种思路通过为 Claude Code 状态栏添加实时**上下文区域context zones**指示追踪你在窗口中的位置——从 Plan绿色可安全规划与编码、经 Code黄色避免开启新计划到 Dump橙色收尾并 rewind。当区域切换时就是 checkpoint 与重新开始的最佳时机而不是顶着退化输出硬推。这可以与本仓库的 06-hooks/README.md基于事件的自动化与 02-memory/README.md会话历史与上下文管理结合使用。关键要点总结Checkpoints 是自动的每次用户 prompt 都会创建 checkpoint无需手动保存。两种入口EscEsc与/rewind别名/checkpoint、/undo是打开 checkpoint 浏览器的途径。选择合适的恢复选项按需选择恢复代码、恢复会话、两者都恢复或汇总Summarize from here / up to here。不要畏惧实验Checkpoints 让激进的变更尝试变得安全。与 git 配合探索用 checkpoints定稿用 git。长会话及时汇总用 Summarize from here 让对话保持可控。快速入口可参考 QUICK_REFERENCE.md其中将08-checkpoints/checkpoint-examples.md列为安全实验场景的首选资料完整命令清单见 CATALOG.md。Checkpoints 相关的进阶能力规划模式、扩展思考、权限模式等可继续阅读 09-advanced-features/README.md配套的完整 settings.json 场景化配置示例见 09-advanced-features/config-examples.json。【免费下载链接】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），仅供参考
Claude How To 实战：用 Claude Code Checkpoints 自动快照与 Rewind 机制驾驭多方案并行探索
Claude How To 实战用 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在 Claude Code 中Checkpoints检查点是随每一次用户输入自动生成的会话状态快照它记录了全部消息、文件修改、工具调用历史与上下文让你可以随时回退Rewind到任意历史节点。本文以仓库中的 vi/08-checkpoints/checkpoint-examples.md 为核心骨架结合 08-checkpoints/README.md 的完整机制说明与仓库内配置样例通过 8 个真实场景的端到端演练带你掌握大胆实验、随时回退、对比择优的 Checkpoint 工作流并理解它与 git、上下文管理如何协同。Checkpoints 核心机制全自动的会话快照Checkpoints 允许你保存会话状态并回退到 Claude Code 会话中的先前节点。它不需要手动保存——每次用户 prompt 都会自动创建一个 checkpoint。按Esc两次EscEsc或使用/rewind即可打开 checkpoint 浏览器。每次快照捕获的内容包括所有已交换的消息All messages exchanged所做的文件修改File modifications made工具使用历史Tool usage history会话上下文Session context三个核心概念构成了理解整个机制的基础概念描述Checkpoint包含消息、文件与上下文的会话状态快照Rewind回退到之前的 checkpoint丢弃后续更改Branch Point分支点从该 checkpoint 出发探索多种方案的节点这些快照在会话之间持续存在Persistent默认保留 30 天后自动清理意味着你可以回退到几分钟前乃至数天前的任意节点。访问 Checkpoints 的三种方式仓库 CATALOG.md 中汇总了 checkpoints 相关的命令入口键盘快捷键连按两次EscEscEsc打开 checkpoint 浏览器浏览已保存的检查点。Slash 命令/rewind快速打开回退界面别名/checkpoint。/undo根据 CATALOG.md 的记载/undo是/rewind的别名v2.1.108 起reverts to the previous checkpoint即撤销到上一个 checkpoint可与/rewind互换使用。# 打开 rewind 界面 /rewind # 或使用别名 /checkpoint每个 checkpoint 会显示创建时间戳、被修改的文件、会话中的消息数量、使用过的工具。Rewind 的六个选项精确控制恢复范围当你执行 rewind 时会看到一个选项菜单08-checkpoints/README.md 中记载为六项Restore code and conversation恢复代码与会话—— 将文件和消息都回退到该 checkpoint。Restore conversation恢复会话—— 仅回退消息保持当前代码不变。Restore code恢复代码—— 仅回退文件更改保留完整会话历史。Summarize from here从此处汇总—— 将从该点往后的会话压缩为 AI 生成的摘要释放上下文窗口空间所选点之前的消息保持完整磁盘文件不变原始消息保留在会话 transcript 中你还可以提供指令如focus on what we tried and what worked让摘要聚焦特定主题。Summarize up to here汇总到此为止—— 与上一项方向相反将所选点之前的所有内容压缩为摘要保留该点之后的消息。它与 Summarize from here 共同构成双向、定向的上下文窗口压缩能力同样不改动磁盘文件原始消息保留在 transcript 中。Never mind算了—— 取消并返回当前状态。两个值得注意的细节恢复会话或汇总后所选消息的原始 prompt 会被恢复进输入框方便你重新发送或编辑而从 v2.1.191 起/clear不再是一道硬边界——/rewind可以恢复到执行/clear之前的 checkpoint清除会话不再永久丢弃其前置状态。配置与保留策略Checkpoints 是 Claude Code 的内置默认行为无需额外配置即可启用。两个设置控制其行为——是否拍照快照以及保留多久{ fileCheckpointingEnabled: true, cleanupPeriodDays: 30 }设置项默认值作用fileCheckpointingEnabledtrue在每次编辑前对文件拍照使/rewind可以恢复。要求 v2.1.119。在/config中显示为Rewind code (checkpoints)。环境变量等价形式CLAUDE_CODE_DISABLE_FILE_CHECKPOINTINGcleanupPeriodDays30会话历史与 checkpoints 的保留天数Claude Code 会保留最近 100 个 checkpoint的快照更旧的快照即使在保留窗口内也会被丢弃。仓库的 09-advanced-features/config-examples.json 展示了fileCheckpointingEnabled在真实场景配置中的用法。例如Learning Modeprompt before every action, checkpoint often显式开启了文件快照{ model: claude-sonnet-5, permissions: { defaultMode: manual }, fileCheckpointingEnabled: true }类似的配置还出现在production、performance_optimization、refactoring等场景中——凡是涉及大型改动或高风险操作都会显式确保文件快照开启为 rewind 提供恢复基础。另外根据 08-checkpoints/README.md 的 v2.1.117 更新记录cleanupPeriodDays现在统一治理四个磁盘缓存的保留期而不仅是 checkpoints——包括会话 checkpoints、~/.claude/tasks/持久任务列表、~/.claude/shell-snapshots/shell 环境快照和~/.claude/backups/设置 / CLAUDE.md 滚动备份。单个设置会在相同天数后统一清理这四个目录。八大实战场景Checkpoint 工作流完整演练以下全部场景取自 vi/08-checkpoints/checkpoint-examples.md展示了 Checkpoints 在真实开发任务中的典型用法。请注意其中标出的[Checkpoint ... created automatically]都无需手动保存。例 1数据库迁移——直迁方案失败后回退改走双写场景需要从 MySQL 迁移到 PostgreSQL但希望同时探索直接迁移与渐进式双写dual-write两种方案。工作流User: Lets implement a direct migration from MySQL to PostgreSQL [Checkpoint A created automatically] Claude: Ill implement the direct migration... [Changes database driver, updates queries, modifies schema] User: Run the tests [Checkpoint B created automatically] Claude: Running tests... ❌ 15 tests failing - connection pool issues User: This approach has issues. Lets try the dual-write pattern instead. [User presses EscEsc, selects Checkpoint A, chooses Restore code and conversation] User: Now implement a dual-write pattern where we write to both databases Claude: Ill implement dual-write migration... [Implements dual-write layer, gradual migration strategy] User: Run the tests Claude: Running tests... ✅ All tests passing User: The dual-write approach is clearly safer. Lets commit this.这个场景揭示了 Checkpoints 的核心价值回退不需要重新来过。当直迁方案在测试阶段暴露 15 个失败用例连接池问题时直接回退到 Checkpoint A迁移开始前代码和对话一并还原然后在干净的基础上切换到双写方案。对比之后安全且通过全部测试的双写方案被提交。例 2性能优化——三条路线对比后叠加出最优解场景API 响应时间优化基线 450ms需要尝试多种优化策略。工作流User: Lets optimize the API response time. Current: 450ms [Checkpoint Baseline created automatically] Claude: Ill add database query caching... [Implements Redis caching] User: Run performance tests Claude: Results: 280ms average response time (38% improvement) User: Let me try a different approach. [User presses EscEsc, selects Baseline checkpoint, chooses Restore code and conversation] User: Try database query optimization instead Claude: Ill optimize database queries... [Adds indexes, optimizes N1 queries] User: Run performance tests Claude: Results: 180ms average response time (60% improvement) User: Let me also try a third approach. [User presses EscEsc, selects Baseline checkpoint, chooses Restore code and conversation] User: Try response compression and CDN Claude: Ill add compression and CDN... [Implements gzip, sets up CDN] User: Run performance tests Claude: Results: 320ms average response time (29% improvement) User: Query optimization was the best. Let me go back and combine it with caching. [User presses EscEsc, selects the checkpoint after query optimization, chooses Restore code and conversation] User: Now add Redis caching on top of these optimized queries Claude: [Adds Redis caching on top of optimized queries] User: Run performance tests Claude: Results: 95ms average response time (79% improvement) User: Perfect! This is the winner. Lets commit this.这是一个教科书级的分支探索案例Redis 缓存38%→ 回退 → 查询优化60%→ 回退 → 压缩 CDN29%。更重要的是最后一步——回退到查询优化完成的 checkpoint而非 Baseline在最优单方案之上叠加缓存最终取得 79% 的改进。Checkpoints 不仅支持从头对比还支持从任意历史节点继续叠加优化。例 3UI/UX 迭代——多布局方案与组合设计场景为 dashboard 尝试不同布局。工作流User: Lets redesign the dashboard with a sidebar layout [Checkpoint Start created automatically] Claude: [Implements sidebar layout] User: Show me a screenshot Claude: [Shows screenshot] User: The sidebar feels cramped. Lets try a top navigation instead. [User presses EscEsc, selects Start checkpoint, chooses Restore code and conversation] User: Try a top navigation layout Claude: [Implements top navigation] User: Show me a screenshot Claude: [Shows screenshot] User: Better, but lets try a card-based grid layout [User presses EscEsc, selects Start checkpoint, chooses Restore code and conversation] User: Try a card-based grid layout Claude: [Implements card grid] User: Show me a screenshot Claude: [Shows screenshot] User: This is great! But can we combine the top nav with the card grid? [User presses EscEsc, selects the checkpoint after the card grid, chooses Restore code and conversation] User: Add top navigation to the card grid layout Claude: [Adds top navigation to card grid] User: Perfect! This is the final design.UI 迭代的典型节奏是截图 → 评估 → 回退 → 换方案。每次回退都回到 Start checkpoint保证三种布局从同一基线出发、互不污染。最终组合方案card grid top nav同样是从card grid 完成的中间 checkpoint 继续而非重新实现。例 4调试会话——多假设排查内存泄漏场景应用存在内存泄漏需要逐一验证多个假设。工作流User: Theres a memory leak in the application [Checkpoint Before debugging created automatically] Claude: Let me investigate... [Analyzes code] User: I think its in the event listeners. Lets fix those. Claude: [Fixes event listener cleanup] User: Run memory profiler Claude: Still leaking memory - event listeners werent the issue User: Let me go back and try a different hypothesis. [User presses EscEsc, selects Before debugging checkpoint, chooses Restore code and conversation] User: Maybe its the database connections? Claude: [Implements connection pooling fixes] User: Run memory profiler Claude: Still leaking - not the connections either User: Let me go back and try another angle. [User presses EscEsc, selects Before debugging checkpoint, chooses Restore code and conversation] User: Lets check for circular references Claude: [Finds and fixes circular references in cache] User: Run memory profiler Claude: ✅ Memory leak fixed! The circular references in the caching layer were the culprit. User: Excellent! Lets commit this fix.调试是最能体现 Rewind 价值的使用场景之一。三个假设事件监听器、数据库连接、循环引用从同一个 Before debugging checkpoint 出发前两个被证明无效后一键回退不会把失败修复的残留代码混入下一轮排查最终精确定位到缓存层的循环引用。例 5API 设计演进——REST 与 GraphQL 的技术选型场景为博客平台设计 API经历多轮迭代与技术路线切换。工作流User: Create a REST API for our blog platform [Checkpoint Before API design created automatically] Claude: [Creates basic CRUD API] User: This is too simple. Lets add pagination and filtering Claude: [Adds pagination and filtering] User: We need better resource relationships Claude: [Implements HATEOAS links] User: Actually, lets try GraphQL instead of REST [User presses EscEsc, selects Before API design checkpoint, chooses Restore code and conversation] User: Implement a GraphQL API for our blog platform instead Claude: [Implements GraphQL API] User: I think REST is better for our use case. [User presses EscEsc, selects the checkpoint after HATEOAS, chooses Restore code and conversation] User: Lets finalize the REST approach.此例展示了 Checkpoints 在架构级技术选型中的应用REST 方案演进到 HATEOAS 后用户临时决定试 GraphQL回退到 Before API design 重新实现当发现 REST 更贴合需求时再回退到HATEOAS 完成后的那个 checkpoint而非从头开始无缝接回之前的所有 REST 工作。两套设计完整保留随时可对照。例 6配置管理——env vars 与 YAML 校验方案的对比与融合场景测试不同的配置管理方案。工作流User: Move configuration to environment variables [Checkpoint Original config created automatically] Claude: [Implements env var configuration] User: Test in development Claude: Works locally but deployment issues in production User: Let me try a different approach. [User presses EscEsc, selects Original config checkpoint, chooses Restore code and conversation] User: Try a config file approach with validation Claude: [Implements YAML config with JSON schema validation] User: Test in development Claude: ✅ Works well, good validation errors User: Can we also support env vars for sensitive values? Claude: [Adds env var override for secrets] User: Test deployment Claude: ✅ All environments working correctly User: Perfect! This is production-ready.当第一种方案纯环境变量在生产部署暴露问题后回退到 Original config 检查点改走YAML JSON Schema 校验路线随后又在其基础上叠加环境变量以覆盖敏感值secrets。最终方案是两种思路的融合产物——这正是分支探索后择优叠加的典型形态。例 7测试策略——覆盖率的渐进式构建与提速场景为项目构建全面的测试体系。工作流User: Add unit tests for the auth module [Checkpoint created automatically] Claude: [Adds Jest unit tests] User: Run tests Claude: 45 tests passing, 78% coverage User: Add integration tests too Claude: [Adds integration tests] User: Run tests Claude: 89 tests passing, 92% coverage, but tests are slow (3 minutes) User: The tests are too slow. Lets optimize. Claude: [Optimizes test setup, adds parallel execution] User: Run tests Claude: 89 tests passing, 92% coverage, 35 seconds ✅ User: Great! Now add E2E tests for critical paths Claude: [Adds Playwright E2E tests] User: Run all tests Claude: 112 tests passing, 94% coverage, 2 minutes User: Perfect balance of coverage and speed!此例不需要回退展示的是 Checkpoints 在增量演进中的保障作用单元测试45 个 / 78%→ 集成测试89 个 / 92%→ 并行化提速35 秒→ E2E 测试112 个 / 94%。每一步都自动生成 checkpoint任何一步出现意外都可以回退到上一步的稳定测试基线。例 8从 Checkpoint 使用 Summarize——压缩长会话释放上下文场景一段 20 条消息的调试探索之后希望压缩对话同时保留上下文。工作流User: [After 20 messages of debugging and exploration] [User presses EscEsc, selects an early checkpoint, chooses Summarize from here] [Optionally provides instructions: Focus on what we tried and what worked] Claude: [Generates a summary of the conversation from that point forward] [Original messages are preserved in the transcript] [The summary replaces the visible conversation, reducing context window usage] User: Now lets continue with the approach that worked.这是唯一不需要回退代码的用法长调试会话会迅速占满上下文窗口、降低模型质量。选择早期 checkpoint 并执行Summarize from hereAI 会从该点往后生成摘要替代可见对话原始消息仍保存在 transcript 中你还可以附带指令让摘要聚焦尝试过什么、什么有效。压缩后可以继续顺着有效路线推进而不是被迫硬撑或从头开始。从示例提炼可复用的 Workflow Patterns08-checkpoints/README.md 将上述示例背后的通用模式归纳为四种使用场景与两种流程模板场景工作流探索多种方案Exploring ApproachesSave → Try A → Save → Rewind → Try B → Compare安全重构Safe RefactoringSave → Refactor → Test → If fail: RewindA/B 测试A/B TestingSave → Design A → Save → Rewind → Design B → Compare错误恢复Mistake RecoveryNotice issue → Rewind to last good state分支探索策略例 2、例 5 的抽象1. Start with initial implementation → Checkpoint A 2. Try Approach 1 → Checkpoint B 3. Rewind to Checkpoint A 4. Try Approach 2 → Checkpoint C 5. Compare results from B and C 6. Choose best approach and continue安全重构模式例 1、例 6 的抽象1. Current state → Checkpoint (auto) 2. Start refactoring 3. Run tests 4. If tests pass → Continue working 5. If tests fail → Rewind and try different approach与 git 的协同分工明确而非互相替代Checkpoints 补充但不替代 git。08-checkpoints/README.md 给出了二者的对比特性GitCheckpoints作用范围文件系统会话 文件持久性永久基于会话粒度Commits任意节点速度较慢即时共享可以有限两者配合使用的最佳实践用 checkpoints 做快速实验与探索用 git commits 固化定稿的代码变更在 git 操作前创建 checkpoint将成功的 checkpoint 状态提交到 git。四个实战示例也遵循这一原则探索、对比、试错全部在 checkpoint 内完成一旦确定方案立即 commit——例 1、例 2、例 4、例 6 都以Lets commit this收尾。注意事项与限制Checkpoints 并非万能以下限制需要牢记08-checkpoints/README.mdBash 命令更改不被追踪文件系统上的rm、mv、cp等操作不会记录进 checkpoints。外部更改不被追踪在 Claude Code 之外编辑器、终端等的修改不会被捕获。不能替代版本控制codebase 的永久性、可审计变更应使用 git。从 v2.1.216 起/rewind不会通过符号链接或硬链接恢复/删除受追踪路径下的文件若某路径经由 symlink/hardlink 解析rewind 会跳过它并报告跳过的路径数量。最佳实践Do 与 Dont✅应当Rewind 之前先浏览可用的 checkpoints确认目标节点想探索不同方向时果断使用 rewind保留 checkpoints 以便对比不同方案理解每个 rewind 选项的确切含义恢复代码与会话 / 恢复会话 / 恢复代码 / 汇总。❌不应仅依赖 checkpoints 来保全代码期待 checkpoints 追踪外部文件系统变更用 checkpoints 替代 git commits。故障排查Checkpoint 缺失找不到预期 checkpoint 时——检查是否已被清理、检查磁盘空间、确认cleanupPeriodDays是否足够高默认 30 天。Rewind 失败无法回退到某 checkpoint 时——确保没有冲突的未提交更改、检查 checkpoint 是否损坏、尝试回退到其他 checkpoint。何时该 Rewind上下文窗口监控Checkpoints 解决能不能回去的问题但何时该回去同样关键。随着会话增长Claude 的上下文窗口会被填满模型质量会悄然下降。仓库 README 介绍了一种思路通过为 Claude Code 状态栏添加实时**上下文区域context zones**指示追踪你在窗口中的位置——从 Plan绿色可安全规划与编码、经 Code黄色避免开启新计划到 Dump橙色收尾并 rewind。当区域切换时就是 checkpoint 与重新开始的最佳时机而不是顶着退化输出硬推。这可以与本仓库的 06-hooks/README.md基于事件的自动化与 02-memory/README.md会话历史与上下文管理结合使用。关键要点总结Checkpoints 是自动的每次用户 prompt 都会创建 checkpoint无需手动保存。两种入口EscEsc与/rewind别名/checkpoint、/undo是打开 checkpoint 浏览器的途径。选择合适的恢复选项按需选择恢复代码、恢复会话、两者都恢复或汇总Summarize from here / up to here。不要畏惧实验Checkpoints 让激进的变更尝试变得安全。与 git 配合探索用 checkpoints定稿用 git。长会话及时汇总用 Summarize from here 让对话保持可控。快速入口可参考 QUICK_REFERENCE.md其中将08-checkpoints/checkpoint-examples.md列为安全实验场景的首选资料完整命令清单见 CATALOG.md。Checkpoints 相关的进阶能力规划模式、扩展思考、权限模式等可继续阅读 09-advanced-features/README.md配套的完整 settings.json 场景化配置示例见 09-advanced-features/config-examples.json。【免费下载链接】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），仅供参考
