MumuSpec，让Spec更落地

写 Spec 这件事，卡在哪了？

很多开发者在推 Spec 驱动开发。PRD、用户故事、API 规格、数据模型、测试策略——文档体系搭得挺全，但用起来总有几道坎：

第一，文档一致性全靠人肉 review。

PRD 说"支持微信登录"，用户故事里写了 5 条 AC，API 规格里定义了 3 个端点。数据模型里有没有 user 表？微信 open_id 字段定义了吗？没人能靠脑子记住 14 份文档之间的所有映射关系。Review 到最后变成了"看个大概，没啥大问题就过"。

第二，每人要面对 14 份文档模板。

PM 不需要看 API 怎么写，Dev 不需要看 PRD 模板长什么样，QA 只关心测试策略和追溯矩阵。但所有入口都在一起，每个人都要在一堆和自己无关的模板里面找到自己需要的那一份。

第三，评审和归档缺少编排。

到底是先对齐 US 和 API，还是先对齐 PRD 和 US？P0 阻断问题谁决策？基线版本怎么打？靠微信群里 @ 所有人，然后口口相传。"

这些问题在方法论层面都有答案——流程文档写得清清楚楚，但工具不支持。流程写在那，人记不住，就约等于不存在。

让工具理解人，而不是让人理解工具

MumuSpec 方案C 是一个 VS Code 扩展。它不改变 MumuSpec 已有的文档体系和library/changes/archive目录规范，而是给这套体系加了一层意图理解层。

你不需要说"我要走 R2 对齐流程"，你只需要说"帮我对下 US 和 API"。

扩展会自动识别你的角色，找到对应的文档，执行检查，列出不一致的问题。

四个核心能力：

📝 创作 — 按角色，而不是按阶段

打开创作面板，按团队角色分组：

选一篇文档，系统自动检查前置依赖（比如写 API 之前需要有用户故事），确认后生成骨架模板。

🔍 校对 — 四组规则引擎，自动跨文档检查

这是方案C 里真正省时间的部分。四组独立的检查，覆盖文档间所有关键一致性：

• align-us-api（用户故事 ↔ API 规格）：AC 里提到的字段在 API 规格里定义了没有？每个 AC 的"可观测断言"在 API 上有对应吗？AC-001 说"返回用户昵称"，但 API 响应里连 nickname 字段都没有——这类问题自动标出来。
• align-prd-us（PRD ↔ 用户故事）：PRD 里的每个功能，用户故事都覆盖了吗？"不做清单"里的内容，有没有出现在 US 中？
• align-api-db（API ↔ 数据模型）：API 的请求/响应字段，数据模型里有没有对应定义？类型是否兼容？string 还是 int？
• align-trace（追溯闭环）：追溯矩阵中，每条 REQ 都有对应的 US、API 和 TC 吗？

每条检查结果标注 🔴 阻断（必须修复）或 🟡 提醒（建议检查），可以直接定位到具体文档和行号。

👥 评审 — 编排对齐步骤 + 基线冻结

评审不是重新做一遍校对，而是编排对齐步骤：

1. 执行 align-prd-us（PRD → US 覆盖）→ 确认需求无遗漏
2. 执行 align-us-api（US → API 映射）→ 确认每个 AC 可观测
3. 执行 align-api-db（API → 数据模型）→ 确认字段定义完整
4. 执行 align-trace（追溯闭环）→ 确认规范全链路可回溯

每个步骤的结果汇总到一个列表中，逐条决策：通过 / 暂缓 / 接受风险。所有 🔴 阻断问题关闭后，允许冻结基线，版本号自动升为 v{大}.{小}。

✅ 验收 — 开发完成后的归档闭环

开发完成后，验收阶段做三件事：

1. 对比用户故事 + AC 与代码实现——是不是都完成了？
2. 检查测试策略中的 TC 通过率
3. 对比 API 规格与实际接口——有没有不一致？

偏差记录入档，然后归档为 v{大}.{小}-delivered。

30 秒上手

扩展装好后，打开包含 MumuSpec 目录结构（library/+ changes/）的工作区，状态栏自动显示 📘 MumuSpec，点击即可打开工作台。

命令面板也可以：Cmd+Shift+P→ MumuSpec: 打开 Spec 工作台。

工作台总控台显示项目概览（文档数、状态分布）和四个入口卡片。

日常使用流：

PM：「写个 PRD」→ 创作面板 → 选 PM → 选 04-PRD → 前置依赖检查 → 骨架生成
Dev：「对下 US 和 API」→ 校对面板 → 一键运行 align-us-api → 检查 Issue
团队：「拉个评审会」→ 评审面板 → 编排全部步骤 → 汇总 → 冻结基线
QA：「验收归档」→ 验收面板 → 跑验收 → 对比偏差 → 归档版本

用了之后，什么变了？

之后

最直接的变化是：跨文档一致性不再是"高端操作"。之前只有最资深的架构师能靠经验发现文档之间的不一致，现在每个 PM 写完后一键校对就能自己发现。

当前状态

扩展已初步可用，目前在内部项目中使用和迭代。近期规划：

• 规则引擎增强：覆盖更多文档类型对的交叉检查
• AI 对齐：对部分模糊匹配场景引入语义级别的判断（当前 P0 用正则保证确定性）
• 代码对比：verify 阶段接入实际代码分析（AST 匹配）
• 变更提案：review 中自动生成修复建议的 Diff

MumuSpec 不改变你写文档的方式——它只确保你写完之后，不用靠肉眼去对齐它们。

如果你团队也在用 Spec 驱动开发，或者正在对比各种 Spec 工具链，欢迎来 GitHub 讨论。