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 份文档覆盖从需求采集到测试追溯的完整链路，团队可以根据业务需要微调。

关键设计：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 用例

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

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 份文档的分工：

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

三个级别对比

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

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

让 AI 写初稿、人来审核确认，是最高的文档生产效率。这套框架提供了 10 个 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 工程化落地。