用规范驱动开发终结代码与文档的撕裂：OpenSpec 实践手记

【免费下载链接】OpenSpec Spec-driven development (SDD) for AI coding assistants. 项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec

规范驱动开发（Spec-driven Development，SDD）这几年被反复提及，但很多团队的真实体感是：文档照写、规范照定，代码和需求该撕裂还是撕裂。OpenSpec 想解决的正是这个落差——它把"需求 → 规范 → 变更 → 验证"串成一条 AI 编码助手能真正执行的闭环，让团队共识不再是一份没人看的 Markdown，而是一套可运行、可验证、可量化的规则。下面从我们踩过的坑讲起，聊聊它到底改变了什么。

凌晨两点，一个路径分隔符让整个迭代停在原地

故事发生在一次跨平台联调。同事在 Windows 上写好命令让 AI 助手执行，推到 CI 里跑到 Linux 节点直接崩了——报错信息只有一个：expected '/' but got '\'。再往下查，是某个配置文件里硬编码了反斜杠，AI 助手在 macOS 上开发时没暴露问题，因为 Mac 的文件系统对大小写不敏感，路径也宽容；可一到 Linux，所有假设全部作废。

这类报错在规范驱动缺位的团队里几乎是周更频率：不是 AI 不够聪明，而是它根本没有"这套项目在哪些平台上跑、路径必须怎么写"的规则可循。OpenSpec 把跨平台约束写进了自己的开发公约：强制使用 path.join() 和 path.resolve() 拼接路径、绝不假设斜杠方向、测试断言里也不允许出现硬编码的路径字符串。换句话说，它把"曾经靠人肉提醒的常识"变成了机器会校验的硬规矩。你可以在项目的 AGENTS.md 里看到这类约束，AI 助手每次生成代码前都会先读到它们。

规范为什么总在写完那一刻就变成"文档僵尸"

先别急着上工具，我们把病根说透。大多数团队的规范流程长这样：开会定需求 → 产品写 PRD → 架构师画方案 → 开发照着写 → 验收时发现对不上。规范文档诞生于项目启动，随后进入"僵尸状态"——没人更新、没人验证、没人知道它和代码是否一致。

问题出在哪？出在"规范只被阅读，从未被执行"。文档写一百遍"必须做权限校验"，不如让工具在变更提交时自动检查"这次改动是否覆盖了权限需求"。OpenSpec 的思路就是把规范从"给人看的说明书"改造成"给机器执行的检查清单"：每条需求都挂在具体的 spec 文件里，每次变更都要声明自己改了哪些 spec，验证命令会逐条核对。规范有没有落地，不再靠评审会上大家点头，而是靠一条命令的输出。

三步把一条业务需求变成 AI 可执行的规范

简单来说，OpenSpec 的工作流就三步：提案 → 规范 → 变更。

第一步，写一份 proposal.md，说清楚"要解决什么问题、为什么现在做"。第二步，把需求拆解成 specs/ 目录下的规范文件，每条规范包含明确的验收行为。第三步，把任务拆进 tasks.md，让 AI 助手照着清单逐项实现。每一步都有对应的 CLI 命令兜底，比如 openspec new-change 初始化变更目录，openspec spec 增删规范条目。

关键就在这里：这三个步骤不是割裂的文档，而是有依赖关系的产物链。提案没通过，规范就不该出现；规范没写完，任务就不能标记完成。你可以把规范存储层理解成"团队共识的版本库"——所有已确认的行为规范都在这里留档，任何修改都有迹可循，和 Git 管代码一样管共识。

一次变更从提案到归档，要过哪几道关卡

团队协作最大的痛点不是写不出规范，而是多个需求并行时互相踩踏。OpenSpec 的变更管理采用"一变更一目录"的隔离策略：

openspec/changes/
├── add-export-api/          # 提案：给 CLI 增加导出能力
│   ├── specs/
│   │   └── cli-export/
│   │       └── spec.md
│   ├── proposal.md
│   └── tasks.md
├── fix-windows-paths/       # 提案：修复跨平台路径问题
│   ├── specs/
│   │   └── cli-config/
│   │       └── spec.md
│   ├── proposal.md
│   └── tasks.md
└── archive/                 # 已合并的变更归档区

每个变更都是独立的原子单元，互不干扰地开发、审查、测试。合并时执行归档操作，把验收过的规范合并进主规范库，同时把变更目录移入 archive。你会发现这套机制和 Git 分支模型如出一辙：隔离保证并行，归档保证合并，全程可回溯。谁改了哪条需求、什么时间验收通过，翻一眼目录结构就清楚了。

不改一行代码，怎么让工具按团队的规矩办事

配置驱动是 OpenSpec 模块化设计的核心：团队定制工具行为，不需要碰核心逻辑，改 YAML 就行。项目根目录的 openspec/config.yaml 控制全局策略：

# openspec/config.yaml（节选）
validation:
  mode: warn-first          # 开发期宽松验证，上线前再切严格模式
  ignoreWarnings: false

commands:
  validate:
    scope: changed-only     # 默认只验证本次变更涉及的范围
  init:
    template: team-standard # 团队自定义初始化模板

telemetry:
  enabled: true

这套配置的价值在于：验证严格度、命令默认参数、遥测开关都可以按项目阶段调整。新团队可以先用宽松模式跑通流程，成熟后再启用严格验证作为质量门禁。配合 schemas/spec-driven/schema.yaml 里的工件定义，团队还能扩展规范结构、加自定义字段，而解析逻辑完全不用动。

只体检这次改动：增量验证为什么又快又稳

规范库膨胀到几十个 spec 之后，全量校验会变成一场灾难——每次改一行配置都要跑几分钟的检查。OpenSpec 的增量验证策略把这个成本砍掉大半：它只对本次变更涉及的规范做检查，而不是把整个仓库重新过一遍。类比一下，全量验证像每年一次的全身体检，增量验证则是"这次只查你动过的地方"，快、准、不影响别处。

验证分两层：先做语法验证，检查规范格式是否符合 schema 定义；再做语义验证，确认这次变更不会破坏已有规范的完整性，比如删掉的 spec 是否还被其他变更引用。两层都过了，变更才允许进入归档。

仪表盘上的数字，凭什么能帮管理者拍板

规范驱动的最后一个难题是"不可见"——管理者看不到规范体系到底运转得怎么样。OpenSpec 内置的仪表盘解决了这一点，一条 openspec view 命令就能看到全局：

这张图里最有信息量的不是"10 个规范、64 条需求"这些总量数字，而是比例关系：3 个进行中的变更里，两个进度条已经到了 90% 以上，说明瓶颈在收尾验证而不是起步；73% 的任务完成率配上 4 个已归档变更，说明这条流水线是真实在转的。管理者盯三个指标就够了：变更周转时间（从提案到归档多久）、验证通过率（提交的规范有多少一次过）、任务完成率（承诺的工作是否按期落地）。这些数字让"规范体系健不健康"从拍脑袋变成了可对话的数据。

从试点到全团队：一条可以直接抄的落地路线

最后给一份能直接抄作业的分阶段推行路线：

1. 试点期（1～2 周）：挑一个非核心模块，把现有需求反向补成规范，跑通"提案 → 规范 → 变更 → 验证"全流程，先让团队看到闭环长什么样。
2. 推广期（1 个月）：把试点经验复制到另外两三个模块，同时把跨平台路径、命名规范这类通用约束写进 AGENTS.md，让 AI 助手从第一天就遵守。
3. 标准化期：制定团队级规范标准，把严格验证接入 CI，规范不过就不允许合并。
4. 优化期：根据仪表盘数据持续调整——验证太严就放松、变更周转变慢就砍流程步骤。

过程中有几个容易踩的坑：规范所有者要明确，没人认领的 spec 迟早变僵尸；规范必须和代码一起进版本控制，否则又回到"文档在 Wiki、代码在 Git"的老路；以及，别想着一次把全部历史需求都补成规范，从增量开始，先把新需求跑顺。

写在最后：规范驱动开发解决什么，不解决什么

说到底，OpenSpec 解决的是"共识的可执行性"：它把团队脑子里的规矩、散落在文档里的约定、口头传递的需求，统一变成机器能校验、能统计、能追溯的规范资产。它不解决需求本身是否合理，也不替你做产品决策——规范再完善，方向错了照样白干。

但如果你受够了"文档和代码两套真相"、受够了跨平台报错反复上演、受够了评审会上靠感觉说话，那么把规范变成可执行闭环，可能是投入产出比最高的一步棋。工具只是载体，真正值钱的是那套"先对齐、再动手、后验证"的工作方式。

【免费下载链接】OpenSpec Spec-driven development (SDD) for AI coding assistants. 项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec