OpenSpec规格驱动开发：终结AI编码随机性，实现按图施工

1. 为什么“凭感觉写代码”这件事必须被终结

过去一年多，我几乎把市面上能叫得上名字的 AI 编码工具都折腾了一遍。从最早的代码补全插件，到后来的对话式编程助手，再到能自主规划任务的智能体框架，体验确实在飞速进化。但有一个问题始终像鞋里的沙子一样硌脚：AI 写出来的代码，质量极不稳定。同一个需求，今天生成的代码结构清晰、边界处理得当，明天可能就给你埋一个空指针异常，或者把业务逻辑写反。你没法跟它讲道理，因为它每次的“理解”都建立在概率之上，而不是建立在一份明确的、可追溯的契约之上。

这就是OpenSpec想要解决的核心痛点。它提出的规格驱动开发（SDD，Specification-Driven Development）理念，说白了就是一句话：在让 AI 动手写代码之前，先把“要做什么”和“做成什么样”用结构化的规格文档固定下来。这份规格文档不是给人看的普通需求文档，而是 AI 能直接解析、校验、执行的“施工图纸”。OpenSpec 就是这套图纸的格式标准、解析引擎和协作框架。

我最初接触 OpenSpec 的时候，心里是犯嘀咕的。因为“先写文档再写代码”这件事，在传统软件工程里已经被喊了几十年，但真正落地的时候往往变成走过场。需求文档写完就锁进文件夹，代码该怎么写还是怎么写。但 OpenSpec 不一样的地方在于，它的规格文档是机器可读、可校验、可生成测试用例的。AI 编码助手拿到这份规格之后，不再是“猜你想要什么”，而是“按合同办事”。这个转变，直接把 AI 编码从“抽卡游戏”变成了“按图施工”。

这篇文章适合谁看？如果你是一个正在用 AI 辅助编码的开发者，被 AI 的“随机性”折磨过；如果你是一个技术团队的负责人，想让 AI 生成的代码能进入生产环境而不是只停留在 demo 阶段；如果你是一个对 SDD 理念感兴趣但不知道从何下手的工程师，那这篇内容就是为你准备的。我会从设计思路、核心概念、实操流程、踩坑经验四个维度，把 OpenSpec 这套东西拆开揉碎讲清楚。

2. OpenSpec 的整体设计思路与核心概念拆解

2.1 从“提示词工程”到“规格工程”的范式转移

大多数人用 AI 编码的方式是这样的：打开对话框，敲一段自然语言描述，比如“帮我写一个用户登录接口，要校验手机号和密码，返回 token”。然后 AI 噼里啪啦生成一堆代码，你复制粘贴，跑一下，报错了，再回去跟 AI 说“这里不对，改一下”。这个循环里，所有的约束都藏在你的脑子里和临时的对话上下文里。一旦对话轮次多了，上下文窗口被挤爆，AI 就开始遗忘之前的约定，生成的东西越来越离谱。

OpenSpec 的思路是把这些约束外化、结构化、持久化。它定义了一套规格描述格式，通常以 YAML 或 JSON 为载体，里面明确写清楚：这个模块的输入是什么、输出是什么、有哪些边界条件、错误码怎么定义、依赖哪些外部服务、性能指标要求是多少。这份规格文件独立于对话存在，每次让 AI 生成代码时，都把这份规格作为“最高指令”喂给它。AI 不需要猜，只需要照着规格逐条实现。

这个转变的意义在于：提示词工程是临时的、模糊的、不可复用的，而规格工程是持久的、精确的、可版本控制的。你可以把规格文件提交到 Git 仓库，可以 review，可以 diff，可以回滚。AI 生成的代码如果不符合规格，你可以拿规格文件当“测试用例”去校验它。这就把 AI 编码从“黑盒艺术”拉回到了“白盒工程”的轨道上。

2.2 OpenSpec 规格文件的核心结构

我拿一个实际项目里的规格文件来举例。假设我们要做一个“优惠券核销”的功能，OpenSpec 的规格文件大概长这样：

spec_version: "1.0" module: coupon_redemption description: "优惠券核销服务" inputs: - name: coupon_code type: string required: true pattern: "^[A-Z0-9]{12}$" description: "12位大写字母数字组合的优惠券码" - name: user_id type: integer required: true min: 1 description: "用户唯一标识" - name: timestamp type: integer required: true description: "请求时间戳，秒级" outputs: success: code: 0 data: discount_amount: "integer, 单位分" remaining_uses: "integer, 剩余可用次数" errors: - code: 40001 condition: "coupon_code 格式不匹配" message: "优惠券码格式错误" - code: 40002 condition: "coupon 不存在或已过期" message: "优惠券不可用" - code: 40003 condition: "user_id 与 coupon 绑定用户不一致" message: "无权使用该优惠券" constraints: - "同一 coupon_code 并发核销必须保证幂等" - "核销操作必须在 200ms 内完成" - "数据库事务隔离级别不低于 Read Committed" dependencies: - service: user_service endpoint: "/api/v1/users/{user_id}/status" timeout: 100ms - service: coupon_db table: "coupon_records" operation: "SELECT ... FOR UPDATE"

这份规格文件里，每一个字段都有明确的类型、约束和语义。AI 拿到这份文件之后，它要做的事情就变成了“翻译”：把 YAML 里的每一条约束翻译成对应的代码逻辑。pattern对应正则校验，min对应边界检查，errors对应异常分支，constraints对应并发控制和事务注解。整个过程是可验证的：你可以写一个测试脚本，逐条检查生成的代码是否满足了规格里的每一条要求。

2.3 为什么选择 YAML 而不是自然语言

有人可能会问：我直接用中文写一段详细的需求描述不行吗？为什么要搞一套 YAML 格式？这个问题我一开始也想过，后来在实际项目里对比了两种方式，差距非常明显。

自然语言描述的问题在于歧义性。你写“优惠券码格式错误”，AI 可能理解为“长度不对”，也可能理解为“包含非法字符”，还可能理解为“大小写不对”。不同轮次的生成结果可能采用不同的校验逻辑。而 YAML 里的pattern: "^[A-Z0-9]{12}$"是无歧义的，正则表达式就是正则表达式，AI 没有发挥空间，只能照搬。

另一个问题是可校验性。自然语言描述没法自动校验，你只能靠人眼去看 AI 生成的代码对不对。而 YAML 规格可以写一个校验器，自动检查生成的代码里是否包含了对应的正则、是否处理了所有错误码、是否加了事务注解。这就把“人工 review”变成了“自动校验”，效率提升不是一点半点。

还有一个隐性好处是团队协作。当规格文件成为团队共识的载体时，后端、前端、测试、产品都可以基于同一份规格文件工作。前端可以根据outputs定义来 mock 接口，测试可以根据errors定义来写用例，产品可以根据description来确认需求理解是否一致。这份文件成了团队沟通的“单一事实来源”。

3. 核心细节解析与实操要点

3.1 规格文件的粒度控制：多细才算够

这是我在实际使用 OpenSpec 时踩过的第一个坑。一开始我写规格文件，恨不得把每一行代码的逻辑都写进去，结果规格文件比代码还长，维护成本极高。后来我调整了策略，总结出一个原则：规格文件只描述“契约”，不描述“实现”。

什么叫契约？就是调用方和被调用方之间的约定。输入是什么、输出是什么、异常怎么抛、性能指标是多少、并发安全怎么保证。这些是契约。至于内部是用哈希表还是红黑树、是先查缓存还是先查数据库、日志打在哪一行，这些是实现细节，不应该写进规格文件。

举个例子，上面那个优惠券核销的规格里，我写了constraints: "同一 coupon_code 并发核销必须保证幂等"，但我没有写“用 Redis 分布式锁实现”或者“用数据库唯一索引实现”。因为这是实现层面的选择，AI 可以根据项目现有的技术栈自行决定。如果我强行指定了实现方式，反而限制了 AI 的发挥空间，也增加了规格文件和具体项目耦合的风险。

提示：规格文件的粒度以“一个中级工程师看完之后能写出符合预期的代码”为标准。如果看完规格还需要猜，说明粒度太粗；如果看完规格发现连变量命名都定死了，说明粒度太细。

3.2 错误码体系的设计技巧

错误码是规格文件里最容易写乱的部分。我见过有的项目，错误码从 40001 排到 40099，但没有任何规律，查一个错误码要翻半天文档。在 OpenSpec 的实践里，我建议采用分段编码的方式。

具体来说，把错误码分成几个区间：1xxxx 表示参数校验错误，2xxxx 表示权限认证错误，3xxxx 表示业务逻辑错误，4xxxx 表示外部依赖错误，5xxxx 表示系统内部错误。每个区间内再按模块细分。这样 AI 在生成代码时，看到错误码就能推断出应该抛什么类型的异常，应该记录什么级别的日志，应该返回给前端什么样的提示。

另外，错误码的condition字段一定要写清楚触发条件，而不是错误现象。比如写condition: "coupon_code 格式不匹配"就比写condition: "优惠券码错误"要好得多。因为前者是明确的判断条件，AI 可以直接翻译成if (!pattern.test(couponCode))，后者则需要 AI 去猜什么算“错误”。

3.3 约束条件的表达方式

constraints字段是 OpenSpec 里最灵活也最难写的部分。它描述的是那些“不是输入输出、但必须满足”的要求。比如性能指标、并发安全、事务隔离级别、幂等性、限流阈值等等。

写约束条件的时候，我总结了一个“三要素”原则：可量化、可验证、可实现。可量化是指不能用“尽快返回”这种模糊表述，要用“200ms 内完成”。可验证是指能写出对应的测试用例，比如“并发 100 次核销同一张券，最终只有一次成功”。可实现是指当前技术栈能搞定，不能写“保证 100% 不丢消息”这种物理上做不到的事情。

我见过一个反例，有人在规格里写constraints: "系统必须高可用"。这种约束写了等于没写，AI 看了也不知道该怎么做。正确的写法应该是constraints: "单节点故障时，服务降级时间不超过 5 秒，降级期间返回缓存数据"。这样 AI 就知道要实现熔断降级逻辑，要引入缓存，要配置超时时间。

3.4 依赖声明的边界

dependencies字段用来声明这个模块依赖了哪些外部服务或数据表。这个字段的价值在于，它让 AI 知道哪些东西是它不能改的。比如你声明了依赖user_service的/api/v1/users/{user_id}/status接口，AI 就不会去重新实现一个用户状态查询逻辑，而是直接调用这个接口。

这里有个细节要注意：依赖声明里最好带上超时时间和降级策略。因为 AI 在生成代码时，如果看到依赖没有超时设置，它可能会生成一个没有超时控制的调用，这在生产环境里是致命的。我通常会在规格里写timeout: 100ms，然后 AI 就会自动加上超时处理和降级逻辑。

4. 完整实操流程：从零搭建一个 SDD 工作流

4.1 环境准备与工具链选型

要跑通 OpenSpec 这套流程，你不需要安装什么特别复杂的工具。核心工具就三个：一个支持自定义指令的 AI 编码助手（比如 Cursor、Windsurf、或者开源的 Continue）、一个 YAML 校验器（比如yamllint）、一个测试框架（比如 pytest 或 jest）。如果你用的是 Go 语言，那go test就够了。

我自己的技术栈是 Go + OpenSpec + Cursor。选 Go 的原因很简单：Go 的静态类型和显式错误处理，跟 OpenSpec 的规格驱动理念天然契合。规格里定义的每个错误码，在 Go 里都能对应到一个具体的 error 类型；规格里定义的每个输入约束，在 Go 里都能对应到一个结构体 tag。这种一一对应的关系，让校验变得非常容易。

工具链的配置也很简单。在项目根目录下建一个specs/文件夹，里面按模块存放 YAML 规格文件。然后在 AI 编码助手的系统提示词里加一段指令：“当用户要求生成或修改代码时，优先读取specs/目录下对应的规格文件，严格按照规格文件中的定义生成代码。如果规格文件不存在，提醒用户先创建规格文件。”

这段指令是整个工作流的“开关”。加上它之后，AI 的行为模式会发生明显变化：它不再急于给你写代码，而是先问你“这个模块的规格文件在哪里”。如果没有，它会引导你先写规格。这个引导过程本身就有价值，因为它强迫你在动手之前把需求想清楚。

4.2 编写第一份规格文件

我拿一个真实的例子来演示。假设我们要做一个“短链接生成服务”，需求是：传入一个原始 URL，返回一个短码；访问短码时重定向到原始 URL。这个需求看起来简单，但如果不写规格，AI 可能会给你生成一个没有过期时间、没有防重复、没有并发控制的版本。

第一步，创建specs/shortlink.yaml：

spec_version: "1.0" module: shortlink_service description: "短链接生成与跳转服务" inputs: - name: original_url type: string required: true max_length: 2048 pattern: "^https?://.+" description: "原始 URL，必须以 http:// 或 https:// 开头" - name: expire_seconds type: integer required: false default: 86400 min: 60 max: 2592000 description: "过期时间，单位秒，默认 24 小时" outputs: success: code: 0 data: short_code: "string, 6位 Base62 编码" short_url: "string, 完整短链接" expire_at: "integer, 过期时间戳" errors: - code: 10001 condition: "original_url 为空或格式不匹配" message: "URL 格式错误" - code: 10002 condition: "original_url 长度超过 2048" message: "URL 过长" - code: 30001 condition: "短码生成冲突且重试 3 次仍失败" message: "系统繁忙，请稍后重试" constraints: - "同一 original_url 在 1 小时内重复提交，返回相同短码" - "短码生成必须保证全局唯一" - "生成操作必须在 50ms 内完成" - "跳转操作必须在 20ms 内完成" dependencies: - service: redis purpose: "缓存短码到原始 URL 的映射" timeout: 10ms - service: mysql table: "shortlink_records" operation: "INSERT ... ON DUPLICATE KEY UPDATE"

这份规格文件写完之后，我把它交给 AI，指令是：“根据 specs/shortlink.yaml 生成 Go 代码，包括 handler、service、repository 三层。”

4.3 AI 生成代码的校验与修正

AI 生成的代码大概长这样（我截取核心部分）：

func (s *ShortlinkService) Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error) { if req.OriginalURL == "" || !urlPattern.MatchString(req.OriginalURL) { return nil, NewAppError(10001, "URL 格式错误") } if len(req.OriginalURL) > 2048 { return nil, NewAppError(10002, "URL 过长") } if req.ExpireSeconds == 0 { req.ExpireSeconds = 86400 } if req.ExpireSeconds < 60 || req.ExpireSeconds > 2592000 { return nil, NewAppError(10001, "过期时间参数错误") } // 检查是否已有相同 URL 的短码 existing, err := s.repo.FindByURL(ctx, req.OriginalURL) if err == nil && existing != nil && time.Now().Unix()-existing.CreatedAt < 3600 { return &GenerateResponse{ ShortCode: existing.ShortCode, ShortURL: s.buildShortURL(existing.ShortCode), ExpireAt: existing.ExpireAt, }, nil } // 生成短码，最多重试 3 次 var shortCode string for i := 0; i < 3; i++ { shortCode = generateBase62(6) err = s.repo.Insert(ctx, shortCode, req.OriginalURL, req.ExpireSeconds) if err == nil { break } if !isDuplicateError(err) { return nil, err } } if err != nil { return nil, NewAppError(30001, "系统繁忙，请稍后重试") } return &GenerateResponse{ ShortCode: shortCode, ShortURL: s.buildShortURL(shortCode), ExpireAt: time.Now().Unix() + int64(req.ExpireSeconds), }, nil }

这段代码基本符合规格，但有一个问题：规格里写了constraints: "生成操作必须在 50ms 内完成"，但 AI 生成的代码里没有超时控制。如果数据库查询慢了，这个函数可能会阻塞很久。我手动加了一个context.WithTimeout包裹整个逻辑，确保 50ms 内必须返回。

这个例子说明了一个重要问题：AI 不会自动实现所有约束，尤其是性能相关的约束。因为性能约束不像输入校验那样有明确的代码模式，AI 需要理解“50ms 内完成”意味着要加超时控制、要避免慢查询、要减少网络往返。所以我在实操中养成了一个习惯：每次 AI 生成代码后，我都会拿规格文件逐条对照，特别是constraints字段，看看有没有遗漏。

4.4 自动化校验脚本的编写

人工对照规格检查代码，做一两次还行，做多了就烦了。所以我写了一个简单的校验脚本，用 Python 实现，核心逻辑是：解析 YAML 规格文件，提取所有错误码和约束条件，然后在生成的代码里搜索对应的字符串。

import yaml import re import sys def validate(spec_path, code_path): with open(spec_path) as f: spec = yaml.safe_load(f) with open(code_path) as f: code = f.read() errors = [] # 检查所有错误码是否都在代码中出现 for err in spec.get('outputs', {}).get('errors', []): code_str = str(err['code']) if code_str not in code: errors.append(f"错误码 {code_str} 未在代码中找到") # 检查输入约束是否体现 for inp in spec.get('inputs', []): if 'pattern' in inp: if inp['pattern'] not in code: errors.append(f"输入 {inp['name']} 的正则约束未找到") if 'max_length' in inp: if str(inp['max_length']) not in code: errors.append(f"输入 {inp['name']} 的长度约束未找到") # 检查约束条件中的关键词 for constraint in spec.get('constraints', []): if '超时' in constraint or 'ms' in constraint: if 'WithTimeout' not in code and 'context.WithTimeout' not in code: errors.append(f"约束 '{constraint}' 可能缺少超时控制") return errors if __name__ == '__main__': errs = validate(sys.argv[1], sys.argv[2]) if errs: for e in errs: print(f"[FAIL] {e}") sys.exit(1) print("[PASS] 所有规格校验通过")

这个脚本很粗糙，但已经能拦住大部分低级问题了。比如 AI 忘了处理某个错误码、忘了加正则校验、忘了加超时控制，脚本都能检测出来。我把它挂在 CI 流程里，每次提交代码自动跑一遍，不通过就卡住。这样一来，规格文件就成了真正的“合同”，AI 生成的代码必须满足合同才能合并。

5. 常见问题与排查技巧实录

5.1 规格文件与代码不同步怎么办

这是 SDD 实践中最常见的问题。需求变了，规格文件更新了，但代码没跟着改；或者代码重构了，规格文件没同步。时间一长，规格文件和实际代码就脱节了，AI 再根据规格生成代码时就会产生冲突。

我的解决办法是把规格文件当成代码的一部分来管理。具体来说：规格文件和代码放在同一个 Git 仓库里，修改规格文件必须走 PR 流程，CI 里跑校验脚本确保代码符合规格。如果需求变更，先改规格文件，再让 AI 根据新规格重新生成代码。如果代码重构影响了契约，必须同步更新规格文件。

另外，我会在规格文件里加一个last_verified字段，记录最后一次人工确认规格与代码一致的时间。如果这个时间超过一个月，CI 会发出警告，提醒团队 review 规格文件。这个机制虽然简单，但很有效，能防止规格文件变成“僵尸文档”。

5.2 AI 生成的代码“过度设计”怎么处理

有时候 AI 会根据规格里的约束条件，生成一些过度复杂的实现。比如规格里写了“并发核销必须保证幂等”，AI 可能给你搞一个分布式锁 + 数据库唯一索引 + 消息队列去重的三重保险。代码是能跑，但复杂度上去了，维护成本也上去了。

遇到这种情况，我的做法是在规格文件里加一个implementation_hints字段，给 AI 一些实现方向的提示。比如：

implementation_hints: - "幂等控制优先使用数据库唯一索引，避免引入分布式锁" - "缓存更新采用 Cache-Aside 模式，不要用 Write-Through"

这些提示不是强制性的，但能引导 AI 选择更简单的实现方案。实测下来，加了implementation_hints之后，AI 生成的代码复杂度明显下降，review 起来也轻松多了。

5.3 规格文件写得太细导致 AI 失去灵活性

跟上一个问题相反，有时候规格文件写得太细，AI 反而变得死板。比如你规定了“用 Redis 做缓存”，但项目里其实已经有一套本地缓存方案，AI 却因为规格里写了 Redis 而硬生生引入了一个新的依赖。

这个问题的根源在于规格文件越界了。规格文件应该描述“做什么”，而不是“用什么做”。如果你确实需要指定技术选型，那应该放在implementation_hints里，而不是放在constraints里。constraints只写那些必须满足的硬性要求，比如性能指标、安全要求、合规要求。技术选型属于实现决策，应该留给 AI 或者开发者根据项目实际情况来判断。

5.4 常见问题速查表

5.5 一个真实的踩坑记录

有一次我给一个支付回调接口写规格，里面定义了constraints: "回调处理必须保证幂等，同一笔订单重复回调只处理一次"。AI 生成的代码里用了一个内存 map 来做去重，单机测试没问题。结果上线之后，服务是多实例部署的，内存 map 不共享，同一笔回调打到不同实例上，还是重复处理了。

这个坑的教训是：规格文件里的约束条件，必须考虑部署环境。如果服务是多实例的，幂等控制就不能用单机内存，必须用共享存储（比如 Redis 或数据库唯一索引）。后来我在规格文件里加了一条deployment: "multi-instance"的元信息，AI 再生成代码时就会自动选择分布式方案。

注意：规格文件不是写完就完了，它需要随着项目环境的变化而迭代。部署架构变了、技术栈升级了、合规要求更新了，规格文件都要跟着改。把规格文件当成活文档来维护，它才能真正发挥价值。

6. 从个人实践到团队协作的扩展思路

6.1 规格文件的版本管理与协作规范

一个人用 OpenSpec 和一群人用 OpenSpec，完全是两码事。个人用的时候，规格文件怎么写、怎么改，自己说了算。但团队用的时候，必须有一套协作规范，否则规格文件会变成新的“扯皮现场”。

我目前在团队里推行的规范是这样的：每个模块的规格文件由该模块的负责人维护，其他人可以提 PR 修改，但必须经过负责人 review。规格文件的变更必须关联到具体的需求单或缺陷单，不能无缘无故改。每次发版前，跑一遍全量校验脚本，确保所有模块的代码都符合规格。如果某个模块的规格文件超过两个月没有更新，但代码有变更，系统会自动提醒负责人 review。

这套规范听起来有点繁琐，但实际跑下来，团队接受度还挺高的。因为大家发现，花在写规格和 review 规格上的时间，远远少于之前花在“跟 AI 扯皮”和“修 AI 生成的 bug”上的时间。而且规格文件本身也成了新人入职的培训材料，新人看完规格文件，基本就能理解系统的核心逻辑了。

6.2 规格驱动开发与测试驱动开发的结合

SDD 和 TDD（测试驱动开发）并不冲突，反而可以互补。TDD 是先写测试再写实现，SDD 是先写规格再写实现。两者的共同点是“先定义预期，再动手实现”。区别在于，测试是代码级别的验证，规格是契约级别的约束。

我在实践中的做法是：先用 OpenSpec 写规格文件，然后让 AI 根据规格生成测试用例，再让 AI 根据测试用例生成实现代码。这个流程走下来，代码的测试覆盖率基本能到 80% 以上，而且测试用例和规格文件是对应的，规格变了测试也跟着变，不会出现“测试和需求脱节”的问题。

举个例子，规格里定义了errors: [{code: 10001, condition: "URL 格式错误"}]，AI 会自动生成一个测试用例：传入一个格式错误的 URL，断言返回的错误码是 10001。这个测试用例是直接从规格推导出来的，不需要人工编写。规格更新了，测试用例也跟着更新，非常省心。

6.3 规格文件的复用与继承

当项目规模变大之后，你会发现很多模块的规格文件有大量重复内容。比如每个接口都有user_id输入、都有10001参数错误码、都有timeout约束。如果每个规格文件都从头写一遍，维护成本会很高。

OpenSpec 支持规格文件的继承和复用。你可以定义一个base_spec.yaml，里面放公共的输入定义、错误码定义、约束条件，然后其他规格文件通过extends: base_spec.yaml来继承。子规格文件只需要定义自己特有的部分，公共部分自动继承。

这个机制在微服务架构里特别有用。比如所有服务都需要trace_id输入、都需要50000系统错误码、都需要timeout约束，这些都可以放在base_spec.yaml里。子规格文件只关注业务逻辑，不用重复写基础设施相关的定义。实测下来，规格文件的体积能减少 40% 左右，维护起来轻松多了。

6.4 规格文件的自动化生成

写规格文件本身也是一件费时费力的事情。特别是对于已有的老项目，补写规格文件简直是一场噩梦。我的做法是：先用 AI 分析现有代码，自动生成一份“逆向规格”，然后人工 review 和修正。

具体操作是：把现有代码喂给 AI，指令是“分析这段代码的输入输出、错误处理、边界条件，生成一份 OpenSpec 格式的规格文件”。AI 生成的规格文件可能不完美，但至少能覆盖 70% 的内容。人工只需要补充那些代码里没有显式表达、但实际存在的约束（比如性能要求、并发安全要求）。这样比从零开始写规格快得多。

对于新项目，我建议还是先写规格再写代码。因为新项目的代码还没写，逆向生成规格没有素材。而且新项目正是需要把需求想清楚的时候，写规格的过程本身就是需求梳理的过程。

6.5 规格驱动开发的边界与局限

说了这么多 OpenSpec 的好处，也得客观聊聊它的局限。首先，规格驱动开发不适合所有场景。对于那些需求极度不确定、需要快速试错的项目，先写规格反而会拖慢速度。比如做一个 demo 或者原型，直接让 AI 生成代码，跑起来看看效果，比写规格快得多。

其次，规格文件的质量高度依赖编写者的经验。一个新手写的规格文件，可能遗漏关键约束，导致 AI 生成的代码有隐患。一个老手写的规格文件，可能过度约束，导致 AI 生成的代码死板。所以规格文件的编写者需要有一定的架构设计能力和业务理解能力。

最后，规格驱动开发不能替代代码 review。规格文件只能保证代码符合契约，不能保证代码的质量。比如 AI 生成的代码可能符合规格，但命名不规范、注释缺失、逻辑绕弯。这些还是需要人工 review 来把关。我的经验是，规格文件把“低级错误”拦住了，人工 review 就可以聚焦在“高级问题”上，整体效率还是提升的。

7. 我个人在实际操作中的几点体会

折腾 OpenSpec 这套东西大概有大半年了，从个人项目到团队协作都试过。最大的感受是：AI 编码的上限不取决于模型有多强，而取决于你给它的约束有多清晰。同一个模型，给它一段模糊的自然语言描述，它生成的代码可能只有 60 分；给它一份结构化的规格文件，它生成的代码能到 85 分。剩下的 15 分，靠人工 review 和测试来补。

另一个体会是：写规格文件的过程，其实是逼自己把需求想清楚的过程。很多时候我们觉得需求很明确，但一写规格就发现，这里没定义、那里有歧义。这些问题在写代码之前暴露出来，比在测试阶段暴露出来要好得多。所以哪怕不用 AI 编码，写规格文件本身也是有价值的。

最后分享一个小技巧：如果你觉得 YAML 规格文件写起来太繁琐，可以先从最简单的开始。不用一上来就写完整的输入输出错误码约束，先写清楚inputs和outputs就行。等习惯了这种思维方式，再逐步补充constraints和dependencies。循序渐进，比一步到位更容易坚持下来。