Spec文档太大?要分层分场景

团队用 AI Coding,瓶颈在哪?

Spec-Driven 理念很直接:先写 Spec 再写代码,内置模板和文档生成能力,单人开发效率很高。在团队落地 AI Coding 时发现一个模式:瓶颈往往不在代码生成,在代码生成之前的对齐。

场景很典型:PM 提了一个需求,研发在 AI IDE 里开始写 Spec 写代码,写到一半发现某个字段的含义跟 PM 想的不一样,回去确认;测试拿到功能后发现验收标准和需求对不上。这不是 AI IDE 的问题——AI IDE 面向的是开发者,它不知道 PM 的业务规则应该对应哪个接口字段、测试用例有没有覆盖所有验收标准。

所以问题不是"AI 能不能生成代码",而是在 AI 生成代码之前,PM、研发、测试三方有没有对齐。

这套 Spec 分级框架解决的就是这个问题。它定义了一套团队协作的 Spec 规范——文档模板定义写什么、三级分级定义写多细、交叉校验定义怎么算对齐。


Spec 文档体系

14 份文档覆盖从需求采集到测试追溯的完整链路,团队可以根据业务需要微调。

编号文档名称一句话说明
01Spec 写作总则与编号索引约定编号规则和文档规范
02需求来源与采集记录原始需求记录,防"需求幽灵化"
03立项提案与范围说明定边界:做什么、不做什么
04产品需求说明 PRD业务规则真源:数值、条件、判断逻辑
05用户故事与验收标准 US+AC验收标准真源:Given/When/Then
06功能规格说明 FSD前端展示和交互契约
07非功能需求与约束性能、安全、兼容性要求
08系统架构与技术选型技术方案和架构决策
09API 接口规格接口契约:端点、字段、错误码(AI IDE 直接消费)
10数据模型与存储规格表结构:字段、类型、约束(AI IDE 直接消费)
11安全设计规格安全策略和审计要求
12实施计划与里程碑排期和阶段划分
13测试策略与质量门禁测试用例和断言
14需求追踪矩阵 RTM追溯工具:REQ → US → API → TC


关键设计:AI工具只需要一部分文档来生成代码,但是整个Spec文档用来校验逻辑,让本来不熟悉的产品与功能模块能够设计的更加严谨,让复杂的产品与功能模块能够通过文档清晰严谨的表达逻辑。Spec Coding 需要接口契约的字段、类型、约束来生成代码。对齐的责任在团队身上,不在 AI IDE 身上。


三级分级:需求风险不同,Spec 规格不同

不是所有需求都需要 14 份文档。一个按钮文案修改和一套费率计算规则变更,需要的 Spec 深度显然不一样。

定级依据四个因素:涉及几个团队、影响范围多大、跟合规或资金有关吗、回滚要多久。


L1 轻量级:不需要 Spec

一个人能判断、一个团队能搞定的事——修改文案、增加展示字段、改超时配置、修已知 Bug。

准入条件(全部满足):只涉及一个团队、不影响已有业务规则、不涉及合规、回滚 ≤ 30 分钟、三方口头能说清楚。

工作流:没有文档。研发直接在 AI IDE 里编码。

业务方提需求 → PM 口头确认 → 研发评估 → AI IDE 开发 → 测试 → 上线

典型周期:0.5 - 1 天。


L2 标准级:一次对齐会比十页文档管用

需要三方配合但不出系统边界的事——新增 API 端点、增加功能(如"导出 PDF")、修改查询过滤逻辑。

准入条件(满足任意两条):涉及 PM+研…

— 以上为试看内容(约 40%),开通会员后阅读全文 —