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

用户5602664

发布于 2026-05-22 18:34:15

1110

团队用 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+研发+测试、需要新增或修改业务规则、前后端都要改、影响已有用户路径、有明确验收标准。

工作流。核心是一次 30 分钟的对齐会。

第 1 步：PM 接需求第 2 步：PM 写方案文档（约 1-2 小时）第 3 步：PM 出快速 Demo 给业务方确认方向第 4 步：发给研发和测试，约定 30 分钟对齐会第 5 步：对齐会——逐条过交叉点，三方拍板第 6 步：研发写 09 API + 10 数据（AI IDE 辅助生成初稿）第 7 步：AI IDE 读取 09+10 生成代码，测试写 13 用例

对齐会只做一件事：过交叉点，不是读文档。

交叉点	怎么对
业务规则 → API 字段	PM 说"R-01 的 limit=3"，研发说"09 对应 request.limit, integer"
AC → 测试用例	PM 问"AC-01 有覆盖吗？"，测试说"有，TC-011"
异常场景	三方逐条确认超时、边界、出错处理

Owner：写方案文档的 PM。典型周期：3 - 5 天。

L3 重量级：文档先行，门禁兜底

一旦出事就兜不住的——跨系统数据链路改造、监管合规变更、费率计算规则变更。

准入条件（命中任意一条）：涉及两个及以上系统、涉及监管合规、涉及资金核心流程、回滚 > 2 小时、失败可能导致事故。

核心理念：开发必须在文档完成并冻结之后才能启动。

工作流：

第 1 步：PM 写 02-05（AI Skill 辅助生成初稿）第 2 步：研发写 06-12（AI IDE 辅助写 09+10）第 3 步：测试写 13-14第 4 步：交叉对齐会，三方确认第 5 步：运行自动门禁——04 的规则在 09 有没有遗漏、05 的 AC 在 13 有没有被测试覆盖、编号是否一致第 6 步：门禁全过 → 文档冻结 → git tag第 7 步：AI IDE 读取 09+10 拆任务 → 生成代码第 8 步：测试按 13 执行用例第 9 步：上线前再跑一次门禁确认

14 份文档的分工：

角色	文档	审核者
PM	02, 03, 04, 05	PM 领导、研发、测试
研发	06, 07, 08, 09, 10, 11	架构师、PM
测试	13, 14	研发
Owner	-	整体串联

门禁校验：自动检查 14 份文档之间的内容一致性。任一门禁失败，打回修复后重新提交。典型周期：2 - 4 周。

三个级别对比

维度	L1 轻量级	L2 标准级	L3 重量级
适用占比	~50%	~40%	~10%
文档	无	方案文档 + 3 份核心	14 份全量
AI IDE 的角色	直接编码	辅助 09+10 初稿 + 代码生成	文档冻结后代码生成
对齐方式	口头	30 分钟对齐会	对齐会 + 自动门禁
开发前提	随时	对齐会通过	文档冻结 + 门禁全过
周期	0.5-1 天	3-5 天	2-4 周

级别不是固定的。L1 做到一半发现需要多人配合，升级 L2。L3 写文档发现影响面比预想小，降级 L2。每次变更重新定级——级别跟着风险走，不跟模块走。

10 个 Skill：降低文档生成成本

让 AI 写初稿、人来审核确认，是最高的文档生产效率。这套框架提供了 10 个 Skill，每个负责特定文档的初稿生成：

Skill 名称	负责写什么	对应文档
@mumu-spec-init	初始化项目骨架，创建文档目录	01-14
@mumu-spec-r1-proposal	需求采集结构化 → 立项提案 → PRD	02, 03, 04
@mumu-spec-r2-align	US+AC 和 API 双面对齐	05, 09
@mumu-spec-r3-design	架构、数据模型、FSD、非功能、安全	06, 07, 08, 10, 11
@mumu-spec-r4-finalize	计划、测试策略、追溯矩阵	12, 13, 14
@mumu-spec-sync	变更联动：改一个文档通知下游更新	全链
@mumu-spec-check	质量检查：完整性、一致性、门禁	01-14 校验
@mumu-spec-status	版本状态看板	版本管理
@mumu-spec-tasks	将 US 拆分为开发任务	任务拆分
@mumu-spec-main	总控路由：判断当前需求该调哪个 Skill	路由