OpenSpec 类工具适合解决什么问题

高谷深陵大约 6 分钟约 1658 字

业务问题背景

AI 辅助开发越深入，需求表达的问题越明显。过去需求说不清，最多是人和人反复沟通；现在需求说不清，AI 会直接生成一套看似完整但方向可能跑偏的实现。

OpenSpec 类工具的价值就在这里：在编码前，把“要做什么、为什么做、怎么验收、哪些不做、涉及哪些契约”先结构化。它不是为了多写文档，而是为了让人和 AI 在同一个事实基准上工作。

Spec 的本质不是文档格式，而是变更契约。

一个团队要新增“AI 助手配置”能力。口头讨论时，大家都觉得很清楚：有页面、有接口、有配置、有权限。但实现过程中，页面入口和已有设置入口混了，接口字段和前端表单不一致，配置更新后缓存没有失效，旧入口兼容没有说明，验收时才发现很多细节要返工。

如果在编码前写清入口、页面、权限、接口、错误码、配置、缓存、旧路径兼容和验收项，这类返工会少很多。

Spec 类工具解决的正是这种“大家以为理解一致，其实只是词一样”的问题。

OpenSpec 类工具适合解决三类断层。

第一，需求到设计的断层。业务目标说了，但非目标、边界条件、异常路径和约束没有写清。

第二，设计到实现的断层。方案有了，但任务拆解、文件范围、接口契约和依赖关系没有落到可执行清单。

第三，实现到验证的断层。代码写完了，但验收标准、测试路径、真实交互和风险说明没有对齐。

Spec 的价值不是把文档写漂亮，而是把这三段连接起来。

一个可落地的 Spec 流程，可以拆成四份产物。

Proposal 负责回答为什么做、解决什么问题、哪些不做、成功标准是什么。

Design 负责回答系统怎么改、边界在哪里、接口怎么定义、数据怎么流动、权限怎么控制、异常怎么处理。

Tasks 负责回答分几步做、每一步改什么、依赖关系是什么、验证点是什么。

Verification 负责回答最终怎么证明完成，包括自动化测试、构建、接口验证、页面验证和人工确认项。

AI 可以参与生成这些内容，但最终要由人确认。因为 Spec 不是 AI 的作文，而是团队的承诺。

AI 编程最大的问题之一，是它会把隐含需求当成可自由补全的空白。Spec 的作用，就是把隐含需求显式化。

从工程角度看，Spec 是上下文压缩器。它把大量分散在会议、聊天、旧代码、接口文档和历史经验里的信息，压缩成 AI 和人都能理解的结构化约束。

从协作角度看，Spec 是责任边界。后端、前端、测试、运维和产品都可以围绕同一份契约讨论，而不是各自拿一份理解去做。

从验证角度看，Spec 是验收基准。没有基准，验证只能变成“看起来差不多”。

不是所有改动都需要重 Spec。改一个错别字、调整一个局部样式、修一个明确的小问题，用轻量任务说明即可。

但以下场景非常适合引入 Spec：跨前后端协作、新模块、新接口、新权限、新数据模型、配置类能力、上传下载、外部服务适配、流程状态变更、发布影响较大的改动。

Spec 也不能替代架构设计。它可以承载设计，但真正的技术取舍、边界判断和风险接受，仍然需要架构师主导。

团队落地 Spec 时，最容易犯的错是把它写成大而全的长文档。更好的方式是让 Spec 可执行。

每个需求只写和本次变更相关的事实：入口在哪里，接口是什么，数据归谁，权限怎么判，错误怎么返回，状态怎么流转，哪些旧行为要兼容，哪些验证必须完成。

Tasks 不要写成愿望清单，要写成能逐项完成的工程清单。每一项最好都能对应到代码改动或验证动作。

Spec 变更也要有版本意识。需求变了，要更新 Spec，再改代码。不能让代码悄悄背离契约。

第一个坑，是为了写 Spec 而写 Spec。文档很长，但任务仍然不可执行。

第二个坑，是 Spec 不维护。需求变了，代码变了，Spec 没变，最后它反而误导 AI。

第三个坑，是只写正向路径。真实系统里，权限、异常、空数据、旧兼容、失败重试和回滚才是容易出问题的地方。

第四个坑，是把 Spec 完全交给 AI。AI 可以起草，人必须确认。

从“高风险变更必须有轻量 Spec”开始，不要一开始就全量推。

Spec 模板可以很短，但要固定包含：背景目标、非目标、入口范围、接口契约、数据边界、权限边界、异常策略、验证清单、风险说明。

AI 执行任务前，先读取对应 Spec；AI 交付任务后，再反向检查实现是否符合 Spec。这样 Spec 才不是摆设，而是工作流里的事实源。

OpenSpec 类工具真正解决的不是文档问题，而是协作确定性问题。

AI 时代，需求越模糊，生成越危险。Spec 的价值，就是在 AI 高速执行之前，把团队共识、业务边界和验证标准先固定下来。先定世界，再让 AI 去执行世界。