Spec-09，接口规格写好，AI 生成代码才不掉链子

在 MumuSpec 十四文档体系里，09 是"行为契约真源"——字段名以它为准，测试断言以它为准，AI 代码生成也以它为准。前端、后端、测试、AI 工具都读同一份规格。

一、先想一个问题：谁说了算？

一个需求从口头到上线，会经过很多双手：

PM 在 PRD 里写"每人限领 3 张"，原型上标了"每人最多领 3 张"，后端接口叫 limitPerUser，前端页面显示"x/3"，测试用例断言"第 4 次返回 403"——这些字段名和边界值，有没有在同一个地方统一定义？

大多数项目没有。结果是：

• 前端问后端："返回的 limit 是什么类型？"
• 后端问 PM："这个字段叫什么？"
• PM翻 PRD："我好像写了……但和现在的对不上"
• AI 写代码："我从 PRD 里看到 'limit=3'，从原型里看到 '每人最多领 3 张'，从已有代码里看到 maxPerUser: 5——我该信哪个？"

这就是缺一份"契约真源"的症状。

在 MumuSpec 体系里，09 API接口规格就是来回答这个问题的。

二、09 是什么，不是什么

它是

• 对外行为契约的真源。接口叫什么、字段名是什么、类型、约束、错误码——一切以 09 为准。
• 全文统一的字段名锚点。PRD 引用 09 的字段名，FSD 引用 09 的字段名，测试断言引用 09 的字段名——但所有人都去 09 查真值。
• AI 代码生成的直接输入。在 Qoder 等工具里，喂给模型的是 09+10，不是 PRD 全文。

它不是

• 不是 UI 设计稿（那在 06 FSD）
• 不是业务规则原文（那在 04 PRD）
• 不是数据库表结构（那在 10 数据模型）
• 不是测试用例（那在 13 测试策略）

一层管一层，不混层。09 只回答一个问题：后端向外部承诺了什么行为？

三、09 在 MumuSpec 体系里站在哪个位置

十四份文档有一条明确的主链：

Proposal(03-04) → Spec(05-06-07) → Design(08-09-10-11) → Plan(12) → Test(13) → Trace(14)

09 属于 Design 阶段，是"怎么实现"那一层的核心契约。

它的上下游关系：

一条规则落到 09，才算"可编码"。PM 的 R-02 说"每人限领 3 张"，业务侧这条规则写在 04。但它真正变成可编码的输入，是在 09 定义了 limitPerUser: integer, 1-5、在 10 定义了 coupon_claims.limit_per_user INT NOT NULL之后。

四、09 为什么是 AI Coding 的"命门"

这是很多团队踩过的坑：

"我们让 AI 直接读 PRD 生成代码，结果同一个字段在不同 API 里被理解成不同名字。"

原因很简单：PRD是给人读的，09 是给人+机器一起读的。

PRD 的写法是自然语言："当用户领取数量达到上限时，返回错误提示"。09 的写法是结构化规格：

POST /coupons/receive
  请求: { "coupon_type": string }
  响应: { "limitPerUser": integer, "claimed": integer }
  错误: 403 COUPON_LIMIT_EXCEEDED

AI 不需要从一段散文里猜接口规格。它只需要读 09 的端点、字段、类型、约束——然后生成代码。

在实际项目中，09 写得越精确，AI 生成的代码质量就越高：

03 到 05 决定"做什么"，09 决定"AI 能不能一次写对"。

五、09 长什么样：以投研问答助手为例

用真实的模板结构说明。完整模板见 Spec模板-投研助手/09-API接口规格.md，这里摘核心几块：

5.1 端点总览

一张表看清全部对外接口：

每个端点都与 04 PRD 的场景编号对应，与 05 UserStory 的需求编号对应。没有"游离端点"——不可能出现接口文档里有个端点但没人知道对应哪个需求。

5.2 详尽的端点描述

对核心端点逐字段展开。例如 POST /ask：

请求体：

成功响应（200）：

每个字段名都是全库统一的。06 FSD 引用 answer_source来展示"数据来源"标签，13 测试用例断言 response_time_ms < 5000，14 追溯矩阵记录字段到 TC 的映射——用的都是 09 里定义的名字。

5.3 错误码清单

前端拿这个写错误提示，测试拿这个写异常断言，AI 拿这个生成错误处理代码。

5.4 参数校验规则汇总

所有校验逻辑集中写在 09，不散落在各端代码里。后端按此实现校验，前端按此做预校验，测试按此设计边界用例。

六、写 09 的三个实用原则

原则 1：字段名"一次定终身"

09 里写定的字段名，就是全库的字段名。

• 不要在 04 里用 maxCount，在 09 里用 limitPerUser，在数据库里用 max_claims_per_user
• 如果必须改，先改 09，再改其他——因为 09 是真源
• AI 生成的代码会直接取 09 的字段名。09 里的名就是代码里的名

原则 2：每个端点都能追溯到需求

写 09 的时候，每个端点旁边标注对应 04 的场景编号和 05 的需求编号：

# 端点 POST /ask
# 对应: 04 SC-02 · 05 US-002 REQ-M1QA-002

这样做的好处：

• 需求变了，知道哪些端点和字段需要联动修改
• 14 追溯矩阵可以直接引用
• 门禁 Skill 可以校验"每个端点都有对应需求"

原则 3：错误码要和字段定义一样严格

很多项目的 09 错误码是"到时候再补"。结果联调时前端问"这个场景返回什么码？"后端说"我还没想好"。

错误码应该在 09 冻结的同时就定义好：

• 每个可能的失败场景一个唯一错误码
• 错误码命名统一（SCREAMING_SNAKE_CASE）
• details 里携带足够的前端展示信息

七、谁需要读 09

在 MumuSpec 十四文档体系里，09 是一个很小的文件——通常 3-5 页 markdown。但它是被引用最多的文件：

• 04 PRD 引用它的字段名
• 05 UserStory 引用它的端点
• 06 FSD 引用它的响应字段
• 10 数据模型保持与它拼写一致
• 13 测试以它的断言字段为准
• 14 追溯矩阵的每一行都涉及它的端点

09 写的质量，直接决定了 AI 生成代码的准确率，也决定了前后端联调的心累程度。

写 09 不需要复杂的工具，一个 markdown 文件 + 一张字段表 + 一个错误码清单就够了。

关键是：把它当合同写，而不是当笔记写。