在使用 Claude 进行规范驱动开发时绝不能做的事
It looks like only the source line was provided, but the article text you’d like translated isn’t included. Could you please paste the content you want translated (or let me know if you’d like me to retrieve it for you)? Once I have the text, I’ll translate it into Simplified Chinese while preserving the formatting, markdown, and any code blocks.
引言
资深工程师已经采用 AI 辅助工作流，了解其承诺：更快的迭代、更少的误解，以及代码库能够体现意图而非即兴。使用 Claude 的规范驱动开发是该手册中最强大的模式之一。但它也是最容易被误用的模式之一。以下是区分能够持续产出生产质量代码的团队与那些花更多时间纠正 Claude 而不是编写代码的团队的关键。
1. 不要写模糊的规格并指望 Claude 填补空白
Claude 是一个出色的推理引擎，但它 不是 心灵感应者。当你的规格说 “构建用户管理系统” 时，Claude 会做出假设——这些假设是合理的，基于通用的最佳实践——但它们很可能不符合你的具体情境。
作为架构师，你的工作是把隐含的内容显式化。这意味着在规格本身中命名有界上下文、数据所有权规则、失败模式以及非功能性需求 在规格本身。如果没有写出来，就不要指望 Claude 在长时间的会话中正确推断。
The fix
把你的规格当作 RFC 来对待。为一个对你组织的决策、约束和惯例一无所知的人撰写它。
2. 不要让 Claude 在没有你的领域输入的情况下编写规范
有一种诱人的工作流：把问题陈述直接丢给 Claude，让它生成规范，然后用该规范来驱动实现。若是天真地直接使用，就会产生循环推理——Claude 根据它认为你想要的内容写出规范，再实现它自己写的规范，根本没有锚定真实的领域问题。
Claude 在结构化和形式化规范方面表现卓越，前提是你已经提供了领域知识。它不应该成为这些知识的来源。
解决方案
- 你提供领域信息。
- Claude 提供结构。
先用自然语言草拟关键决策和约束条件，然后让 Claude 将它们形式化为包含章节、边缘情况和验收标准的规范。
3. 不要跳过验收标准
这是高级工程师在转向规范驱动工作流时最常犯的错误。他们编写了出色的功能描述，却忽略了 “完成”应是什么样子。
如果没有验收标准，Claude 会按照它理解的方式完成实现——技术上正确，但可能完全不符合你的期望。你只能在评审时才发现这一点，这完全违背了规范驱动方法的初衷。
解决方案
规范中的每个功能都应以 至少三个可测试、具体的验收标准 结束。
- ✅ 好的示例：“当缺少必填字段时，端点返回 422 状态码并带有结构化错误体。”
- ❌ 不好的示例：“优雅地处理错误。”
4. 不要过度指定实现
在模糊的另一端也存在一种失效模式：在规范中对实现进行微观管理。告诉 Claude 使用哪种设计模式、如何组织类层次结构，或调用哪个库方法，会把你的规范变成一个翻译层——并且剥夺了 Claude 最有价值的优势。
规范应当捕捉 what（做什么）和 why（为什么）。实现细节应在单独的对话中，或在技术设计文档里讨论，且仅在规范得到验证之后才进行。
解决方案
如果你发现自己在规范中写方法签名或 SQL 查询，请停下来。改为写你想要强制执行的业务规则或约束，让实现的讨论另行进行。
5. 不要假设 Claude 在会话之间保留上下文
Claude 的上下文窗口 不会 在不同对话之间持久化。如果你上周二写了一份基础规范，Claude 今天已经不记得它了。在没有重新提供上下文的情况下继续构建会导致漂移——每个会话都会稍微重新解释基础内容，随着时间推移，实现会偏离最初的意图。
解决方案
将你的规范视为 活文档，在每个相关会话开始时都提供给 Claude。将其保存在版本控制中并显式引用。如果规范太长，以至于每次传递都显得代价高昂，那说明你有范围（scope）问题，而不是工具问题。
6. 不要在单一规范中混合关注点
同时涵盖 API 合约、数据持久层、业务规则和 UI 行为的规范 不是 规范；它是一份带有身份问题的设计文档。Claude 会尝试满足所有这些内容，导致实现紧耦合，违背了你作为架构师真正关心的边界。
在规范中混合关注点也是协作风险。如果多个团队使用同一规范，他们会把 Claude 拉向不同的方向。
解决方案
- 每个有界关注点对应一个规范。
- API 行为
- 领域逻辑
- 数据合约
- 基础设施期望
应在任何给定会话中明确告知 Claude 正在使用哪个规范。
7. 不要忽视 Claude 的澄清问题
当 Claude 在规格或实现的中途暂停并提出澄清问题时，这个问题是信号，而不是烦扰。它表明规格中存在歧义，如果不解决，就会导致隐式做出决定。代码库中的隐式决定实际上是技术债务。
人们往往想快速回答并继续前进。更好的做法是 更新规格 来消除歧义，然后再作答。这样，问题只会被提出一次——而不是每当新的工程师或新的 Claude 会话遇到同样的空白时都要重新提问。
解决方案
把每一个澄清问题视为 规格缺陷。先修正规格，然后再继续。
8. 在规范稳定之前不要开始编码
规范驱动的开发需要纪律：在生成任何实现代码之前，规范必须 完整、已审查并签署。这是你必须强制执行的过程边界。
这种无摩擦感是一个陷阱。根据草稿规范生成实现代码意味着随着规范的演进，你会不断修改代码。在复杂系统中，这会导致实现陈旧、行为不一致，以及会抹去所有预期的生产力提升的返工。
解决方案
为规范工作和实现工作使用不同的对话。生成规范的对话应以一个稳定、已审查的产出结束。随后以该产出为起点的新对话推动实现。
9. 不要忘记定义范围之外的内容
高级工程师在撰写 RFC 和设计文档时都知道：你选择不去构建的东西与决定要构建的东西同样重要。没有明确范围边界的规格会让 Claude 对是否包含做出判断，而这些判断往往过于乐观。
范围之外的章节也是对你自己思考的强制推动。如果你无法阐明该规格不涵盖哪些内容，说明你没有一个足够清晰的边界来开始构建。
解决方案
每个规格都需要一个 “非目标” 或 “范围之外” 部分。要明确说明。
“本规格不涉及多租户、审计日志或软删除行为。”
这种精确性可以让实现保持精简且易于审查。
10. 不要在实现开始后把规范视为不可变
规范会演变。需求会变化。你在实现过程中会发现设计时未显现的边缘情况。这本身不是问题——除非你选择让 Claude 规避规范而不是更新规范。
规避措施会累积。实现会偏离规范。规范变成了历史文献，而不再是事实的来源。你失去了规范‑驱动方法的全部价值。
解决方案
当实现揭示出缺口或矛盾时，停止。更新规范。将 Claude 重新锚定到更新后的版本。这在短期会增加摩擦，但能防止长期的熵增。
基本原理
Spec‑driven development with Claude works when the spec does what specs have always been meant to do: encode intent precisely enough that implementation becomes a constrained, verifiable process. Claude amplifies that process; it does not replace the thinking that makes the spec worth writing in the first place.
The anti‑patterns above share a common root: they treat Claude as a system that compensates for imprecision. It doesn’t. It executes against what it’s given with remarkable fidelity, which means the quality of your output is a direct function of the quality of your spec.