1. 规范驱动开发到底是什么——先别急着写代码
过去一年，AI编程工具的进步速度有目共睹。我身边越来越多的团队开始让AI直接参与功能开发，从一开始的兴奋到后来的冷静，很多人发现一个尴尬的事实：AI写代码确实快，但代码改不动。功能上线第一个版本没问题，第二个版本需求一变，AI生成的那一坨代码就像一座豆腐渣工程——拆了可惜，留着又无法扩展。
问题出在哪？出在大家让AI写代码之前，根本没想清楚要的是什么。
这就是我想聊的规范驱动开发（Spec-Driven Development）。它不是什么高深的理论，核心就一句话：在让AI动手写代码之前，先把需求转换成一份结构化、可验证、可执行的规范文档，把规范当作整个开发流程的权威依据。AI的任务不再是“猜你想要什么然后给你写一堆代码”，而是“根据规范把设计变成实现”。
这个范式解决的根本痛点，是AI编程时代的“目标模糊”问题。传统开发里，需求文档、设计文档、代码三层之间靠人脑对齐；现在AI加入之后，如果你不给它一份足够精确的“图纸”，它就会自己脑补一份，而AI脑补的结果往往和你想要的天差地别。规范驱动开发就是把“人脑对齐”变成“文档对齐”，让需求和代码之间有一条清晰、可校验的链路。
这套做法既适合个人开发者，也适合团队协作。个人用它能让AI编程的产出质量稳定翻倍，团队用它能让多个人和多个AI Agent协作时不跑偏。接下来的内容，我会从规范设计、实操流程、避坑经验三个维度展开，全部是我自己项目里反复验证过的思路。
1.1 AI时代的“代码写得快，改得慢”困局
先复盘一下大家现在最常用的AI编程方式：丢一段需求描述给AI，让它直接生成代码。需求描述通常是这样的——“做一个任务管理系统，支持用户注册、创建任务、标记完成”。然后AI就会给你生成一个能跑的CRUD应用。
看起来很快，但陷阱藏在下一步。当你提出“任务需要支持优先级排序”“任务要分配给多个用户”“完成任务时要记录操作日志”的时候，AI给出的修改方案往往是打补丁式的：在原有代码上叠加逻辑。几次迭代下来，代码里充斥着互相冲突的条件判断，数据模型变得面目全非，原来30行能搞定的事情变成了200行绕来绕去的逻辑。
这个困局在传统开发里也存在，但AI把它放大了。原因有三点：
第一，AI没有长期记忆。它只看到你当前对话里的需求变更，看不到你最初设计时的整体意图。你让它改一个字段，它不会重新审视整个数据模型，只会机械地加字段。
第二，AI生成代码的速度太快，掩盖了设计缺失。在没有AI的时代，写200行代码需要大半天，你有充足的时间思考每一行代码为什么要这么写。现在AI几秒钟就能生成200行，你甚至连检查的时间都没有，代码就已经提交了。
第三，需求描述本身的歧义被AI“自动补全”了。同样一句“支持用户注册”，不同开发者脑子里可能有完全不同的实现：手机号注册还是邮箱注册？需不需要验证码？密码存明文还是哈希？用户名能不能重复？AI不会问你，它会替你做一个默认选择。等到线上出问题，你才发现AI替你选的方案和你预期差了十万八千里。
这三件事叠加在一起，结果就是：AI编程把“从0到1”的速度提升了一个数量级，却把“从1到100”的维护成本也提升了一个数量级。
1.2 规范驱动开发的核心逻辑：让需求先变成“可验证的契约”
规范驱动开发针对上述困境给出的解法，是把需求从“自然语言描述”变成“结构化契约”。什么叫契约？契约就是双方都认可、并且可以验证对错的条款。放在软件开发里就是：数据模型长什么样、接口输入输出是什么、业务规则有哪些边界、验收标准怎么判定。
传统敏捷开发中，需求文档经常被视为“重量级流程”的象征，但规范驱动的文档和传统需求文档有一个本质区别：传统需求文档是给人看的，规范文档是人和AI共同执行的“代码级约束”。所以它的写法不是散文，而是结构化的、带明确判断条件的、包含具体示例的。
这不是一个全新的发明，它更像是把几个已有的优秀实践——测试驱动开发（TDD）、行为驱动开发（BDD）、领域驱动设计（DDD）——在AI时代重新组合了一次。TDD用测试约束实现，BDD用行为描述拉齐业务认知，DDD用统一语言消除沟通鸿沟。规范驱动把这些融合成一份“开发前契约”，让AI在动手之前就拿到所有约束条件。
我自己的经验是，这个范式带来的最大变化不是代码质量提升了多少，而是返工率显著下降了。过去用AI写一个模块，平均要来回拉扯五六轮才能达到预期；现在规范写清楚之后，通常一两轮就能产出可用的结果。省下来的时间，远比写规范的时间多。
2. 规范文档怎么写——规范的结构设计与内容清单
很多第一次接触规范驱动开发的人，最大的困惑是“规范到底写什么”。写太细怕过度设计，写太粗又起不到约束作用。我把自己的规范文档框架整理出来，你可以直接照着套。
一份可用的开发规范，至少包含六个部分：
- 目标描述：这个模块要解决什么问题，服务的用户是谁，为什么现在要做。
- 术语表：统一关键概念的定义，防止人和AI理解偏差。比如“任务”是单条待办，还是包含子任务的复杂对象？
- 数据模型：核心实体、字段、类型、约束、关系。这是AI生成代码时最重要的参考。
- 接口契约：对外提供的功能入口，输入、输出、异常情况。
- 业务规则：满足什么条件执行什么逻辑，有哪些边界和例外。
- 验收标准：可验证的、写进自动化测试的判定条件。
这个结构不是固定的，你可以按项目类型增删。比如纯前端组件，数据模型可以弱化，但接口契约和业务规则依然需要；算法类的模块，数据模型和验收标准就是重中之重。
2.1 一个规范的“最小可用”模板
直接上一份我常用的模板，以“多用户任务管理系统”为例，这个案例后文还会用到：
# 模块规范：任务管理核心模块 ## 1. 目标描述 提供任务创建、查询、状态流转能力，支持多用户隔离。 暂不涉及提醒、定时、文件附件能力。 ## 2. 术语表 - 任务（Task）：一条最小的工作单元，拥有标题、状态、优先级。 - 状态（Status）：枚举，取值为 pending（待处理）、doing（进行中）、done（已完成）、archived（已归档）。 - 所有者（Owner）：创建任务的用户，拥有任务的全部权限。 ## 3. 数据模型 实体：Task | 字段 | 类型 | 约束 | |------|--------|----------------------------------------| | id | string | 主键，UUID格式，系统生成 | | title| string | 必填，长度 1~100 字符，去除首尾空格后不可为空 | | status| enum | 默认 pending，取值范围见术语表 | | priority| enum| 取值为 low / medium / high，默认 medium | | owner_id | string | 必填，外键关联用户实体 | | created_at | timestamp | 系统生成，不可修改 | | updated_at | timestamp | 每次更新自动刷新 | 关系说明： - 一个用户拥有多条 Task，Task 和 User 是多对一关系。 - Task 不直接关联其他业务实体。 ## 4. 接口契约 功能入口：create_task(owner_id, title, priority) - 参数校验规则：title 去除首尾空格后长度在 1~100 之间，否则抛参数错误。 - 成功返回：Task 完整对象。 - 失败情况：owner_id 不存在时抛用户不存在错误。 功能入口：list_tasks(owner_id, status_filter?) - 返回当前用户的任务列表，支持按状态过滤。 - 排序规则：优先按 priority 倒序（high > medium > low），同优先级按 created_at 倒序。 功能入口：update_task_status(task_id, owner_id, new_status) - 校验规则：只有 owner 可以更新任务状态。 - 状态流转规则：pending -> doing -> done；archived 状态只能由 done 状态转入。 - 非法流转时抛状态冲突错误。 ## 5. 业务规则 - 用户只能查看和操作自己创建的任务。 - 任务删除采用逻辑删除：实际上只将状态置为 archived。 - 系统不提供任务恢复接口，archived 是不可逆状态。 ## 6. 验收标准 - 创建任务成功后，数据库新增一条记录，所有字段符合约束。 - 空字符串 title 创建任务时返回参数错误提示。 - 超过 100 字符的 title 创建任务时返回参数错误提示。 - 非 owner 用户的更新操作返回权限错误。 - 状态从 done 回退到 pending 时返回状态冲突错误。 - list_tasks 返回结果按优先级和创建时间正确排序。 - 并发更新同一任务时，后提交的更新基于最新数据，不覆盖中间状态。注意到没有，这份规范几乎把AI“自由发挥”的空间全部堵死了。它不需要AI去猜“状态有哪些取值”“排序规则是什么”“谁能操作这个任务”，所有决策在写代码之前就已经确定。
2.2 让大模型真正“读懂”规范的三个要点
规范文档写出来了，怎么让AI最大程度地吃透它？我踩了很多次坑之后总结出三个关键原则。
原则一：结构化优先于散文。上面模板里的数据模型表格、接口契约、规则列表，都是结构化表达。大模型对表格和短句的理解准确度远高于长段落文本。散文式描述“用户只能查看自己创建的任务，并且只有创建者本人可以修改任务状态和优先级”——这种写法AI大概率会在某个角落漏掉后半句。拆成“用户只能查看和操作自己创建的任务”这种独立规则条目，被遵循的概率就高得多。
原则二：每个规则必须可验证。“用户不能乱改状态”——这句话无法验证，AI拿到它等于没拿到。“pending -> doing -> done，archived 只能从 done 转入”——这句话可以逐条写成测试用例。规范里的每一条业务规则，都应该能对应到至少一个明确的输入-输出判定。写规范的时候如果发现某条规则没法表达成可判定形式，说明规则本身还没想清楚。
原则三：用示例锚定模糊场景。有些规则边界怎么描述都有歧义，最有效的办法是直接给输入输出示例。比如排序规则，光说“按优先级和创建时间排序”，到底哪个在前？补一个示例就清楚了：现有任务A（high）、B（medium）、C（high，创建时间早于A），排序结果为C、A、B。大模型对示例的理解能力非常强，一个精准的例子往往胜过十行说明文字。
3. 从规范到代码——一次完整的实操演示
理论讲再多，不如跑一遍完整流程。接下来我用上文那个任务管理系统做一次从规范到AI生成的全程演示。这个案例是我实际项目简化出来的，里面包含了不少只有踩过坑才懂的处理细节。
3.1 案例背景与技术选型
假设我要构建一个任务管理系统的后端核心模块，技术栈选型为：Python 3.11 + FastAPI + SQLAlchemy 2.0 + SQLite（开发环境）/ PostgreSQL（生产环境）。
选这套组合没什么特别原因，就是生态成熟、AI训练语料多。这里有一个选型层面的经验：AI编程时代的技术栈选择，要优先考虑AI训练数据的覆盖度。一个冷门框架虽然技术上有优势，但大模型见过的样本少，生成的代码质量会明显下降。Python全家桶是AI生成代码质量最稳定的组合之一，因为开源社区的海量代码样本构成了它的训练基础。
3.2 与AI协作生成核心模块的分步拆解
拿到我上面那份规范文档之后，我不会一次性把它全部丢给AI让它“生成整个项目”，而是分段推进。原因在于大模型单次对话的上下文处理能力是有限的，信息量太大时它会倾向于漏掉细节。我的实操节奏是把规范拆成三个层级，逐层喂给AI。
第一层：数据模型层。我先只发送规范中的“目标描述”“术语表”“数据模型”三个部分，让AI生成SQLAlchemy模型代码。提示词大概是这样的：
请根据以下规范生成 SQLAlchemy 2.0 的模型定义代码。 [粘贴：目标描述、术语表、数据模型表格] 要求： 1. 所有字段约束必须与规范完全一致。 2. status 和 priority 使用原生 Enum 类型。 3. 模型包含 created_at 和 updated_at 字段的自动处理逻辑。 4. 只生成模型代码，不要生成其他内容。 5. 如果有你认为规范中未覆盖但必要的设计，单独注明，不要擅自加入代码。注意第5条，这是我控制AI“自作主张”的关键。默认情况下，AI会在生成代码时自作主张地加索引、加唯一约束、加默认值。这些添加可能是合理的，但也可能改变业务行为。要求AI单独注明它的额外设计，能让你保留决策权。
第二层：接口层。模型生成并人工review通过后，我发送规范中的“接口契约”和“业务规则”部分，让AI生成FastAPI路由和服务层代码。这次我会在提示词里补充一些模型层已经确定的信息，避免AI生成接口代码时猜测模型字段。
第三层：测试层。最后，我发送“验收标准”部分，让AI生成对应的pytest测试。这一步很关键，它不只是验证AI生成的代码，更是验证你写的规范本身。验收标准覆盖不全的地方，测试跑完马上就会暴露出来。
3.3 把约束写进提示词的三个技巧
上面这个流程里，提示词的写法直接影响AI产出的质量。分享几个我自己验证过有效的写作技巧。
技巧一：让AI“复述规范”再开工。在要求AI生成代码之前，先加一句“请先用自己的话复述规范中的关键约束，再开始编码”。这个做法能强制AI把规范过一遍脑子，实际效果是，AI生成的代码对规范中细节条目的遵循率显著提升。如果AI复述时出现了和规范不一致的地方，说明它在理解上就有偏差，这时候让它直接写代码等于制造bug。
技巧二：指定“只生成代码，不要注释解释”。很多AI默认会给生成代码添加大量注释，这本身没毛病，但当代码量大时，注释会稀释输出长度，导致AI生成的代码不完整。我一般分两轮：第一轮让AI“只生成完整代码不要注释”，第二轮再让AI“为代码补充必要的注释和文档字符串”。这样分工更明确，两轮的输出质量都比一轮混着干要高。
技巧三：用“验收标准”做第二轮校验。AI生成完代码后，不要急着改代码，而是把验收标准原封不动发给它，让它逐条对照自己生成的代码，指出哪些验收标准没有被满足。这一步相当于让AI自己做一次code review。很多时候AI能直接发现自己漏掉了某个边界判断，并在回复里给出修正建议。省掉了你逐条看代码的时间。
3.4 把验收标准变成自动化测试
规范驱动开发和传统开发的另一个重要区别是：验收标准不是在代码完成之后才补写的，而是和规范文档同生命周期。规范定稿的那一刻，测试用例的基本框架就已经定了。
还是以上文的验收标准为例。我让AI生成的测试长这样：
def test_create_task_success(): # 准备一个合法的 owner_id 和 title result = task_service.create_task(owner_id="user_123", title="写周报", priority="high") assert result.id is not None assert result.status == "pending" assert result.priority == "high" assert result.owner_id == "user_123" def test_create_task_empty_title_raises_error(): with pytest.raises(ParameterError): task_service.create_task(owner_id="user_123", title=" ", priority="medium") def test_create_task_title_too_long_raises_error(): long_title = "一" * 101 with pytest.raises(ParameterError): task_service.create_task(owner_id="user_123", title=long_title, priority="medium") def test_update_status_by_non_owner_rejected(): # 任务属于 user_123，user_456 尝试更新状态 task = task_service.create_task(owner_id="user_123", title="写周报", priority="medium") with pytest.raises(PermissionError): task_service.update_task_status(task.id, owner_id="user_456", new_status="doing") def test_update_status_backward_rejected(): task = task_service.create_task(owner_id="user_123", title="写周报", priority="medium") task_service.update_task_status(task.id, owner_id="user_123", new_status="doing") task_service.update_task_status(task.id, owner_id="user_123", new_status="done") with pytest.raises(StatusConflictError): task_service.update_task_status(task.id, owner_id="user_123", new_status="pending") def test_list_tasks_sorted_by_priority_then_created_at_desc(): task_service.create_task(owner_id="user_123", title="低优先级旧任务", priority="low") task_service.create_task(owner_id="user_123", title="高优先级新任务", priority="high") task_service.create_task(owner_id="user_123", title="高优先级旧任务", priority="high") tasks = task_service.list_tasks(owner_id="user_123") titles = [t.title for t in tasks] assert titles == ["高优先级旧任务", "高优先级新任务", "低优先级旧任务"]注意，验收标准里最后一条“并发更新同一任务时不覆盖中间状态”在这个测试集里没有覆盖到，因为它本身是需要专门的并发测试手段的。我在规范里写“并发”两个字其实是不够严谨的——规范的表述本身就是可验证的，如果你没法写出一页纸以内的测试来覆盖它，说明这条规范本身的粒度还需要再打磨。
这套测试跑下来，如果全绿，说明AI生成的代码基本符合规范；如果有红，说明要么规范有遗漏、要么AI没理解透。但无论哪种情况，问题的定位都变得非常清晰——不是“代码哪里写错了”这种模糊问题，而是“哪条规范没有被满足”这种精确问题。
4. 常见问题与排查技巧——规范驱动落地中的坑
规范驱动开发不是你今天看了文章、明天就能顺畅跑起来的。我在项目里实践了大半年，踩过不少坑，有些坑几乎是每个初次尝试的人都会遇到的。我把它们整理成几个典型问题，按频率从高到低排列。
4.1 AI频繁偏离规范？问题八成出在规范本身
这是实践中最常见的问题。开发者辛辛苦苦写好了规范，然后让AI生成代码，结果AI产出的东西有一半不符合要求。第一反应是怪AI不够聪明，但排查一圈下来，问题通常出在规范里写了一些大模型难以解析的“模糊表达”。
举几个我在code review中看到的反例：
- “确保数据安全”——什么叫安全？怎么验证？AI会自行理解为加密码、加权限、加校验，但它不知道你的“安全”指的是什么。
- “性能要好”——多好算好？完全无法验证。
- “正当情况下……”“尽量……”“等等”——这些口语化的修饰词，放在规范里就是让AI自由发挥的许可。
所以，每一次AI偏离规范，都应该当作一次规范本身的bug来处理。修复方式不是重新生成代码，而是把那条模糊的规范改写成不带任何主观色彩的、可判定的表述。比如“数据安全”可以改成“密码字段必须经过bcrypt哈希，禁止明文存储；Token有效期24小时后必须过期并强制重新登录”。比如“性能要好”可以改成“普通列表查询必须在100毫秒内返回”。
这个过程有点像一个新员工入职之后的磨合期——你每发现一次他的理解偏差，就修正一次你的表达方式。几轮之后，你说的话他会越来越准确地执行。
4.2 规范文档失控：写得太厚、没人看、腐化快
规范驱动开发的另一个常见问题是：规范文档越写越长，最后变成了一个谁也不想看的巨型文档。尤其在团队协作场景，异步更新、接口调整之后，规范文档经常忘了同步，最后变成一份和代码不一致的僵尸文档。
我应对这个问题的方式是：规范不是一次写完的，而是按需增长的，并且在模块开发完成后立刻“固化”。
所谓按需增长，是指刚开始只需要写“数据模型、接口契约、业务规则、验收标准”四个核心部分，目标、术语表等内容等有争议了再补充。一上来就写全所有部分，大概率浪费大量时间在还没出现的问题上。
“固化”指的是，当某个模块已经开发完成、测试通过、功能上线之后，就把该模块的规范文档冻结，不再随意修改。后续要新加功能，写新的增量规范，而不是回头改旧规范。旧规范沉淀下来做知识库，新规范用于指导后续开发。这就像版本管理一样，让规范文档永远是“当下的、可用的”，而不是“堆砌了太多历史包袱的”。
4.3 团队协作：谁负责维护规范，谁负责审核AI产物
规范驱动在一个人独立开发时推进很容易，但到了团队协作场景，就涉及一个绕不开的问题：规范由谁写？AI产物由谁审？
我看到的成功案例，通常有一个“规范负责人（Spec Owner）”角色。这个人不一定技术最强，但一定是业务理解最深的。他负责收集各方需求、把模糊的业务想法翻译成可验证的规范条款。在规范驱动的范式里，写规范就是做设计，这个角色应该由原来的系统架构师或技术负责人来承担。
AI产物的审核责任则应该落在所有开发者身上，但它和管理规范是脱开的。每个开发者拿到AI生成的代码，他的review重点就是“对照规范逐条检查”，而不是“整体判断代码风格好不好”。这能显著降低review的认知负担——你不需要从头到尾理解一段几百行的代码的每个细节，你只需要检查它是否满足规范列出的那些判定条件。这也是规范驱动的隐藏红利之一：它让code review变成了打勾检查。
4.4 与AI Agent和自动化测试的联动
现在很多团队开始引入AI Agent来做自动化编码和缺陷修复。规范驱动开发和AI Agent几乎是天生一对。我实践过的一个比较顺的流程是：把规范文档作为Agent的“系统提示词”的一部分，Agent在动手编码之前先按规范生成一份“实现计划”，经过人工确认后再写代码；写完代码之后，Agent自己运行测试，如果不通过就基于错误信息迭代修改。
这个闭环的好处是，Agent的每一次代码迭代都有了明确的“正确目标”——不是模糊的“让测试通过”，而是“满足规范中的所有约束条件”。如果规范里清晰定义了状态流转、边界条件、异常处理，Agent自己就能发现并修复代码问题。
同时，多AI协作的趋势也在往这个方向走。比如规划Agent负责拆解规范为具体任务，编码Agent负责实现，测试Agent负责验证。这个时候，规范就变成了多个Agent之间的“通信协议”，是它们分工协作、互相验证的共同基准。哪个Agent产出有问题，对照规范立刻就能定位，不会出现“你写的bug我接不住”的情况。
5. 从规范到知识资产——规范驱动带来的额外收益
上面聊的都是规范驱动怎么提高开发效率和代码质量。但在我实际用下来之后，发现它的价值远不止于此。规范驱动的过程中沉淀下来的文档，正在变成一个团队最重要的知识资产。
首先，规范文档是新人的最佳入职教材。传统团队带新人，一般是给他指几个代码文件让他自己看，或者老员工花几小时口头讲一遍。我现在的做法是：直接把相关模块的规范文档丢给新人，让他先做一次“规范review”，提出任何他不理解或有疑问的地方。这样新人花1个小时读完规范，对这个系统的理解可能比读三天代码还要快——因为他直接看到的是设计意图，而不是一堆被各种commit打磨得面目全非的代码痕迹。
其次，规范文档可以逆向输出为产品文档和测试用例文档。接口契约那一节基本可以直接扩充成API文档；验收标准那一节就是现成的测试计划。我试过用规范文档自动生成部分API文档，省下了不少重复劳动。
最后，规范文档在AI时代是非常值得做“向量化”处理的知识库。你可以把自己的历史模块规范全部导入到知识库系统里，当新需求来的时候，AI可以检索历史类似模块的规范，作为新规范设计的参考。这个东西用起来之后，团队内部的“设计风格”会趋向一致，因为你每一次写新规范都是在复用和微调旧规范，而不是从零开始。设计一致性又会反向降低代码维护成本，形成正向循环。
规范驱动开发看起来多了一道写文档的工序，但它省掉的，是AI生成代码之后反复调试、返工、打补丁的大量无效时间。以我实际的度量结果来说，引入这个范式之后，一个中等复杂度模块从需求确认到上线，总工时反而缩短了大约30%——因为浪费在工作循环上的时间大幅减少了。
6. 结尾：一点个人体会
最后聊一点我自己的感受。刚开始尝试规范驱动开发的时候，我最大的抵触感来自“写规范多花的时间值不值得”。每次需求来了，我脑子里已经知道大概要怎么实现了，恨不得马上让AI把代码生成出来。
但几次项目过去之后，我的感受彻底变了。规范驱动那种“先想清楚再动手”的节奏，逼迫你在写代码之前把每个模糊地带都过一遍脑子——这个用户真的需要这个功能吗？这个状态流转真的合理吗？这些边界情况真的能接受吗？这些思考其实在传统开发里也存在，区别在于，传统开发里它们藏在你的脑子里，AI时代它们必须被写出来。
因为AI不会替你思考，它只会替你执行。你写不出来的思考，就会被AI的默认值填上。所以我现在写代码的过程，反而是先花半小时写规范，再花半小时让AI按照规范写代码，最后花十五分钟review和测试。“写代码”的时间看起来变短了，但产出的代码质量和可维护性，比原来直接让AI放飞自我写的版本高了不止一个档次。
如果你想在自己的项目里试试这个范式，我的建议是从一个小模块开始。不用追求一上来就写完美规范，先把核心的数据模型、接口契约、业务规则、验收标准这四块写清楚，让AI实现一次，用测试验证一遍，然后回头看一下——对比你平时直接让AI写代码的结果，你很快就能感受到区别。
