这两年我最大的感受是AI 编程工具已经足够强但绝大多数人用不好它问题不在模型而在方法。你有没有过这种体验——让 AI 写个功能它咔嚓一下给你吐出一大段代码能跑但你不敢改改一处崩三处加个字段就要重构。你说“帮我加个删除功能”它把整个 Service 层都给你重写了。几次下来代码比你自己写还难维护。我摸索了很久最后发现破局点不是更好的提示词而是换一套开发思路SDDSpec-Driven Development规格驱动开发。简单说就是先写清楚“软件应该做什么”再让 AI 写“怎么实现”。这套方法和 AI 编程结合起来效果比我用过的任何提示词技巧都明显。这篇文章是我这段时间的实战笔记适合正在用 AI 写代码但觉得失控的人也适合想把 AI 从“代码生成器”升级成“协作者”的开发者。1. SDD 是什么以及它为什么在 AI 时代重新被重视1.1 一句话理解 SDD 的核心思想SDD 不是什么新东西。它的核心思想就一句话先写规格后写代码。规格Spec描述的是软件的行为、输入输出、约束条件而不是具体的实现方式。传统开发里规格往往以需求文档、接口文档、设计文档的形式存在但大多数团队写文档是走过场代码写完文档就进回收站了。AI 时代把这事彻底改变了。因为 AI 写代码的依据就是你给它的文字描述。你给得越模糊它写得越随意你给得越精确它写得越贴合需求。规格说明刚好就是“精确描述”的最佳载体。换句话说SDD 过去是软件工程里的一门“纪律”现在变成了使用 AI 编程时的“杠杆”。我试过直接让 AI“写一个用户注册接口”它确实能写出来但参数命名风格、错误处理方式、返回结构每次都不一样。而当我先把接口规格写清楚包括请求字段、校验规则、响应结构、异常码定义再扔给 AI它生成的质量直接上一个台阶几乎不用返工。1.2 为什么 AI 编程让 SDD 从“文档负担”变成“核心生产力”过去写规格文档最大的问题是投入产出比低。你花三天写文档开发还不一定看看了也不一定按文档写。所以敏捷开发盛行之后大家恨不得连设计文档都省了。但 AI 编程出现后情况反过来了。第一AI 没有“直觉”。人读需求能脑补出上下文AI 只能从你给的文本里推理。规格说明就是它的“上下文”写得越完整它就越接近你心里的“标准答案”。第二AI 没有“责任心”。它不会主动问你“这个字段要不要校验”“这个异常要不要处理”你不写清楚它就默认不做。规格里写清楚每条约束它就会老老实实加上。第三AI 的产出需要验收标准。你怎么判断 AI 写的代码对不对靠测试。而规格恰恰是写测试用例的最佳蓝本。先有规格再有测试用例然后再让 AI 实现这就形成了一个完整的闭环规格指导测试测试验证代码代码反馈规格。所以我的结论是在 AI 编程工作流里规格文档不是负担而是你用来“遥控” AI 的遥控器。没有规格你只能在 AI 给的代码上拆东墙补西墙有了规格你可以在动手之前就把大部分坑填平。1.3 SDD 和 TDD、DDD 的关系别搞混既然聊到方法论顺便说一下 SDD 和另外两个常见缩写的关系。TDDTest-Driven Development测试驱动开发是先写测试再写实现重点关注“代码是否正确”DDDDomain-Driven Design领域驱动设计是先建领域模型再写代码重点关注“业务逻辑如何映射到代码”。SDD 关注的是“系统应该有什么行为”它比 TDD 更靠前一步比 DDD 更轻量、更通用。实际使用中它们并不冲突。我现在的工作流是用 SDD 写清楚行为规格然后从规格直接生成测试用例这相当于把 TDD 的“测试先行”也一起做了。至于 DDD如果项目足够复杂我才会在规格里加入领域模型描述。对小项目、原型项目来说SDD 加 AI 已经是性价比最高的组合。2. 用 SDD AI 开发软件的完整工作流2.1 五个阶段需求梳理、规格编写、任务拆分、AI 编码、验证反馈整套流程可以分成五个阶段我按平时执行的顺序列一下需求梳理把模糊的想法变成明确的功能列表。这阶段不碰任何代码只回答“系统要做什么”。我习惯用一页纸把所有功能点写下来每个功能点一句话说清楚。规格编写把功能列表变成可验证的规格。每个功能点展开成输入、处理、输出、约束、异常五部分。这是整个流程的核心阶段占的时间也最长。任务拆分把规格拆分成 AI 能够一次完成的小任务。每个任务对应一个文件、一个接口、一个组件大小控制在 AI 一次能正确完成的范围内。一个经验值是单个任务生成的代码量不超过 300 行。AI 编码把单个任务的规格作为提示词喂给 AI让它生成实现代码。这阶段需要做上下文管理必要的时候把相关文件内容也传给 AI但每次只给它看它需要的那一小部分。验证反馈运行测试、检查代码、把发现的问题反馈给 AI 修复。这个阶段要像审普通人代码一样审 AI 的代码发现问题就用带上下文的反馈让它改而不是直接手动改。这五个阶段里最容易跳过的就是第二阶段“规格编写”。很多人包括我最初觉得功能都想清楚了直接让 AI 写不就行了为什么还要多写一份文档但实际跑过一次完整流程你就知道跳过规格省下的一小时后面至少用三小时来填。AI 生成的代码会缺校验、缺边界处理、缺统一异常结构最后你花在“缝缝补补”上的时间远超写规格的时间。2.2 规格说明书怎么写一个可以直接套用的模板我写规格有一套固定模板无论项目大小都按这个来。这里用“用户注册功能”举个例子## 功能名称 用户注册 ## 功能描述 用户提供手机号、密码和昵称系统验证后创建账号并返回用户信息。 ## 输入规格 - phonestring必填11 位数字需以 1 开头 - passwordstring必填8~20 位需包含字母和数字 - nicknamestring必填1~20 个字符 ## 处理逻辑 1. 校验输入参数任一不合法则返回对应错误码 2. 检查手机号是否已注册已注册则返回错误码 REGISTERED 3. 密码使用 bcrypt 加密后入库 4. 生成用户 IDUUID和初始用户状态 ## 输出规格 - 成功返回 201响应体为 { id, phone, nickname, createdAt } - 失败返回 400响应体为 { code, message } ## 错误码 - PARAM_INVALID参数校验失败 - PHONE_REGISTERED手机号已注册 - INTERNAL_ERROR服务内部错误 ## 约束条件 - 需要在事务中处理用户创建和初始记录写入 - 密码明文禁止出现在日志中这个模板的好处是它把所有 AI 需要知道的信息都结构化地表达出来了。输入输出、错误码、约束条件每一项都是 AI 生成代码时容易遗漏或乱发挥的地方。你把这个模板填好后面不管是直接丢给 AI 生成代码还是丢给 AI 生成测试用例它都能给出高质量结果。规格不是越详细越好而是关键信息不缺失。什么是关键信息会影响代码行为的都算。比如字段是否必填、长度限制、唯一性约束、错误码定义、事务要求——这些如果不写AI 就会自己发挥而它发挥的方向往往不是你想要的。2.3 AI 编程工具怎么选通用型、IDE 插件、Agent 型工具怎么搭配规格写好了接下来要选工具。现在市面上的 AI 编程工具大致分三类我用下来各有适用场景。第一类是通用型大模型比如 ChatGPT、Claude、Kimi 这类直接在网页里对话。适合做前期规划和方案讨论。我会把规格文档贴上去问“这个模块有没有更好的设计思路”“这里还有什么边界情况我没想到”让它在“设计层面”帮我补充。这类工具的好处是对话上下文长适合一次性处理整个规格文件坏处是它对项目代码没有感知生成的代码需要你自己贴到项目里。第二类是 IDE 插件比如 GitHub Copilot、通义灵码、CodeGeeX以及 PyCharm 里的 AI Assistant。它们能读取你当前打开的文件在编辑器里直接补全代码适合在“实现阶段”用。比如根据规格提示词在编辑器里让它补全函数体、生成测试用例、修复报错。我实际用下来这类工具对“改动现有代码”的场景比通用大模型更顺手因为它能看到你项目里的真实类名、函数名、导入路径不用你反复解释。第三类是 Agent 型工具比如 Cursor、Windsurf以及基于自建流程的 AI Agent。它们能自主地读取项目目录、修改多个文件、运行命令。这类工具潜力最大也最容易翻车——如果规格不清楚它会用最“想当然”的方式把功能写出来而且一次动很多文件出问题不好排查。我的建议是Agent 型工具必须配合前面说的“小任务拆分”使用让它在明确的小范围内自主执行而不要让它一口气把一个模块全部写完。我的日常搭配是方案讨论用通用大模型单文件实现用 IDE 插件跨文件重构或批量生成测试用 Agent 型工具。工具不用多关键是你手里有一份写得足够好的规格换什么工具都好使。3. 核心实操把规格变成 AI 看得懂的提示词3.1 从规格到提示词的一个完整示例规格写完了怎么喂给 AI直接整个文档复制进去可以但效果不是最优。因为规格文档里有相当一部分是给人看的背景说明AI 需要的是“任务定义 约束条件 验收标准”这三件事。我通常会把规格转换成“任务式提示词”模板大概是这样的请实现以下功能。 【功能名称】 用户注册接口 【输入参数】 - phone: string, 必填, 11位数字, 以1开头 - password: string, 必填, 8-20位, 包含字母和数字 - nickname: string, 必填, 1-20个字符 【处理流程】 1. 参数校验失败返回 400 {code: PARAM_INVALID, message: 具体原因} 2. 手机号已注册返回 400 {code: PHONE_REGISTERED, message: 手机号已注册} 3. 密码使用 bcrypt 加密 4. 创建用户记录, 返回 201 用户信息(不含密码) 【技术栈】 - Python 3.11 - FastAPI - SQLAlchemy 2.x - MySQL 8.x 【代码风格】 - 采用依赖注入方式获取数据库会话 - 错误处理使用自定义异常 全局异常处理器 【验收标准】 1. 提供完整的接口代码 2. 包含参数校验逻辑 3. 不包含密码明文返回 4. 数据库操作包含事务处理注意几个细节。第一我把“处理流程”写成了编号列表AI 对有序列表的执行顺序理解比段落描述精确得多。第二我明确指定了“技术栈”否则它可能会用你项目里根本不存在的库。第三我写了“代码风格”这一节这能避免 AI 生成和你项目现有代码风格不一致的代码。第四“验收标准”看起来是给代码提要求的实际上也是给 AI 自己核对用的它在生成时会自动对照这些标准。3.2 让 AI 先写测试用例再写实现代码这是一个能明显提升代码质量的小技巧在让 AI 写实现代码之前先让它按规格生成测试用例。为什么因为测试用例是规格的“机器可读版本”。AI 生成测试用例的过程相当于它把规格里的每条规则都翻译成具体的断言。如果规格里某条规则写得不清楚它在生成测试用例时就会暴露出来——要么它跳过这条规则要么它用错误的理解去写断言。你检查测试用例时就能发现自己规格里的漏洞此时修正规格的成本几乎为零。等测试用例通过评审之后再让 AI 写实现代码。这个过程会顺很多因为测试用例其实已经替实现代码“探好路”了AI 会在写代码时自动去满足这些测试。具体操作时我会在提示词里加一句请先阅读以下规格生成对应的 pytest 测试用例。测试用例需要覆盖所有成功路径、失败路径和边界情况。生成时不要写实现代码。测试用例通过评审后我会再让你基于这些测试用例实现功能代码。实测下来这个“先测试后实现”的顺序能减少大概一半的返工。尤其是边界情况——比如字段长度、空值、特殊字符——AI 在写测试用例时会认真考虑而这些边界处理恰恰是直接生成代码时最容易漏掉的。3.3 上下文管理如何让 AI 始终“想”起规格约束AI 对话的上下文窗口是有限的而且会出现“聊久了就忘了前面的要求”的问题。特别是在长对话里你前面说“密码要用 bcrypt 加密”聊了半小时后它可能就给你生成一个明文存储的版本。解决这个问题有两个办法。一个是把规格文件放在项目目录里并在提示词里标注“实现前请先阅读 SPEC.md 第 2.3 节”。Cursor、Copilot 这类工具支持引用项目文件。只要规格文件在项目里AI 就能随时读取不用反复粘贴。另一个办法是每次开始一个新任务时都重新贴一遍相关的规格片段。很多人怕麻烦觉得之前说过了就不用再贴但 AI 的记忆远没有你想象的可靠。每次任务都“重置上下文”是保证它不跑偏最稳妥的方式。实际项目中我通常会在项目根目录维护一个spec/目录每个模块一个文件。AI 需要时就让它读对应文件需要针对性修改时再贴片段。这样规格既是给 AI 用的“操作手册”也是给团队看的“项目文档”一举两得。3.4 不要一开始就引入 AI Agent先手动跑通全流程关于 AI Agent我多提醒一句。如果你是第一次尝试 SDD AI 的工作流我强烈建议先在普通对话式 AI 里手动跑通一遍不要一开始就用 Agent 自动执行。原因是Agent 自动执行时你很难观察到每一步 AI 做决策的过程出了问题也不好定位是“规格不清”还是“执行错误”。手动跑一遍能让你清楚知道每个环节可能出现什么问题哪些规格写得不明确哪些任务拆得太大。等你对流程足够熟悉了再把这些经验固化到 Agent 的配置和执行逻辑里。我现在用的 Agent 流程其实是把“手动流程”自动化了读取规格文件 → 按任务清单逐项实现 → 运行测试 → 汇报结果。但它背后的规则全部是从手动实践中沉淀下来的。一上来就追求全自动往往会得到一个跑得很快但方向经常跑偏的 Agent。4. 实战记录用 SDD AI 从零开发一个待办事项 API4.1 需求与规格定义空谈方法论没用我用一个实际项目来串一遍完整流程。项目是一个待办事项 API我给它的需求定义就一句话“用户可以创建待办事项查看列表标记完成删除事项。”这个项目很小但麻雀虽小五脏俱全足够演示 SDD 的完整闭环。按照模板我写出了第一版规格。这里直接展示核心部分## 功能清单 1. 创建待办事项 2. 查看待办事项列表支持按完成状态筛选 3. 更新待办事项修改标题、标记完成 4. 删除待办事项 ## 数据模型 Todo: - id: integer, 主键, 自增 - title: string, 必填, 1~100 字符 - completed: boolean, 默认 false - created_at: datetime, 默认当前时间 ## 接口定义 ### POST /todos - 请求体: { title: string } - 成功: 201, 返回创建的 Todo - 失败: 400, title 为空或超过 100 字符时返回 {code: INVALID_TITLE} ### GET /todos?completedtrue|false - 成功: 200, 返回 Todo 数组 - completed 参数可选, 不传返回全部 ### PATCH /todos/{id} - 请求体: { title?: string, completed?: boolean }至少一个字段 - 成功: 200, 返回更新后的 Todo - 失败: 404, 不存在时返回 {code: NOT_FOUND} - 失败: 400, 请求体为空或字段不合法时返回 {code: INVALID_PARAMS} ### DELETE /todos/{id} - 成功: 204, 无响应体 - 失败: 404, 不存在时返回 {code: NOT_FOUND}关于技术栈我选择了 Python FastAPI SQLite。原因很简单项目是演示性质FastAPI 自带 OpenAPI 文档便于验证SQLite 不需要额外配置数据库服务拿到就能跑。如果你的项目是生产级的把技术栈替换成 MySQL、PostgreSQL 等流程完全一样。4.2 让 AI 生成测试用例并评审规格到位后我没有直接让 AI 写接口实现而是先让它生成测试用例。提示词大概是这样项目使用 FastAPI 和 pytest。请依据以下规格生成测试用例文件 test_todos.py。测试需要覆盖 1. 每个接口的成功路径 2. 每个接口的失败路径非法参数、不存在的 ID 等 3. 边界情况空字符串、超长 title、布尔值过滤等 不要编写实现代码只生成测试用例。测试需要能在测试数据库中独立运行。重点说下评审测试用例时我看什么。第一看它是否覆盖了所有“失败路径”——没有失败路径测试的用例集基本是摆设。第二看它的断言是不是足够严格——测试里如果只断言状态码 200 而不检查响应体内容那就没抓住规格的核心。第三看它有没有把“数据准备”和“测试逻辑”分开——这样后续维护更清晰。AI 第一次生成的测试用例通常会有 80% 能直接用剩下 20% 需要修改。比如它会用 Mock 替代真实数据库方便是方便但对这个项目来说反而复杂化了。我会直接告诉它“不要用 Mock直接使用 SQLite 临时文件作为测试数据库”它会重新生成一份更贴合项目的版本。4.3 让 AI 生成实现代码并运行测试拿到评审通过的测试用例后我下一步就是让 AI 生成实现代码。提示词依然是基于规格但会增加一条“请实现代码确保所有测试用例全部通过。”这次 AI 生成的代码质量明显就高多了。数据结构、参数校验、异常处理都规规矩矩没有出现“只写快乐路径”的老毛病。运行 pytest 之后一多半测试直接通过。剩下几个失败的都是些小问题比如 PATCH 接口的字段校验和预期不一致、DELETE 返回了 200 而不是 204、标题校验的边界条件没处理好。这些问题的共同规律是规格文档里写了但 AI 在实现时“略过了”。它看到“标题长度 1~100 字符”这个描述却不一定会在代码里真正去校验。这也是为什么我会把“验收标准”写在提示词里的原因它能一定程度降低这种情况的发生但不能完全消除。4.4 修复 bug 的正确姿势反馈回规格而不是直接改代码测试发现的这些小问题处理方式有讲究。很多人遇到 AI 代码出 bug会直接把错误信息和代码贴给 AI 说“帮我改掉”。这确实能解决问题但容易“修一个冒一个”——因为 AI 修改代码时没有全局视角它可能会在别处引入新问题。我的做法是把测试失败的详细信息包括断言、期望值、实际值反馈回去并且指出规格对应的条款编号。比如test_todos.py 中的 test_delete_todo 失败了。 规格中使用 DELETE /todos/{id}成功时返回 204当前实现返回了 200。 请对照规格第 4.5 节修正实现确保仅修改 delete 相关代码不改变其他接口行为。这样做的关键是不要让 AI 自己判断“应该是什么”而是明确告诉它“按规格应该怎样”。它就没有再自由发挥的空间了。整个修复过程迭代了两轮耗时不到十分钟就完成了全部测试通过。这个项目从开始写规格到测试全绿总共用了大约一个下午。刨掉吃饭休息纯工作时间大概三个小时其中写规格用了将近一个小时。这个“浪费”在传统开发里可能觉得不值但在 AI 编程里它就是让你“省下后面十个返工小时”的投资。5. 常见问题与排查技巧实录5.1 AI 生成代码偏离规格怎么办这是最常遇到的问题几乎每个项目都会碰上。我整理出的排查思路有三个检查规格是否写清楚了“不能做什么”。AI 最容易在“约束”上跑偏。规格里写了“title 必填”但你没写“title 为空时不能通过校验”它就会漏掉这一步校验。规格不光要写“要做什么”还要写“不允许发生什么”。检查任务是不是拆得太大。如果你让 AI 一次实现“用户注册 登录 找回密码”三个功能它很可能顾此失彼。拆小任务每个任务只解决一个功能偏离的概率会直线下降。用测试用例“框住”它。有测试用例在AI 跑偏的代价就变小了。反正测试会失败失败后再让它按反馈修正即可。5.2 规格本身写错了如何低成本修正AI 时代修改规格的成本比传统开发低得多因为改规格后只需要让 AI 同步更新测试用例和实现代码。但这里有个关键步骤修改规格时要同时修改测试用例然后让 AI 根据新测试用例重新实现。如果你只改规格不改测试测试就会成为“旧规格”的守护者阻碍新需求的落地。我自己的习惯是每个功能点都建立一个“规格条目标识”比如SPEC-2.3。当需求变更时我只需要说“更新 SPEC-2.3 的描述并同步修改测试用例”AI 就能精准定位范围而不会把不相关的功能也改掉。这个标识体系在项目变大之后特别有用否则你很难和 AI 定位“到底要改哪一部分”。5.3 上下文窗口不够用怎么管理大型规格随着项目变大规格文档会越来越长AI 的上下文窗口装不下。我的策略是**“按模块拆文件 按需加载”**。不再维护一个巨大的规格文件而是在spec/目录下按模块拆分成多个文件。每个文件只描述一个模块的行为。需要开发哪个模块就让 AI 读哪个文件。如果确实有些跨模块的公共约束比如统一的错误码规范那就单独维护一个spec/common.md在需要时一并提供给 AI。还有个小技巧规格文件头部放一个“简要说明”和“变更记录”让 AI 只读取这个文件的最近几节就能快速了解上下文而不是每次都要扫描整个文件。这能有效减少 token 消耗同时保持信息不缺失。5.4 AI 生成了“正确但没用”的代码怎么避免比“错误代码”更难发现的是“正确但没用”的代码——它语法正确、逻辑清晰但实现的东西和你真正想要的不一样。比如你让它“删除 todo”它认为“删除应该是软删除即在数据库里加一个 deleted 字段”于是在原来的表结构上增加了一列还改了查询逻辑整个改动范围超出预期。解决这个问题核心还是规格。你对“删除”如果真是“物理删除”就要在规格里明确写“DELETE 接口执行物理删除从数据库中彻底移除该记录”。如果你觉得“可能会做回收站功能”那软删除也是合理方案。规格的价值就是把这种“想当然”的空间压到最小。我的经验是在规格里专门留一节“非目标”列清楚“本模块不做 X”。比如“本模块不做用户权限区分所有请求一律视为同一用户”“本模块不做数据软删除所有删除均为物理删除”。这个反向定义的效果出奇地好AI 看到“非目标”之后基本不会再发挥多余功能。6. 热词背后的实战关联AI Agent、Spring AI 和本地部署6.1 AI Agent 为什么必须和规格绑定最近 AI Agent 这个词在开发圈里特别热很多人把 AI Agent 当成“上传需求自动出软件”的万能工具。但我用下来的感受是没有规格约束的 Agent就像没有剧本的演员自由发挥是天性但你不敢让它上台演正剧。Agent 的自主性是一把双刃剑。有规格的时候它能自动拆任务、自动写代码、自动跑测试把整个 SDD 流程变成一条流水线没规格的时候它会自作主张地设计数据模型、选择技术实现、甚至添加你没要求的功能而这些“自主行为”往往就是 bug 和返工的源头。所以我在和 Agent 协作时最先输入的不是需求描述而是规格文件本身并且明确告诉它“所有实现必须符合规格文件里的定义超出规格的部分一律不做。”这句话能把 Agent 的创造力引导到正确的方向上。6.2 Spring AI 这类框架能帮你省什么如果你的技术栈是 JavaSpring AI 是值得关注的方向。它把大模型调用、Prompt 模板、结构化输出这些能力封装成了 Spring 生态的组件让 AI 功能可以像配数据库一样配置。这和 SDD 有什么关系在我看来Spring AI 本身解决的问题是“让 AI 能力容易接入”而 SDD 解决的问题是“让 AI 输出可预期”。两者是互补的。比如你用 Spring AI 开发一个 AI 客服系统Spring AI 负责管理模型调用和上下文SDD 则负责定义客服的应答规范、话术边界、转人工条件。没有 SDD 定义这些行为Spring AI 接入得再顺客服也会乱说话。所以我的建议是框架可以用但别指望框架解决“需求不清晰”的问题。6.3 本地部署大模型SDD 会有什么变化本地部署 AI 大模型也是热门方向。成本、隐私、离线可用这些原因都好理解但从 SDD 的角度看本地模型和在线模型有个关键区别本地模型的指令跟随能力通常弱于顶级在线模型对模糊信息的容忍度更低。这反而让 SDD 的价值更突出了。本地模型更需要结构化的规格输入更需要明确的验收标准更需要小任务拆分。我用本地模型跑过同样的待办事项项目规格不清时它生成的代码比在线模型更容易“缺胳膊少腿”但规格写得足够好时它也能完成任务而且因为上下文不占在线额度可以反复试错。本地部署模型时的配置门槛显存、量化、推理框架是一个独立话题但如果你已经在折腾本地模型了我的建议是从 SDD 流程开始规格文件会让你调试模型输出的成本大幅下降。6.4 Python 开发软件的角色分工最后说回 Python。当前 AI 编程生态下Python 几乎成了事实上的标准语言原因很简单AI 训练数据里 Python 代码的占比最高所以 Python 生成质量最好同时 AI 相关的框架基础设施也主要是 Python 生态。用 SDD AI 开发软件选择 Python 能最大化 AI 编码的“战斗力”。但这不意味着 Python 项目不需要规格。恰恰相反因为 Python 的动态类型特性AI 生成代码时更容易在数据结构上“自由发挥”。我习惯在规格里额外强调数据模型和类型定义并让 AI 使用pydantic或dataclass做显式建模。这相当于把规格里的定义用代码固化下来AI 后续生成的逻辑就不会在这个基础上跑偏。7. 最后补充几个实战环节的细节心得这套流程跑了几十个项目之后我沉淀了一些零散但实用的经验一并分享在这里。第一个是关于规格文档的维护节奏。每逢需求变更我会先改规格文档再改测试用例最后才让 AI 改代码。顺序不能反。如果让 AI 先改代码测试用例还是旧逻辑就会出现“代码已实现新需求但测试还在验证旧需求”的尴尬状态。反过来先改测试用例、让测试先挂掉再实现新代码整个流程就顺理成章。第二个是关于“验收标准”的书写细节。不要写“代码质量要高”这种没法验证的描述而要写可检查的条目比如“所有数据库操作包含事务”“所有 API 返回统一的 JSON 结构”“不包含明文密码”。可验证的标准才能真正约束 AI 的行为。第三个是善用 AI 做规格本身的“评审官”。写完一份规格后我会把它丢给 AI 问“如果我是开发工程师按这份规格实现有哪些地方语义不明确有没有遗漏的异常情况”它通常能挑出几个我没想到的边界问题比如“如果 title 只有空格算不算合法输入”这类问题在写规格阶段发现并及时补充比到编码阶段让 AI 自己猜测要好得多。第四个是关于贴代码时的“圈地”意识。让 AI 修改某个文件时我会明确告诉它“只修改 XXX 函数其他代码保持不变”。这听起来像是废话但 AI 确实经常顺手把无关代码改了特别是格式化工具版本的差异会导致它重排你整个文件的代码格式。加一句“不要改动与本任务无关的代码”能减少大量无谓的 code review 消耗。还有一个小技巧每次让 AI 完成任务后让它用一句总结它做了什么、改了什么、没做什么。比如完成后请用三句话总结1. 本次做了哪些改动2. 哪些测试通过了3. 还有哪些遗留问题。这个小动作能逼着 AI 对自己的输出做一次检查很多“看起来完成其实没完成”的情况在这一步就会被暴露出来。我现在已经离不开“规格先行”这套流程了。以前让 AI 写代码像在跟一个记忆力很差的天才合作——他能写出漂亮的代码但总是忘记你 30 分钟前说过的话。现在有了 SDD他不再需要记那么多话只需要每次打开规格按文件执行。感觉就像终于拿到了这份协作者的完整说明书。如果你也想试建议从一个小项目开始不要找那种一两个接口的玩具项目而是选一个有那么三五个模块、二十来个接口的真实需求完整地把这套流程走一遍。第一次跑通的时候你可能会觉得繁琐但等你看到 AI 在规格约束下生成的代码能被测试用例完整验证那种“一切尽在掌控”的感觉就是这套方法论真正的回报。 AI编程失控？用SDD规格驱动开发重构AI协作流程
这两年我最大的感受是AI 编程工具已经足够强但绝大多数人用不好它问题不在模型而在方法。你有没有过这种体验——让 AI 写个功能它咔嚓一下给你吐出一大段代码能跑但你不敢改改一处崩三处加个字段就要重构。你说“帮我加个删除功能”它把整个 Service 层都给你重写了。几次下来代码比你自己写还难维护。我摸索了很久最后发现破局点不是更好的提示词而是换一套开发思路SDDSpec-Driven Development规格驱动开发。简单说就是先写清楚“软件应该做什么”再让 AI 写“怎么实现”。这套方法和 AI 编程结合起来效果比我用过的任何提示词技巧都明显。这篇文章是我这段时间的实战笔记适合正在用 AI 写代码但觉得失控的人也适合想把 AI 从“代码生成器”升级成“协作者”的开发者。1. SDD 是什么以及它为什么在 AI 时代重新被重视1.1 一句话理解 SDD 的核心思想SDD 不是什么新东西。它的核心思想就一句话先写规格后写代码。规格Spec描述的是软件的行为、输入输出、约束条件而不是具体的实现方式。传统开发里规格往往以需求文档、接口文档、设计文档的形式存在但大多数团队写文档是走过场代码写完文档就进回收站了。AI 时代把这事彻底改变了。因为 AI 写代码的依据就是你给它的文字描述。你给得越模糊它写得越随意你给得越精确它写得越贴合需求。规格说明刚好就是“精确描述”的最佳载体。换句话说SDD 过去是软件工程里的一门“纪律”现在变成了使用 AI 编程时的“杠杆”。我试过直接让 AI“写一个用户注册接口”它确实能写出来但参数命名风格、错误处理方式、返回结构每次都不一样。而当我先把接口规格写清楚包括请求字段、校验规则、响应结构、异常码定义再扔给 AI它生成的质量直接上一个台阶几乎不用返工。1.2 为什么 AI 编程让 SDD 从“文档负担”变成“核心生产力”过去写规格文档最大的问题是投入产出比低。你花三天写文档开发还不一定看看了也不一定按文档写。所以敏捷开发盛行之后大家恨不得连设计文档都省了。但 AI 编程出现后情况反过来了。第一AI 没有“直觉”。人读需求能脑补出上下文AI 只能从你给的文本里推理。规格说明就是它的“上下文”写得越完整它就越接近你心里的“标准答案”。第二AI 没有“责任心”。它不会主动问你“这个字段要不要校验”“这个异常要不要处理”你不写清楚它就默认不做。规格里写清楚每条约束它就会老老实实加上。第三AI 的产出需要验收标准。你怎么判断 AI 写的代码对不对靠测试。而规格恰恰是写测试用例的最佳蓝本。先有规格再有测试用例然后再让 AI 实现这就形成了一个完整的闭环规格指导测试测试验证代码代码反馈规格。所以我的结论是在 AI 编程工作流里规格文档不是负担而是你用来“遥控” AI 的遥控器。没有规格你只能在 AI 给的代码上拆东墙补西墙有了规格你可以在动手之前就把大部分坑填平。1.3 SDD 和 TDD、DDD 的关系别搞混既然聊到方法论顺便说一下 SDD 和另外两个常见缩写的关系。TDDTest-Driven Development测试驱动开发是先写测试再写实现重点关注“代码是否正确”DDDDomain-Driven Design领域驱动设计是先建领域模型再写代码重点关注“业务逻辑如何映射到代码”。SDD 关注的是“系统应该有什么行为”它比 TDD 更靠前一步比 DDD 更轻量、更通用。实际使用中它们并不冲突。我现在的工作流是用 SDD 写清楚行为规格然后从规格直接生成测试用例这相当于把 TDD 的“测试先行”也一起做了。至于 DDD如果项目足够复杂我才会在规格里加入领域模型描述。对小项目、原型项目来说SDD 加 AI 已经是性价比最高的组合。2. 用 SDD AI 开发软件的完整工作流2.1 五个阶段需求梳理、规格编写、任务拆分、AI 编码、验证反馈整套流程可以分成五个阶段我按平时执行的顺序列一下需求梳理把模糊的想法变成明确的功能列表。这阶段不碰任何代码只回答“系统要做什么”。我习惯用一页纸把所有功能点写下来每个功能点一句话说清楚。规格编写把功能列表变成可验证的规格。每个功能点展开成输入、处理、输出、约束、异常五部分。这是整个流程的核心阶段占的时间也最长。任务拆分把规格拆分成 AI 能够一次完成的小任务。每个任务对应一个文件、一个接口、一个组件大小控制在 AI 一次能正确完成的范围内。一个经验值是单个任务生成的代码量不超过 300 行。AI 编码把单个任务的规格作为提示词喂给 AI让它生成实现代码。这阶段需要做上下文管理必要的时候把相关文件内容也传给 AI但每次只给它看它需要的那一小部分。验证反馈运行测试、检查代码、把发现的问题反馈给 AI 修复。这个阶段要像审普通人代码一样审 AI 的代码发现问题就用带上下文的反馈让它改而不是直接手动改。这五个阶段里最容易跳过的就是第二阶段“规格编写”。很多人包括我最初觉得功能都想清楚了直接让 AI 写不就行了为什么还要多写一份文档但实际跑过一次完整流程你就知道跳过规格省下的一小时后面至少用三小时来填。AI 生成的代码会缺校验、缺边界处理、缺统一异常结构最后你花在“缝缝补补”上的时间远超写规格的时间。2.2 规格说明书怎么写一个可以直接套用的模板我写规格有一套固定模板无论项目大小都按这个来。这里用“用户注册功能”举个例子## 功能名称 用户注册 ## 功能描述 用户提供手机号、密码和昵称系统验证后创建账号并返回用户信息。 ## 输入规格 - phonestring必填11 位数字需以 1 开头 - passwordstring必填8~20 位需包含字母和数字 - nicknamestring必填1~20 个字符 ## 处理逻辑 1. 校验输入参数任一不合法则返回对应错误码 2. 检查手机号是否已注册已注册则返回错误码 REGISTERED 3. 密码使用 bcrypt 加密后入库 4. 生成用户 IDUUID和初始用户状态 ## 输出规格 - 成功返回 201响应体为 { id, phone, nickname, createdAt } - 失败返回 400响应体为 { code, message } ## 错误码 - PARAM_INVALID参数校验失败 - PHONE_REGISTERED手机号已注册 - INTERNAL_ERROR服务内部错误 ## 约束条件 - 需要在事务中处理用户创建和初始记录写入 - 密码明文禁止出现在日志中这个模板的好处是它把所有 AI 需要知道的信息都结构化地表达出来了。输入输出、错误码、约束条件每一项都是 AI 生成代码时容易遗漏或乱发挥的地方。你把这个模板填好后面不管是直接丢给 AI 生成代码还是丢给 AI 生成测试用例它都能给出高质量结果。规格不是越详细越好而是关键信息不缺失。什么是关键信息会影响代码行为的都算。比如字段是否必填、长度限制、唯一性约束、错误码定义、事务要求——这些如果不写AI 就会自己发挥而它发挥的方向往往不是你想要的。2.3 AI 编程工具怎么选通用型、IDE 插件、Agent 型工具怎么搭配规格写好了接下来要选工具。现在市面上的 AI 编程工具大致分三类我用下来各有适用场景。第一类是通用型大模型比如 ChatGPT、Claude、Kimi 这类直接在网页里对话。适合做前期规划和方案讨论。我会把规格文档贴上去问“这个模块有没有更好的设计思路”“这里还有什么边界情况我没想到”让它在“设计层面”帮我补充。这类工具的好处是对话上下文长适合一次性处理整个规格文件坏处是它对项目代码没有感知生成的代码需要你自己贴到项目里。第二类是 IDE 插件比如 GitHub Copilot、通义灵码、CodeGeeX以及 PyCharm 里的 AI Assistant。它们能读取你当前打开的文件在编辑器里直接补全代码适合在“实现阶段”用。比如根据规格提示词在编辑器里让它补全函数体、生成测试用例、修复报错。我实际用下来这类工具对“改动现有代码”的场景比通用大模型更顺手因为它能看到你项目里的真实类名、函数名、导入路径不用你反复解释。第三类是 Agent 型工具比如 Cursor、Windsurf以及基于自建流程的 AI Agent。它们能自主地读取项目目录、修改多个文件、运行命令。这类工具潜力最大也最容易翻车——如果规格不清楚它会用最“想当然”的方式把功能写出来而且一次动很多文件出问题不好排查。我的建议是Agent 型工具必须配合前面说的“小任务拆分”使用让它在明确的小范围内自主执行而不要让它一口气把一个模块全部写完。我的日常搭配是方案讨论用通用大模型单文件实现用 IDE 插件跨文件重构或批量生成测试用 Agent 型工具。工具不用多关键是你手里有一份写得足够好的规格换什么工具都好使。3. 核心实操把规格变成 AI 看得懂的提示词3.1 从规格到提示词的一个完整示例规格写完了怎么喂给 AI直接整个文档复制进去可以但效果不是最优。因为规格文档里有相当一部分是给人看的背景说明AI 需要的是“任务定义 约束条件 验收标准”这三件事。我通常会把规格转换成“任务式提示词”模板大概是这样的请实现以下功能。 【功能名称】 用户注册接口 【输入参数】 - phone: string, 必填, 11位数字, 以1开头 - password: string, 必填, 8-20位, 包含字母和数字 - nickname: string, 必填, 1-20个字符 【处理流程】 1. 参数校验失败返回 400 {code: PARAM_INVALID, message: 具体原因} 2. 手机号已注册返回 400 {code: PHONE_REGISTERED, message: 手机号已注册} 3. 密码使用 bcrypt 加密 4. 创建用户记录, 返回 201 用户信息(不含密码) 【技术栈】 - Python 3.11 - FastAPI - SQLAlchemy 2.x - MySQL 8.x 【代码风格】 - 采用依赖注入方式获取数据库会话 - 错误处理使用自定义异常 全局异常处理器 【验收标准】 1. 提供完整的接口代码 2. 包含参数校验逻辑 3. 不包含密码明文返回 4. 数据库操作包含事务处理注意几个细节。第一我把“处理流程”写成了编号列表AI 对有序列表的执行顺序理解比段落描述精确得多。第二我明确指定了“技术栈”否则它可能会用你项目里根本不存在的库。第三我写了“代码风格”这一节这能避免 AI 生成和你项目现有代码风格不一致的代码。第四“验收标准”看起来是给代码提要求的实际上也是给 AI 自己核对用的它在生成时会自动对照这些标准。3.2 让 AI 先写测试用例再写实现代码这是一个能明显提升代码质量的小技巧在让 AI 写实现代码之前先让它按规格生成测试用例。为什么因为测试用例是规格的“机器可读版本”。AI 生成测试用例的过程相当于它把规格里的每条规则都翻译成具体的断言。如果规格里某条规则写得不清楚它在生成测试用例时就会暴露出来——要么它跳过这条规则要么它用错误的理解去写断言。你检查测试用例时就能发现自己规格里的漏洞此时修正规格的成本几乎为零。等测试用例通过评审之后再让 AI 写实现代码。这个过程会顺很多因为测试用例其实已经替实现代码“探好路”了AI 会在写代码时自动去满足这些测试。具体操作时我会在提示词里加一句请先阅读以下规格生成对应的 pytest 测试用例。测试用例需要覆盖所有成功路径、失败路径和边界情况。生成时不要写实现代码。测试用例通过评审后我会再让你基于这些测试用例实现功能代码。实测下来这个“先测试后实现”的顺序能减少大概一半的返工。尤其是边界情况——比如字段长度、空值、特殊字符——AI 在写测试用例时会认真考虑而这些边界处理恰恰是直接生成代码时最容易漏掉的。3.3 上下文管理如何让 AI 始终“想”起规格约束AI 对话的上下文窗口是有限的而且会出现“聊久了就忘了前面的要求”的问题。特别是在长对话里你前面说“密码要用 bcrypt 加密”聊了半小时后它可能就给你生成一个明文存储的版本。解决这个问题有两个办法。一个是把规格文件放在项目目录里并在提示词里标注“实现前请先阅读 SPEC.md 第 2.3 节”。Cursor、Copilot 这类工具支持引用项目文件。只要规格文件在项目里AI 就能随时读取不用反复粘贴。另一个办法是每次开始一个新任务时都重新贴一遍相关的规格片段。很多人怕麻烦觉得之前说过了就不用再贴但 AI 的记忆远没有你想象的可靠。每次任务都“重置上下文”是保证它不跑偏最稳妥的方式。实际项目中我通常会在项目根目录维护一个spec/目录每个模块一个文件。AI 需要时就让它读对应文件需要针对性修改时再贴片段。这样规格既是给 AI 用的“操作手册”也是给团队看的“项目文档”一举两得。3.4 不要一开始就引入 AI Agent先手动跑通全流程关于 AI Agent我多提醒一句。如果你是第一次尝试 SDD AI 的工作流我强烈建议先在普通对话式 AI 里手动跑通一遍不要一开始就用 Agent 自动执行。原因是Agent 自动执行时你很难观察到每一步 AI 做决策的过程出了问题也不好定位是“规格不清”还是“执行错误”。手动跑一遍能让你清楚知道每个环节可能出现什么问题哪些规格写得不明确哪些任务拆得太大。等你对流程足够熟悉了再把这些经验固化到 Agent 的配置和执行逻辑里。我现在用的 Agent 流程其实是把“手动流程”自动化了读取规格文件 → 按任务清单逐项实现 → 运行测试 → 汇报结果。但它背后的规则全部是从手动实践中沉淀下来的。一上来就追求全自动往往会得到一个跑得很快但方向经常跑偏的 Agent。4. 实战记录用 SDD AI 从零开发一个待办事项 API4.1 需求与规格定义空谈方法论没用我用一个实际项目来串一遍完整流程。项目是一个待办事项 API我给它的需求定义就一句话“用户可以创建待办事项查看列表标记完成删除事项。”这个项目很小但麻雀虽小五脏俱全足够演示 SDD 的完整闭环。按照模板我写出了第一版规格。这里直接展示核心部分## 功能清单 1. 创建待办事项 2. 查看待办事项列表支持按完成状态筛选 3. 更新待办事项修改标题、标记完成 4. 删除待办事项 ## 数据模型 Todo: - id: integer, 主键, 自增 - title: string, 必填, 1~100 字符 - completed: boolean, 默认 false - created_at: datetime, 默认当前时间 ## 接口定义 ### POST /todos - 请求体: { title: string } - 成功: 201, 返回创建的 Todo - 失败: 400, title 为空或超过 100 字符时返回 {code: INVALID_TITLE} ### GET /todos?completedtrue|false - 成功: 200, 返回 Todo 数组 - completed 参数可选, 不传返回全部 ### PATCH /todos/{id} - 请求体: { title?: string, completed?: boolean }至少一个字段 - 成功: 200, 返回更新后的 Todo - 失败: 404, 不存在时返回 {code: NOT_FOUND} - 失败: 400, 请求体为空或字段不合法时返回 {code: INVALID_PARAMS} ### DELETE /todos/{id} - 成功: 204, 无响应体 - 失败: 404, 不存在时返回 {code: NOT_FOUND}关于技术栈我选择了 Python FastAPI SQLite。原因很简单项目是演示性质FastAPI 自带 OpenAPI 文档便于验证SQLite 不需要额外配置数据库服务拿到就能跑。如果你的项目是生产级的把技术栈替换成 MySQL、PostgreSQL 等流程完全一样。4.2 让 AI 生成测试用例并评审规格到位后我没有直接让 AI 写接口实现而是先让它生成测试用例。提示词大概是这样项目使用 FastAPI 和 pytest。请依据以下规格生成测试用例文件 test_todos.py。测试需要覆盖 1. 每个接口的成功路径 2. 每个接口的失败路径非法参数、不存在的 ID 等 3. 边界情况空字符串、超长 title、布尔值过滤等 不要编写实现代码只生成测试用例。测试需要能在测试数据库中独立运行。重点说下评审测试用例时我看什么。第一看它是否覆盖了所有“失败路径”——没有失败路径测试的用例集基本是摆设。第二看它的断言是不是足够严格——测试里如果只断言状态码 200 而不检查响应体内容那就没抓住规格的核心。第三看它有没有把“数据准备”和“测试逻辑”分开——这样后续维护更清晰。AI 第一次生成的测试用例通常会有 80% 能直接用剩下 20% 需要修改。比如它会用 Mock 替代真实数据库方便是方便但对这个项目来说反而复杂化了。我会直接告诉它“不要用 Mock直接使用 SQLite 临时文件作为测试数据库”它会重新生成一份更贴合项目的版本。4.3 让 AI 生成实现代码并运行测试拿到评审通过的测试用例后我下一步就是让 AI 生成实现代码。提示词依然是基于规格但会增加一条“请实现代码确保所有测试用例全部通过。”这次 AI 生成的代码质量明显就高多了。数据结构、参数校验、异常处理都规规矩矩没有出现“只写快乐路径”的老毛病。运行 pytest 之后一多半测试直接通过。剩下几个失败的都是些小问题比如 PATCH 接口的字段校验和预期不一致、DELETE 返回了 200 而不是 204、标题校验的边界条件没处理好。这些问题的共同规律是规格文档里写了但 AI 在实现时“略过了”。它看到“标题长度 1~100 字符”这个描述却不一定会在代码里真正去校验。这也是为什么我会把“验收标准”写在提示词里的原因它能一定程度降低这种情况的发生但不能完全消除。4.4 修复 bug 的正确姿势反馈回规格而不是直接改代码测试发现的这些小问题处理方式有讲究。很多人遇到 AI 代码出 bug会直接把错误信息和代码贴给 AI 说“帮我改掉”。这确实能解决问题但容易“修一个冒一个”——因为 AI 修改代码时没有全局视角它可能会在别处引入新问题。我的做法是把测试失败的详细信息包括断言、期望值、实际值反馈回去并且指出规格对应的条款编号。比如test_todos.py 中的 test_delete_todo 失败了。 规格中使用 DELETE /todos/{id}成功时返回 204当前实现返回了 200。 请对照规格第 4.5 节修正实现确保仅修改 delete 相关代码不改变其他接口行为。这样做的关键是不要让 AI 自己判断“应该是什么”而是明确告诉它“按规格应该怎样”。它就没有再自由发挥的空间了。整个修复过程迭代了两轮耗时不到十分钟就完成了全部测试通过。这个项目从开始写规格到测试全绿总共用了大约一个下午。刨掉吃饭休息纯工作时间大概三个小时其中写规格用了将近一个小时。这个“浪费”在传统开发里可能觉得不值但在 AI 编程里它就是让你“省下后面十个返工小时”的投资。5. 常见问题与排查技巧实录5.1 AI 生成代码偏离规格怎么办这是最常遇到的问题几乎每个项目都会碰上。我整理出的排查思路有三个检查规格是否写清楚了“不能做什么”。AI 最容易在“约束”上跑偏。规格里写了“title 必填”但你没写“title 为空时不能通过校验”它就会漏掉这一步校验。规格不光要写“要做什么”还要写“不允许发生什么”。检查任务是不是拆得太大。如果你让 AI 一次实现“用户注册 登录 找回密码”三个功能它很可能顾此失彼。拆小任务每个任务只解决一个功能偏离的概率会直线下降。用测试用例“框住”它。有测试用例在AI 跑偏的代价就变小了。反正测试会失败失败后再让它按反馈修正即可。5.2 规格本身写错了如何低成本修正AI 时代修改规格的成本比传统开发低得多因为改规格后只需要让 AI 同步更新测试用例和实现代码。但这里有个关键步骤修改规格时要同时修改测试用例然后让 AI 根据新测试用例重新实现。如果你只改规格不改测试测试就会成为“旧规格”的守护者阻碍新需求的落地。我自己的习惯是每个功能点都建立一个“规格条目标识”比如SPEC-2.3。当需求变更时我只需要说“更新 SPEC-2.3 的描述并同步修改测试用例”AI 就能精准定位范围而不会把不相关的功能也改掉。这个标识体系在项目变大之后特别有用否则你很难和 AI 定位“到底要改哪一部分”。5.3 上下文窗口不够用怎么管理大型规格随着项目变大规格文档会越来越长AI 的上下文窗口装不下。我的策略是**“按模块拆文件 按需加载”**。不再维护一个巨大的规格文件而是在spec/目录下按模块拆分成多个文件。每个文件只描述一个模块的行为。需要开发哪个模块就让 AI 读哪个文件。如果确实有些跨模块的公共约束比如统一的错误码规范那就单独维护一个spec/common.md在需要时一并提供给 AI。还有个小技巧规格文件头部放一个“简要说明”和“变更记录”让 AI 只读取这个文件的最近几节就能快速了解上下文而不是每次都要扫描整个文件。这能有效减少 token 消耗同时保持信息不缺失。5.4 AI 生成了“正确但没用”的代码怎么避免比“错误代码”更难发现的是“正确但没用”的代码——它语法正确、逻辑清晰但实现的东西和你真正想要的不一样。比如你让它“删除 todo”它认为“删除应该是软删除即在数据库里加一个 deleted 字段”于是在原来的表结构上增加了一列还改了查询逻辑整个改动范围超出预期。解决这个问题核心还是规格。你对“删除”如果真是“物理删除”就要在规格里明确写“DELETE 接口执行物理删除从数据库中彻底移除该记录”。如果你觉得“可能会做回收站功能”那软删除也是合理方案。规格的价值就是把这种“想当然”的空间压到最小。我的经验是在规格里专门留一节“非目标”列清楚“本模块不做 X”。比如“本模块不做用户权限区分所有请求一律视为同一用户”“本模块不做数据软删除所有删除均为物理删除”。这个反向定义的效果出奇地好AI 看到“非目标”之后基本不会再发挥多余功能。6. 热词背后的实战关联AI Agent、Spring AI 和本地部署6.1 AI Agent 为什么必须和规格绑定最近 AI Agent 这个词在开发圈里特别热很多人把 AI Agent 当成“上传需求自动出软件”的万能工具。但我用下来的感受是没有规格约束的 Agent就像没有剧本的演员自由发挥是天性但你不敢让它上台演正剧。Agent 的自主性是一把双刃剑。有规格的时候它能自动拆任务、自动写代码、自动跑测试把整个 SDD 流程变成一条流水线没规格的时候它会自作主张地设计数据模型、选择技术实现、甚至添加你没要求的功能而这些“自主行为”往往就是 bug 和返工的源头。所以我在和 Agent 协作时最先输入的不是需求描述而是规格文件本身并且明确告诉它“所有实现必须符合规格文件里的定义超出规格的部分一律不做。”这句话能把 Agent 的创造力引导到正确的方向上。6.2 Spring AI 这类框架能帮你省什么如果你的技术栈是 JavaSpring AI 是值得关注的方向。它把大模型调用、Prompt 模板、结构化输出这些能力封装成了 Spring 生态的组件让 AI 功能可以像配数据库一样配置。这和 SDD 有什么关系在我看来Spring AI 本身解决的问题是“让 AI 能力容易接入”而 SDD 解决的问题是“让 AI 输出可预期”。两者是互补的。比如你用 Spring AI 开发一个 AI 客服系统Spring AI 负责管理模型调用和上下文SDD 则负责定义客服的应答规范、话术边界、转人工条件。没有 SDD 定义这些行为Spring AI 接入得再顺客服也会乱说话。所以我的建议是框架可以用但别指望框架解决“需求不清晰”的问题。6.3 本地部署大模型SDD 会有什么变化本地部署 AI 大模型也是热门方向。成本、隐私、离线可用这些原因都好理解但从 SDD 的角度看本地模型和在线模型有个关键区别本地模型的指令跟随能力通常弱于顶级在线模型对模糊信息的容忍度更低。这反而让 SDD 的价值更突出了。本地模型更需要结构化的规格输入更需要明确的验收标准更需要小任务拆分。我用本地模型跑过同样的待办事项项目规格不清时它生成的代码比在线模型更容易“缺胳膊少腿”但规格写得足够好时它也能完成任务而且因为上下文不占在线额度可以反复试错。本地部署模型时的配置门槛显存、量化、推理框架是一个独立话题但如果你已经在折腾本地模型了我的建议是从 SDD 流程开始规格文件会让你调试模型输出的成本大幅下降。6.4 Python 开发软件的角色分工最后说回 Python。当前 AI 编程生态下Python 几乎成了事实上的标准语言原因很简单AI 训练数据里 Python 代码的占比最高所以 Python 生成质量最好同时 AI 相关的框架基础设施也主要是 Python 生态。用 SDD AI 开发软件选择 Python 能最大化 AI 编码的“战斗力”。但这不意味着 Python 项目不需要规格。恰恰相反因为 Python 的动态类型特性AI 生成代码时更容易在数据结构上“自由发挥”。我习惯在规格里额外强调数据模型和类型定义并让 AI 使用pydantic或dataclass做显式建模。这相当于把规格里的定义用代码固化下来AI 后续生成的逻辑就不会在这个基础上跑偏。7. 最后补充几个实战环节的细节心得这套流程跑了几十个项目之后我沉淀了一些零散但实用的经验一并分享在这里。第一个是关于规格文档的维护节奏。每逢需求变更我会先改规格文档再改测试用例最后才让 AI 改代码。顺序不能反。如果让 AI 先改代码测试用例还是旧逻辑就会出现“代码已实现新需求但测试还在验证旧需求”的尴尬状态。反过来先改测试用例、让测试先挂掉再实现新代码整个流程就顺理成章。第二个是关于“验收标准”的书写细节。不要写“代码质量要高”这种没法验证的描述而要写可检查的条目比如“所有数据库操作包含事务”“所有 API 返回统一的 JSON 结构”“不包含明文密码”。可验证的标准才能真正约束 AI 的行为。第三个是善用 AI 做规格本身的“评审官”。写完一份规格后我会把它丢给 AI 问“如果我是开发工程师按这份规格实现有哪些地方语义不明确有没有遗漏的异常情况”它通常能挑出几个我没想到的边界问题比如“如果 title 只有空格算不算合法输入”这类问题在写规格阶段发现并及时补充比到编码阶段让 AI 自己猜测要好得多。第四个是关于贴代码时的“圈地”意识。让 AI 修改某个文件时我会明确告诉它“只修改 XXX 函数其他代码保持不变”。这听起来像是废话但 AI 确实经常顺手把无关代码改了特别是格式化工具版本的差异会导致它重排你整个文件的代码格式。加一句“不要改动与本任务无关的代码”能减少大量无谓的 code review 消耗。还有一个小技巧每次让 AI 完成任务后让它用一句总结它做了什么、改了什么、没做什么。比如完成后请用三句话总结1. 本次做了哪些改动2. 哪些测试通过了3. 还有哪些遗留问题。这个小动作能逼着 AI 对自己的输出做一次检查很多“看起来完成其实没完成”的情况在这一步就会被暴露出来。我现在已经离不开“规格先行”这套流程了。以前让 AI 写代码像在跟一个记忆力很差的天才合作——他能写出漂亮的代码但总是忘记你 30 分钟前说过的话。现在有了 SDD他不再需要记那么多话只需要每次打开规格按文件执行。感觉就像终于拿到了这份协作者的完整说明书。如果你也想试建议从一个小项目开始不要找那种一两个接口的玩具项目而是选一个有那么三五个模块、二十来个接口的真实需求完整地把这套流程走一遍。第一次跑通的时候你可能会觉得繁琐但等你看到 AI 在规格约束下生成的代码能被测试用例完整验证那种“一切尽在掌控”的感觉就是这套方法论真正的回报。