让 Claude Code 思考后再写代码的 Prompt 秘诀

更新说明

目前已推出 v2 版本。这篇文章中那个纪律严明的开发者演变为一个完整的团队：一个 agent 将想法转化为 issue，一个编排器负责工作分配（不写代码），专门的子 agent 并行构建，还有一个审查门控将一组 PR 一次性推动到可合并的状态。如果这篇文章是"编码前思考"的基础，v2 就是"设计、委派、验证，并行进行"。→ 在这里阅读

下面的所有内容仍然有效，保留为 v1。

正文

Claude Code 是我合过的最快的编码员。它能在几分钟内搭建功能、写测试、打开 PR。但我一直遇到同样的问题：代码能工作，然后它就不能了。

状态转换中的竞态条件。一个本应是常量的硬编码字符串。一个回滚了它应该保留的审计记录的事务。断言为 true 而不是断言正确值的测试。

修复总是很快。但每次修复都伴随一个附加任务：事件处理、回归测试、"我们为什么没抓住这个？"的事后分析。速度很高。考虑到 bug，净速度就不是了。

即使有个不错的 CLAUDE.md，我仍然要在每次会话中监督 Claude。"这次别忘了 TDD"。"嘿，你忘了检查 Bug Bot"。"能在打开 PR 前真正运行一遍测试吗？"每个提示都像是和一个才华横溢但短期记忆力堪比金鱼的人对话。问题不在 Claude 的能力。问题在于，写在 markdown 文件里的好习惯不会自动变成实际行为。我就是这个流程。这意味着流程是不稳定的、容易遗忘的，而且越来越让人恼火。

所以我尝试了不同的方法。我没有去修复 Claude 的输出，而是改变了 Claude 的思考方式。

问题不在智力，在流程

看看初级开发者怎么工作：他们读 ticket，打开文件，开始敲代码。他们很快。同时，他们也是那些容易忘记检查调用的方法是否真的存在、或者引用的数据库列是否在三周前被重命名的人。（总是三周前被改的。）

再看看高级开发者：他们读 ticket，读周围的代码，读测试，查 git 历史，然后才开始敲代码。他们启动慢，但完成快，因为他们不用回头修复自己破坏的东西。

Claude Code 默认是初级模式。不是因为知识不足，而是因为没有流程。它没有内部检查清单告诉它要验证假设、先写测试，或者思考两个请求同时打到一个端点会怎样。它充满热情。它快速发布。而热情，事实证明，察觉不了可空 datetime 的崩溃。

我为它构建了这个检查清单。

/wizard 技能

/wizard 是一个 Claude Code 技能，是存在于你项目中的 markdown 文件，当你在 CLI 中输入 /wizard 时激活。它把 Claude 从快速编码员转变为有方法的软件架构师。可以想象成有个高级工程师看着 Claude 的肩膀，只不过这个人从不问你有没有试过重启一下。

这是一个 8 阶段的方法论，最有效的前提是已经具备几个条件：有一个定义项目约定的 CLAUDE.md，工作前已创建 GitHub issue（/wizard 可以帮你写），真正承诺做 TDD，每个任务一个干净的特性分支。对于 CI，我用 GitHub Actions，但这个技能不挑。它只需要在第 8 阶段能有东西来响应。

8 个阶段如何运作

阶段 1：动手前先计划

Claude 读你的 CLAUDE.md，找到关联的 GitHub issue，在写一行代码前就构建好结构化的待做清单。它评估复杂度：可能影响几个文件、是否有架构影响、风险有多大。然后据此调整工作规模。

听起来很显而易见。确实显而易见。但这也是你匆忙时最容易跳过的步骤，而这正是你最需要它的时候。讽刺吧。

阶段 2：假设前先探索

有了计划后，Claude 探索实际代码库。它对每个打算使用的模型、方法、关系和常量进行 grep，在代码里引用前先验证它们确实存在。

没有这个阶段，Claude 可能会自信地调用 user.clientProfile.accounts，一个它完全凭想象编造出的关系链。第 2 阶段存在的目的就是防止这种事。仅这一个改变就消除了我项目中整整一类 bug。事实证明"这东西真的存在吗"是个相当好的问题，要在你基于它构建前问一遍。

阶段 3：先写测试

阶段 3 强制执行 TDD。Claude 写会失败的测试，运行它们（必须失败），实现最少代码让测试通过，然后验证。每次都这个顺序，没有捷径。

但关键是：它采用变异测试心态。不是 assert($result)，而是 assertEquals('completed', $result->status)。不是检查函数运行无错，而是检查每个副作用都真的发生了：时间戳被设置了，通知发出去了，计数器递增了。

区别很重要。assert(true) 即使代码什么都不做也会通过。抵抗变异的断言能捕获真实的 bug。你的测试套件应该是个怀疑者，不是那个不读代码也要跟你说 PR 很棒的朋友。

阶段 4：实现最小化

有了失败的测试，Claude 写实现。不是完整的远景，不是它脑子里已经有的聪慧抽象，就是让测试通过所需的最少代码。范围蠕变也是 bug，而且是最昂贵的那种，因为它看起来像是进度。

阶段 5：验证没有回归

阶段 5 运行更广泛的测试套件，不只是新写的测试。目标是零回归。如果有不相关的东西坏了，现在发现比在 PR review 里听说"怎么账单模块坏了？"好得多。

阶段 6：趁上下文还热时记录

内联注释、changelog 条目，任何需要更新的东西。小步骤，容易跳过，但在上下文蒸发前总值得做。下一个读这段代码的人可能是三个月后的你，那时你对自己的决定一无所知。

阶段 7：对抗性审查

这是 /wizard 真正发光的地方。每次提交前，Claude 不是以作者身份，而是以攻击者身份审查自己的工作。检查清单：

• 如果这个并发运行两次会怎样？
• 如果输入是 null？空的？负数？
• 我做了什么可能错误的假设？
• 如果这在生产坏掉我会尴尬吗？

这不是纯理论。在我的代码库里，这个阶段捕获过：

一个缺乏数据库锁定的状态转换服务。两个并发 API 调用可能应用冲突转换。一个竞态条件，就静静地坐在那里，等待糟糕的一天。

一个 Blade 模板在可空 datetime 上调用 ->format()。当字段为 null 时任何页面加载都会崩溃。完全无声，直到它发生。

使用硬编码类别字符串的通知负载，而不是同一个 PR 里新创建的枚举。真是绝了。

单靠测试捕获不了这些。它们需要以不同的心态思考代码：作为攻击者而非作者。

阶段 8：质量门控循环

阶段 8 处理 PR 生命周期。/wizard 不只是打开 PR 然后撒手不管。它监视自动审查 bot 状态（Bug Bot、CodeRabbit，无论你用什么），读每一个发现，修复有效的问题，回复误报，重复直到状态清晰。

这是我以前手动做、而且经常忘记的阶段，导致 PR 带着未解决的 bot 发现在那儿放了好几天。现在它是流程的一部分，这才是它该在的地方。

一个真实任务的完整例子

这就是所有 8 个阶段在真实任务中的样子：实现 ACAT 转移状态跟踪和通知。

阶段 1： Claude 读 CLAUDE.md，找到 GitHub issue，将任务评估为"复杂"（7+ 个文件，有架构影响），构建待做清单。

阶段 2： Claude 对 AcatTransfer 模型 grep，验证 VALID_TRANSITIONS 常量存在，检查 ClientProfile 有正确的关系，确认 NotificationCategory 枚举存在。没有幻想出的方法链。没有意外。

阶段 3： Claude 写 23 个失败的测试，覆盖状态转换、通知、命令行为和 dashboard 渲染。运行它们。全部失败。好的。这就是目的。

阶段 4： Claude 实现服务、命令、5 个通知类、控制器改动和 Blade 模板。运行测试。全部通过。

阶段 5： 运行完整的相关测试套件（49 个测试）。零回归。

阶段 6： 更新 changelog，为转换服务添加内联注释。

阶段 7： 对抗性审查捕获 initiated_at->format() 在字段为 null 时可能 NPE。在它变成凌晨 2 点的事件前就修了。

阶段 8： 打开 PR。Bug Bot 找到 4 个问题：

• 硬编码类别字符串（应该用枚举）：已修复
• 状态转换上缺乏数据库锁定：用 lockForUpdate() 修复
• Blade 模板中可空的 initiated_at：用 null-safe 操作符修复
• 完成事件的错误通知语气：已修复

3 个修复循环后，Bug Bot 返回成功。PR 准备好了。

总计： 49 个测试，108 个断言，4 个 bug 在发货前被捕获。对一个检查清单来说不错。

安装和定制

curl -sL https://raw.githubusercontent.com/vlad-ko/claude-wizard/main/install.sh | bash

这会在 .claude/skills/wizard/ 里放入三个文件：

• SKILL.md： 核心 8 阶段方法论
• CHECKLISTS.md： 快速参考检查清单
• PATTERNS.md： 常见的模式和反模式

然后在 Claude Code 里输入 /wizard 来激活它。

这个技能设计上是框架无关的。它不关心你是在写 Laravel、Rails、Next.js 还是 Rust。计划、探索、测试、实现、验证、文档、审查、发布的方法论，放哪儿都好用。

但当你定制它时它会更强大。在我的项目里，我加了：

• Laravel 特定的测试命令（./vendor/bin/sail test）
• 我们的日志服务模式（LoggingService::logPortfolioEvent()）
• ORM 的数据库锁定约定
• Bug Bot 线程解决命令（GraphQL mutations）
• Alpine.js 组件的需求

你加的项目特定上下文越多，Claude 需要猜测的就越少。Claude 猜测越少，就越少有 bug 漏出去。事实证明这两件事是相关的。

/wizard 不是什么

/wizard 不是代码审查的替代品。不是测试框架。不是 CI 管道。

它是一个流程提示：一种方式来把高级工程师的习惯编码到 Claude 的工作流中，这样这些习惯每次都会执行，每个任务都会，即使在凌晨 2 点当你累得只想让功能发布的时候。

这个提示大约 500 行 markdown。没有魔法。它就是一个好的技术主管会过一遍的那个检查清单，写成了明确和可重复的形式。唯一令人惊讶的是没人早点想到把它写下来。

想要团队版本？v2 把这个完整方法论分配给编排器、专门的子 agent、对抗性人物评论者和独立审查门控，全部并行运行，一次驱动多达 10 个 PR。→ 我给 Claude Code 一个团队

完整的技能开源于 github.com/vlad-ko/claude-wizard。MIT 许可。fork 它，定制它，让它更好。

它来自于构建 wealthbot.io，一个金融科技平台，"大部分能工作"绝对不是产品策略。这些模式是在数百个 PR 和真实生产事件中精化出来的。框架特定的部分已经被剥离，但方法论经过了真实考验。

如果你试试，我很想听听它给你捕获了什么。

有些评论可能只对登录用户可见。登录以查看所有评论。有些评论已被 post 作者隐藏——了解更多

对于进一步的行动，你可以考虑屏蔽此人和/或举报滥用