第2节：规范驱动开发SDD，让AI永远在轨道上

AI编程企业级实战上一节第1节一个人的架构师Claude Code是你的团队本节第2节规范驱动开发SDD让AI永远在轨道上下一节待更新带过团队的人大多都有一个很深的体会你脑子里想得再清楚只要没有落成明确的文字对方做出来的东西往往就会和你想的不一样。但如果你给了接口文档、数据模型、命名规范、错误码定义交付质量通常就会立刻上一个台阶。Claude Code 也是一样。它很强但它不会读心。你不告诉它规则它就会自己“脑补”出一套做法而且每次写出来还可能都不一样。这就是我们接下来要讲的规范驱动开发 SDD。一句话概括先定规范再让 AI 按规范执行而不是一上来就让它直接写代码。规范不是一次性指令而是一套体系很多人已经发现了一个规律给 Claude Code 的指令越清晰输出质量就越高。但这里有一个很容易被忽略的问题你在某一次对话里补充得再详细那些要求也只对那一次对话有效。比如我在做模型提供商管理时曾经把要求写得很细实体叫 Provider不要加前缀或后缀。返回格式统一。使用 Result 包装。错误码按模块分段。不要引入设计模式。于是 Claude Code 输出得很干净命名统一格式规范结构也足够简洁。但过了一段时间当我开始做 Agent 模块时指令里没有再重复这些规范只写了“实现 CRUD 接口”。我以为它会记得结果并不会。单看每一段代码也许都不是 bug功能甚至是完整的。但一旦放到同一个项目里就会出现两套风格命名规则不同返回格式不同前端要适配两种响应结构后续维护时也要先重新理解“这个模块到底遵循哪套规矩”。问题出在哪里不是 Claude Code “忘了”而是它根本没有看到。它没有长期记忆每次新对话本质上都是重新开始。所以我们需要让规范被稳定记录下来并且在每次工作时都能自动进入上下文。只有这样Claude Code 才能在不同模块、不同阶段下始终沿着同一套规则工作。这就是 SDD 和“写好提示词”之间的本质区别。写好提示词是一次性的技巧SDD 是贯穿整个项目生命周期的方法论。SDD 的完整工作流1. 先定规范规范并不一定复杂。真正有用的规范往往就集中在几个最容易让 AI 跑偏的地方。命名规范如果你不约束命名每个模块都可能长得不一样。实体类要不要加前缀字段用驼峰还是下划线接口路径用单数还是复数这些它每次都要“猜”而且每次可能猜得都不一样。实体类使用大驼峰命名不加前缀和后缀例如 Provider、Agent、ChatMessage。字段使用小驼峰命名例如 apiKey、baseUrl、modelName。接口路径统一为 /api/v1/{资源复数名}。接口规范如果你不约束返回格式问题会更明显。有的接口返回 { code: 200, data: {...} }有的返回 { error: not found }还有的直接返回 ResponseEntity。前端一接这种接口适配成本会立刻上升。所有接口统一返回 Result格式为 { code, message, data }。列表字段为空时返回空数组 []不要返回 null。分页参数统一使用 page 和 pageSize。page 从 1 开始pageSize 默认值为 20。错误码规范如果错误码没有统一规则项目很快就会乱掉。有人直接用 HTTP 状态码有人用自定义字符串也有人随手写个数字。更糟的是不同模块的错误码可能还会撞号你根本分不清 2001 到底表示 Provider 的“网络超时”还是 Agent 的“模型不存在”。错误码统一使用四位数字。按模块分段1000-1999 为通用模块。2000-2999 为 Provider 模块。3000-3999 为 Agent 模块。4000-4999 为 Chat 模块。5000-5999 为 MCP 模块。设计原则这部分往往是最关键的。Claude Code 的训练数据里有大量“最佳实践”代码所以它天然倾向于做得很“完整”工厂模式、策略模式、三层抽象、接口隔离能上的都想上。但对于一个几十人使用的内部平台来说很多设计模式并不是资产反而是负担。不引入不必要的设计模式除非有明确要求。不做过度抽象一层能解决的问题不要拆成两层。不引入技术栈之外的新依赖如有需要先确认。这几块内容加在一起可能也就一页纸。但“有规范”和“没规范”之间的差距常常不是一点点而是从“勉强可用”到“稳定可维护”的差距。2. 让 AI 按规范执行规范写好之后下达任务时要明确引用它。不是说“帮我做个 Agent CRUD”而是说按照 CLAUDE.md 中的规范实现 Agent 的 CRUD 接口。这句话的重点不只是“按照规范”这四个字。因为 CLAUDE.md 已经在上下文里Claude Code 理论上是能看到的。真正重要的是这句话在提醒它这次不要按你自己的默认经验发挥而要优先服从项目规范。有了 CLAUDE.md 之后你再回到 Agent 模块这个场景实体类会叫 Agent而不是 AgentConfig因为规范写了“不加前缀后缀”。返回格式会统一走 Result因为规范写了“统一返回结构”。错误码会从 3000 段开始因为规范写了“按模块分段”。它不会随手加上 Builder 模式因为规范写了“不引入不必要的设计模式”。同样是一个 AI有规范体系和没有规范体系最终输出的一致性会完全不同。3. 由人验证输出有了规范之后review 的效率会明显提升。因为你不再是漫无目的地看代码而是在对着一份清单逐项核查命名是不是按规范来的返回格式是否统一有没有引入你明确禁止的设计模式错误码是否落在当前模块对应的分段里规范的价值就在于它把 review 从“主观判断”变成了“客观核查”。这个转变对效率的提升非常大。你不需要每次都重新思考“这里应该怎么写”因为标准已经提前定好了。4. 持续迭代规范在验证输出的过程中你一定会不断发现规范还没覆盖到的地方。这太正常了。没有人能在第一版规范里就把所有情况都想全。关键不在于“一开始就写得完美”而在于每次发现缺口时都及时把它补上。每次 AI 跑偏不要只改代码。先停下来问自己它为什么会跑偏是不是因为规范没覆盖到如果是就补上一条。一旦这条规则被写进 CLAUDE.md后续所有对话都会受到约束。你不需要反复在同一个问题上来回纠正。它跑偏一次你补一条以后在这个点上它大概率就不会再跑偏。什么样的规范才真正有用具体而不是模糊没用的规范是这样的代码要简洁。Claude Code 对“简洁”的理解和你未必一样。它可能觉得“工厂模式 策略接口”就是一种很简洁的抽象。真正有用的规范应该像这样不引入不必要的设计模式工厂、策略、观察者等除非明确要求。每个功能都用最简单、最直接的方式实现。这句话几乎没有歧义它能明确知道工厂模式这类设计默认不能上。再比如下面这句也很空接口要规范。而真正有效的写法是所有接口统一返回 Result格式为 { code, message, data }。错误码统一为四位数字并按模块分段。判断标准其实很简单Claude Code 看到这条规范之后是否还需要“猜”你的意思如果还需要猜那它就还不够具体。有优先级不要贪多规范并不是越多越好。太多了Claude Code 也处理不过来。上下文窗口是有限的塞进太多规则反而会稀释真正重要的那几条。我的原则是AI 反复跑偏的地方写细不容易跑偏的地方少写。比如“文件编码使用 UTF-8”Claude Code 一般不会搞错不值得占太多篇幅。“Controller 不写业务逻辑”这是它经常犯错的地方就必须明确写出来。你的注意力应该放在它真正容易出错的地方。要写规则也要写原因这一点是我在做 Agent 模块时踩过坑之后才真正意识到的。在做 Agent 工具列表更新时我在指令里写了“不要全量删除再全量插入”。Claude Code 第一版还是这么做了因为它并不理解为什么这样不行。后来我补了一句解释全量删除再插入会导致并发场景下 Agent 瞬间失去所有工具关联。如果此时正好有对话在读取工具列表就会拿到空列表。第二版它就改成了差异比对的方式。这说明一件事对于涉及工程权衡的规范不能只告诉 Claude Code “不要这样做”还要告诉它“为什么不能这样做”。只有理解了约束背后的原因它才能在类似场景里举一反三而不是机械执行。当然也不是每条规范都需要解释。像“实体类不加前缀”这种规则照做就行不需要展开说明。但像“不破坏已有接口契约”“不要全量删除再插入”这种涉及系统行为和工程判断的规则一旦补上原因Claude Code 的遵循度通常会明显提升。规范也需要分层管理最后再说一下规范的组织方式。随着项目推进规范会越来越多。如果不分层管理后面一定会乱。全局规范写在 CLAUDE.md 里整个项目通用。比如命名规则、接口格式、错误码体系、设计原则、行为约束。这类规范通常在项目初期就应该定下来后面改动不会太频繁它们就是整个项目的地基。模块规范针对某个模块单独定义。比如 Provider 模块有自己的接口契约对话模块有自己的数据流定义工作流模块有自己的节点类型规范。这类内容可以写在模块目录下也可以在模块启动开发前单独补充。任务规范这是每次给 Claude Code 下达具体任务时的临时补充说明。比如这次不需要分页。这次异常要区分三种情况。这次要用差异比对不要全量替换。这类规则通常是阶段性的不一定需要沉淀成长期文档但在当前任务里依然非常重要。说到底SDD 不是让你写更多规范而是让你把那些真正关键、真正会反复影响交付质量的规则沉淀成一套稳定可复用的工作方式。当规范稳定下来之后Claude Code 才不会每次都从“猜你的想法”开始而是会一直沿着你设定好的轨道持续前进。