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 份文档覆盖从需求采集到测试追溯的完整链路,团队可以根据业务需要微调。
| 编号 | 文档名称 | 一句话说明 |
| 01 | Spec 写作总则与编号索引 | 约定编号规则和文档规范 |
| 02 | 需求来源与采集记录 | 原始需求记录,防"需求幽灵化" |
| 03 | 立项提案与范围说明 | 定边界:做什么、不做什么 |
| 04 | 产品需求说明 PRD | 业务规则真源:数值、条件、判断逻辑 |
| 05 | 用户故事与验收标准 US+AC | 验收标准真源:Given/When/Then |
| 06 | 功能规格说明 FSD | 前端展示和交互契约 |
| 07 | 非功能需求与约束 | 性能、安全、兼容性要求 |
| 08 | 系统架构与技术选型 | 技术方案和架构决策 |
| 09 | API 接口规格 | 接口契约:端点、字段、错误码(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+研…