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

团队用 AI 写代码，卡点往往不在代码生成本身，而在生成之前的“对齐”环节。这套 Spec 分级框架，通过三级规范和交叉校验机制，让 PM、研发、测试三者在 AI 动手之前就能达成共识——这才是工程化落地的关键。

核心内容包含几个方面：AI Coding 团队协作中真正的瓶颈与对齐难题；一套三级分级的 Spec 文档体系，附带 14 份覆盖全链路的文档模板；以及依据风险定制的分级策略和关键设计原则。

团队用 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	路由

每个 Skill 的 Prompt 和输出格式都可以自定义。Skill 写初稿，人做判断和决策。

如何在你的团队开始使用

第一周：只跑 L2。选一个中等复杂度的需求，走一遍 L2 流程——PM 写方案文档，拉 30 分钟对齐会，研发写 09+10 喂给 AI IDE 生成代码。先让团队感受一次“对齐会 → 文档 → AI 生成”的完整链路。

逐步加 L3。L2 跑顺之后，挑一个核心需求走 L3 全流程。PM 写 02-05，研发写 06-12，测试写 13-14，跑自动门禁。这时候团队会理解为什么需要交叉校验——不是因为流程要求，而是因为门禁真能发现规则遗漏。

自定义模板。14 份文档是模板不是铁律。不需要 12 实施计划（用 Jira 管排期）就删掉，需要把 06 和 07 合并就合并。保持编号体系一致即可。

总结

这套 Spec 分级框架的核心只有三条：文档模板可自定义、分级匹配风险等级、Skill 降低文档生成成本。工具解决“怎么写代码”的问题，框架解决“写代码前对清楚、写代码后能追溯”的问题。二者配合，才是完整的 AI Coding 工程化落地。