一次说错可以撤回:checkpoint 用法

📍 进阶 5/10 · 上一篇:← 上下文窗口怎么算的

一个迟早会撞上的灾难时刻

某个工作日午后,你跟 Claude Code 说:

“把这个项目的代码风格统一一下,有些地方用 camelCase 有些用 snake_case,挑一个标准全部统一。”

它非常热情:

“好的,我看了一下,你的项目大部分文件偏向 camelCase,我已经把全项目 26 个文件全部统一成了 camelCase!”

你打开 git diff,3,400 行修改。

你心一沉——你早上刚跟客户对齐过,这个项目要走 snake_case 才能跟他们的库对接。它把方向完全做反了。

如果只有 git,你接下来要:git reset + 解释为什么 staging 区里有这么多怪改动 + 担心丢掉同时段的另一组合理改动…

Checkpoint 就是为这一刻而生:一行命令回到改之前,不影响其他东西。

Checkpoint 是什么

简单粗暴:Claude Code 每次改完一组文件后,自动存一个快照。

这个快照:

• ✅ 记录了所有被改文件的「改前 / 改后」内容
• ✅ 不污染你的 git 历史(完全独立)
• ✅ 永久保留(直到你手动清理或者超过保留期)
• ✅ 一行命令就能跳回去

类比一下:

• Checkpoint = 游戏存档点 — 死了能读档,不用从头开始
• Git commit 是给团队看的「正式版本」(整理过、配 message)
• Checkpoint 是给你和 AI 之间的「小灶」(自动、密集、随便丢)

重点区别:Git 是你手动commit;Checkpoint 是 Claude 自动存,你不用想着保存。

怎么看历史 checkpoint

在 Claude Code 内,输入:

/checkpoint

会列出最近的 checkpoint 列表,大概像这样:

Checkpoints (most recent first):

  [1]  3 minutes ago    │ Updated 12 files in src/api/
  [2]  17 minutes ago   │ Refactored auth.py
  [3]  42 minutes ago   │ Created new helper.ts
  [4]  1 hour ago       │ Updated README.md
  [5]  2 hours ago      │ Fixed typo in package.json

  Type /checkpoint <n> to roll back to that point.

每一条 checkpoint 有 3 个信息:

• 编号(从 [1] 开始,数字越小越新)
• 时间(多久之前存的)
• 改了什么(自动总结的概要)

怎么回滚

知道要回到哪个之后,输入:

/checkpoint 1

(回到最近一个 checkpoint,也就是说:撤销上一组改动)

或者:

/checkpoint 3

(回到 42 分钟之前)

Claude Code 会:

1. 二次确认:“将回滚以下文件:…”(列出受影响的文件)
2. 你按 y 确认
3. 瞬间还原——所有 checkpoint [3] 之后的改动全部撤销

⚠️ 关键提醒:回滚是累积的——回到 [3],等于同时撤销了 [1] [2] [3] 之后的所有 [1] [2]。不能只撤 [2] 不撤 [1]。

如果你想「只撤其中一组」,得用 git 的 cherry-pick 思路,checkpoint 做不到精细化挑选。

怎么看 checkpoint 的具体差异(diff)

回滚之前,你想先看一眼具体改了什么?有专门的命令:

/checkpoint diff 1

会弹出一个对比视图,红色是删的、绿色是加的,跟 git diff 一模一样。

新手强烈建议的习惯:回滚前先 diff 看一眼——

• 确认 AI 真的改了不该改的东西
• 避免把对的部分一起撤了
• 看清楚后再下决定 y/n

什么时候要「手动锚定」一个 checkpoint

Claude Code 是每改完一组文件就自动存。但有些时刻你想主动多存一个,因为接下来要做的事风险特别高:

/checkpoint create "before-refactor-api"

(给这个 checkpoint 加一个名字,方便以后找)

什么场景该手动锚定:

场景	为什么要锚定
准备让 AI 大刀阔斧重构	一旦方向错,要能秒退
已经跑通了一个 demo,想试新方案	试新方案前先存”已知能跑”的版本
准备让它 bypass 模式跑大任务	给自己留个底牌
周五下班前	周一回来如果方向乱了,周五的版本随时回

取名的小技巧:用「描述任务目标」而不是「时间戳」。

• ❌ 不好:checkpoint-2026-05-16-1430
• ✅ 好:before-refactor-api / demo-works-here / friday-eod

Checkpoint 跟 Git 的关系

一句话:Checkpoint 不替代 Git,Git 也不替代 Checkpoint。

用 Checkpoint 处理:

• 跟 AI 的密集试错(它改 → 你看 → 不对再回滚 → 它再改)
• 你不想污染 git 历史的零碎改动
• 当天的回退需求

用 Git 处理:

• 正式发布的版本(打 tag、做 release)
• 团队协作的版本(同步给别人 / pull request)
• 跨周 / 跨月的回退

最佳节奏:

1. 早上git pull 拿最新代码
2. 白天用 Claude Code 改,全程靠 checkpoint 来回试
3. 改顺了,手动 git add + git commit 给团队
4. 第二天重新走一遍

三个新手最容易踩的坑

❌ 坑 1:不知道 checkpoint 存在,出了事傻乎乎用 git

新手第一次撞上「AI 改坏了」,第一反应是:

• git status 看一堆乱七八糟的修改
• git reset --hard 强行撤回(可能误伤其他改动)
• git stash 然后再 stash pop

修正:装好 Claude Code 第一周,就把 /checkpoint 这条命令记下来。出事第一件事,先 /checkpoint 看清楚有没有快照能用。

❌ 坑 2:回滚后没存盘,关掉 Claude Code 又丢了

/checkpoint <n> 回滚之后,改动只在内存里——你要是直接退出 Claude Code,有可能丢失。

修正:回滚完立刻 git add + git commit——把「回滚后的好版本」钉到 git 历史里,这样无论 Claude Code 关闭还是 checkpoint 过期,你都有底。

❌ 坑 3:依赖 checkpoint 当唯一备份

checkpoint 是本地的、有保留期的、Claude Code 进程相关的——

• 换电脑:checkpoint 不跟你走
• 保留期超了:checkpoint 可能被自动清理
• Claude Code 重装 / 升级:checkpoint 不一定保留

修正:长期 backup 还是要 git。Checkpoint 是「临时撤销键」,不是替代品。

一个真实场景演练

假设你跟 Claude Code 这样一段对话:

你:  把全项目代码风格统一成 camelCase。
AI:  好的,已修改 26 个文件。
你:  /checkpoint diff 1
AI:  (弹出 26 个文件的红绿对比)
你:  完蛋,客户那边要 snake_case,撤回。
你:  /checkpoint 1
AI:  Confirm rollback of 26 files? (y/n)
你:  y
AI:  ✓ Restored.
你:  把全项目代码风格统一成 snake_case 而不是 camelCase。
AI:  好的,已修改 26 个文件。
你:  /checkpoint diff 1
AI:  (弹出新对比)
你:  好,这次对了。
你:  git add . && git commit -m "unify code style to snake_case"

整个过程不到 10 分钟,没有污染 git 历史,也没有损失任何代码。

这就是 checkpoint 的真实价值——让你敢让 AI 大胆改。

下一步

读完这一篇你应该理解 /checkpoint 列表 + 回滚 + diff + 手动锚定 这 4 个核心操作。

接下来:

→ 出错怎么办:常见报错排雷大全 —— 8 个最常见报错的「症状 → 原因 → 修复」速查

→ 怎么省钱:成本控制实战 —— 4 个手法把 Claude Code 月费砍到三十块

想第一时间收到,可以收藏 niuxue.org 主页。

---

如果你跟 AI 之间发生过最戏剧的 checkpoint 回滚,告诉我们 [email protected],优秀案例会精选放上来。