检查点预览

bmad-checkpoint-preview 是一个交互式的、LLM 辅助的人机协作审查工作流。它带你逐步走过一个代码变更——从目的和上下文到细节——让你能做出知情决策：是发布、返工，还是深入挖掘。

典型流程

你运行 bmad-quick-dev。它澄清你的意图、构建规范、实现变更，完成后将审查线索追加到 spec 文件并在编辑器中打开。你查看 spec，发现这次变更涉及跨多个模块的 20 个文件。

你可以肉眼扫一遍 diff。但 20 个文件正是肉眼审查开始失效的临界点——你会丢失线索，漏掉两个相距甚远的变更之间的关联，或者批准了自己没有完全理解的东西。所以你改为说 “checkpoint”，让 LLM 带你走一遍。

这种交接——从自主实现回到人工判断——就是核心使用场景。Quick-dev 以最少的监督长时间运行，检查点预览则是你重新掌舵的地方。

为什么需要它

代码审查有两种失败模式。一种是审查者浏览 diff，什么也没发现，直接批准。另一种是逐文件仔细阅读，但丢失了全局线索——见树不见林。两种模式的结果相同：审查没有抓住真正重要的东西。

根本问题在于顺序。原始 diff 按文件顺序呈现变更，而这几乎从来不是构建理解的顺序。你先看到一个辅助函数，却不知道它存在的原因；先看到一个 schema 变更，却不了解它支撑什么功能。审查者必须从零散的线索中重建作者的意图，而这个重建过程正是注意力失效的地方。

检查点预览通过让 LLM 完成重建工作来解决这个问题。它读取 diff、spec（如果有的话）和周围的代码库，然后按照有利于理解的顺序——而不是 git diff 的顺序——呈现变更。

工作原理

工作流分为五个步骤。每一步都建立在前一步的基础上，逐步从”这是什么？“过渡到”我们该不该发布？“

1. 定向

工作流识别变更来源（来自 PR、commit、分支、spec 文件或当前 git 状态），生成一行意图摘要以及表面积统计：变更文件数、涉及模块数、逻辑行数、边界穿越数和新增公共接口数。

这是”这是不是我以为的那个东西？“的时刻。在阅读任何代码之前，审查者确认自己看的是正确的东西，并对范围建立预期。

2. 走查

变更按关注点——而非按文件——组织。关注点是内聚的设计意图，例如”输入验证”或”API 契约”。每个关注点附带简短说明——为什么选择这种方案，然后列出可点击的 path:line 停靠点，审查者可以沿着这些停靠点在代码中导航。

这是设计判断步骤。审查者评估的是方案对系统是否合理，而不是代码是否正确。关注点按自顶向下排列：最高层意图在前，支撑实现在后。审查者永远不会遇到引用了自己尚未看过的内容。

3. 细节审视

在审查者理解了设计之后，工作流浮出 2-5 个”出错代价最高”的位置。这些位置按风险类别标记——[auth]、[schema]、[billing]、[public API]、[security] 等——并按出错后的影响范围排序。

这不是找 bug。自动化测试和 CI 负责正确性。细节审视激活的是风险意识：“这些是出错成本最高的地方。“如果审查者想在某个领域深入，可以说 “dig into [area]” 来触发一次聚焦正确性的重新审查。

如果 spec 经过了对抗性审查循环（机器硬化），那些发现也会在这里浮出——不是已修复的 bug，而是审查循环标记出的、审查者应当知晓的决策。

4. 测试

建议 2-5 种手动观察变更生效的方式。不是自动化测试命令——而是能构建信心、但测试套件无法提供的手动观察。一个可以尝试的 UI 交互、一条可以运行的 CLI 命令、一个可以发送的 API 请求，以及每项的预期结果。

如果变更没有用户可见的行为，它会明确说明。不发明多余的忙活。

5. 总结

审查者做出决定：批准、返工或继续讨论。如果批准 PR，工作流可以协助执行 gh pr review --approve。如果需要返工，它帮助诊断问题出在方案、spec 还是实现，并帮助起草与具体代码位置关联的可操作反馈。

它是对话，不是报告

工作流将每一步呈现为起点，而非定论。在步骤之间——或步骤中间——你可以与 LLM 对话、提问、挑战它的框架，或调用其他技能来获取不同视角：

• “run advanced elicitation on the error handling” — 推动 LLM 重新思考并细化对特定领域的分析
• “party mode on whether this schema migration is safe” — 引入多个 agent 视角进行聚焦辩论
• “run code review” — 生成包含对抗性和边界场景分析的结构化 agentic 审查报告

检查点工作流不会把你锁在线性路径上。它在你需要结构时提供结构，在你想探索时让开。五个步骤确保你看到全貌，但每一步深入到什么程度——以及调用什么工具——完全由你决定。

审查线索

走查步骤在有建议审查顺序时效果最好——这是 spec 作者编写的停靠点列表，用于引导审查者走过变更。当 spec 包含此内容时，工作流直接使用它。

当没有作者提供的线索时，工作流会从 diff 和代码库上下文生成一份。生成的线索质量不如作者编写的，但远好于按文件顺序阅读变更。

何时使用

主要场景是 bmad-quick-dev 的交接：实现完成，spec 文件在编辑器中打开并追加了审查线索，你需要决定是否发布。说 “checkpoint” 即可开始。

它也可以独立使用：

• 审查 PR — 尤其是涉及多个文件或跨模块变更的 PR
• 了解一个变更 — 当你需要理解一个不是你写的分支上发生了什么
• Sprint 审查 — 工作流可以提取 sprint 状态文件中标记为 review 的 story

通过说 “checkpoint” 或 “walk me through this change” 来调用。它在任何终端中都能工作，但在 IDE 中——VS Code、Cursor 或类似工具——你会获得更多，因为工作流在每一步都生成 path:line 引用。在嵌入 IDE 的终端中，这些引用是可点击的，你可以沿着审查线索在文件间跳转。

它不是什么

检查点预览不是自动化审查的替代品。它不运行 linter、类型检查器或测试套件。它不打分也不给出通过/不通过的判定。它是一份阅读指南，帮助人类在最重要的地方运用自己的判断力。