企业官网建设流程全解析

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两次（Esc+Esc）或使用/rewind即可打开 checkpoint 浏览器。

每次快照捕获的内容包括：

• 所有已交换的消息（All messages exchanged）
• 所做的文件修改（File modifications made）
• 工具使用历史（Tool usage history）
• 会话上下文（Session context）

三个核心概念构成了理解整个机制的基础：

这些快照在会话之间持续存在（Persistent），默认保留 30 天后自动清理，意味着你可以回退到几分钟前乃至数天前的任意节点。

访问 Checkpoints 的三种方式

仓库 CATALOG.md 中汇总了 checkpoints 相关的命令入口：

1. 键盘快捷键：连按两次Esc（Esc+Esc）打开 checkpoint 浏览器，浏览已保存的检查点。
2. Slash 命令/rewind：快速打开回退界面，别名/checkpoint。
3. /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 中记载为六项）：

1. Restore code and conversation（恢复代码与会话）—— 将文件和消息都回退到该 checkpoint。
2. Restore conversation（恢复会话）—— 仅回退消息，保持当前代码不变。
3. Restore code（恢复代码）—— 仅回退文件更改，保留完整会话历史。
4. Summarize from here（从此处汇总）—— 将从该点往后的会话压缩为 AI 生成的摘要，释放上下文窗口空间；所选点之前的消息保持完整，磁盘文件不变，原始消息保留在会话 transcript 中；你还可以提供指令（如"focus on what we tried and what worked"）让摘要聚焦特定主题。
5. Summarize up to here（汇总到此为止）—— 与上一项方向相反：将所选点之前的所有内容压缩为摘要，保留该点之后的消息。它与 "Summarize from here" 共同构成双向、定向的上下文窗口压缩能力；同样不改动磁盘文件，原始消息保留在 transcript 中。
6. Never mind（算了）—— 取消并返回当前状态。

两个值得注意的细节：恢复会话或汇总后，所选消息的原始 prompt 会被恢复进输入框，方便你重新发送或编辑；而从 v2.1.191 起，/clear不再是一道硬边界——/rewind可以恢复到执行/clear之前的 checkpoint，清除会话不再永久丢弃其前置状态。

配置与保留策略

Checkpoints 是 Claude Code 的内置默认行为，无需额外配置即可启用。两个设置控制其行为——是否拍照快照，以及保留多久：

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

Claude Code 会保留最近 100 个 checkpoint的快照；更旧的快照即使在保留窗口内也会被丢弃。

仓库的 09-advanced-features/config-examples.json 展示了fileCheckpointingEnabled在真实场景配置中的用法。例如Learning Mode（"prompt 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: Let's implement a direct migration from MySQL to PostgreSQL [Checkpoint A created automatically] Claude: I'll 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. Let's try the dual-write pattern instead. [User presses Esc+Esc, selects Checkpoint A, chooses "Restore code and conversation"] User: Now implement a dual-write pattern where we write to both databases Claude: I'll 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. Let's commit this.

这个场景揭示了 Checkpoints 的核心价值：回退不需要重新来过。当直迁方案在测试阶段暴露 15 个失败用例（连接池问题）时，直接回退到 Checkpoint A（迁移开始前），代码和对话一并还原，然后在干净的基础上切换到双写方案。对比之后，安全且通过全部测试的双写方案被提交。

例 2：性能优化——三条路线对比后叠加出最优解

场景：API 响应时间优化，基线 450ms，需要尝试多种优化策略。

工作流：

User: Let's optimize the API response time. Current: 450ms [Checkpoint "Baseline" created automatically] Claude: I'll 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 Esc+Esc, selects "Baseline" checkpoint, chooses "Restore code and conversation"] User: Try database query optimization instead Claude: I'll optimize database queries... [Adds indexes, optimizes N+1 queries] User: Run performance tests Claude: Results: 180ms average response time (60% improvement) User: Let me also try a third approach. [User presses Esc+Esc, selects "Baseline" checkpoint, chooses "Restore code and conversation"] User: Try response compression and CDN Claude: I'll 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 Esc+Esc, 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. Let's commit this.

这是一个教科书级的分支探索案例：Redis 缓存（38%）→ 回退 → 查询优化（60%）→ 回退 → 压缩 + CDN（29%）。更重要的是最后一步——回退到"查询优化完成"的 checkpoint（而非 Baseline），在最优单方案之上叠加缓存，最终取得 79% 的改进。Checkpoints 不仅支持从头对比，还支持从任意历史节点继续叠加优化。

例 3：UI/UX 迭代——多布局方案与组合设计

场景：为 dashboard 尝试不同布局。

工作流：

User: Let's 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. Let's try a top navigation instead. [User presses Esc+Esc, 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 let's try a card-based grid layout [User presses Esc+Esc, 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 Esc+Esc, 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: There's a memory leak in the application [Checkpoint "Before debugging" created automatically] Claude: Let me investigate... [Analyzes code] User: I think it's in the event listeners. Let's fix those. Claude: [Fixes event listener cleanup] User: Run memory profiler Claude: Still leaking memory - event listeners weren't the issue User: Let me go back and try a different hypothesis. [User presses Esc+Esc, selects "Before debugging" checkpoint, chooses "Restore code and conversation"] User: Maybe it's 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 Esc+Esc, selects "Before debugging" checkpoint, chooses "Restore code and conversation"] User: Let's 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! Let's commit this fix.

调试是最能体现 Rewind 价值的使用场景之一。三个假设（事件监听器、数据库连接、循环引用）从同一个 "Before debugging" checkpoint 出发，前两个被证明无效后一键回退，不会把失败修复的残留代码混入下一轮排查，最终精确定位到缓存层的循环引用。

例 5：API 设计演进——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. Let's add pagination and filtering Claude: [Adds pagination and filtering] User: We need better resource relationships Claude: [Implements HATEOAS links] User: Actually, let's try GraphQL instead of REST [User presses Esc+Esc, 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 Esc+Esc, selects the checkpoint after HATEOAS, chooses "Restore code and conversation"] User: Let's 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 Esc+Esc, 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. Let's 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 Esc+Esc, 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 let's continue with the approach that worked.

这是唯一不需要"回退代码"的用法：长调试会话会迅速占满上下文窗口、降低模型质量。选择早期 checkpoint 并执行Summarize from here，AI 会从该点往后生成摘要替代可见对话，原始消息仍保存在 transcript 中；你还可以附带指令让摘要聚焦"尝试过什么、什么有效"。压缩后可以继续顺着有效路线推进，而不是被迫硬撑或从头开始。

从示例提炼：可复用的 Workflow Patterns

08-checkpoints/README.md 将上述示例背后的通用模式归纳为四种使用场景与两种流程模板：

分支探索策略（例 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 给出了二者的对比：

两者配合使用的最佳实践：

1. 用 checkpoints 做快速实验与探索；
2. 用 git commits 固化定稿的代码变更；
3. 在 git 操作前创建 checkpoint；
4. 将成功的 checkpoint 状态提交到 git。

四个实战示例也遵循这一原则：探索、对比、试错全部在 checkpoint 内完成，一旦确定方案立即 commit——例 1、例 2、例 4、例 6 都以Let's commit this收尾。

注意事项与限制

Checkpoints 并非万能，以下限制需要牢记（08-checkpoints/README.md）：

• Bash 命令更改不被追踪：文件系统上的rm、mv、cp等操作不会记录进 checkpoints。
• 外部更改不被追踪：在 Claude Code 之外（编辑器、终端等）的修改不会被捕获。
• 不能替代版本控制：codebase 的永久性、可审计变更应使用 git。
• 从 v2.1.216 起，/rewind不会通过符号链接或硬链接恢复/删除受追踪路径下的文件；若某路径经由 symlink/hardlink 解析，rewind 会跳过它并报告跳过的路径数量。

最佳实践：Do 与 Don't

✅应当：

• 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（会话历史与上下文管理）结合使用。

关键要点总结

1. Checkpoints 是自动的：每次用户 prompt 都会创建 checkpoint，无需手动保存。
2. 两种入口：Esc+Esc与/rewind（别名/checkpoint、/undo）是打开 checkpoint 浏览器的途径。
3. 选择合适的恢复选项：按需选择恢复代码、恢复会话、两者都恢复，或汇总（Summarize from here / up to here）。
4. 不要畏惧实验：Checkpoints 让激进的变更尝试变得安全。
5. 与 git 配合：探索用 checkpoints，定稿用 git。
6. 长会话及时汇总：用 "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