编写 AI Ready Spec

资源

• 创建新 Spec 时，先完整阅读 assets/spec-template.md模板，遵循本技能规范，根据需求应用模板中的编写提示，并以该模板为骨架编写；最终删除不适用章节和全部编写提示。
• 新写、重构 FR，审查 SC/AC 覆盖，或判断是否使用流程图和交互依据时，完整读取 references/fr-writing-guide.md。
• 只修改元数据、版本记录或明确的小范围条款时，不必加载 FR 指南。

目标

把输入中的目标、事实、缺口和冲突收敛为一个规范性 Spec，使开发 Agent 不需要自行决定业务规则，测试 Agent 能从规则、SC 和 AC 得到稳定断言。Spec 描述“必须实现什么”，不记录需求分析过程。

核心原则

• 只规定业务行为、角色权限、字段规则、状态、计算、关联关系和可观察结果，不规定接口、数据库、缓存、日志、代码组织或测试实现。
• 每个 FR 表达一个可独立交付的业务能力，统一按“功能目标、功能行为、业务规则、不满足条件时的结果、验收标准、核心场景”组织；业务规则和核心场景按需保留。同一 FR 可以按实际业务主题包含零个、一个或多个“业务规则：[主题]”小节，不限制数量。
• 规则表是规范性需求；SC 只提炼关键、可独立判定的验收结果，不逐条重抄字段表或状态表。
• 每个 FR 的 SC 通常为 3～8 条，复杂功能可以更多；数量由独立业务结果决定，不为凑数拆分。
• AC 只保留高风险权限、状态、删除、原子变更等路径，数量由独立高风险路径决定，不设固定数量。只有真实存在页面操作路径时才写浏览器 AC，不为越权构造、接口篡改等场景虚构 UI。
• 两个或以上 FR 共用的规则使用稳定 BR-[模块]-[序号] ID。章节号只用于文档排版，禁止用“按第 X 节”“见上表”“满足下方规则”等位置描述作为唯一规范性引用。
• 多个 FR 共用的全局权限使用 BR-AUTH-[序号] 定义，并在受影响 FR 的 SC/AC 中验收；只有权限管理本身构成可独立交付的业务能力时才建立权限 FR。
• 按需保留章节。用户故事、交互依据、流程图和来源迁移不是固定配额。
• 流程图和交互依据只用于辅助理解已有需求：流程图表达必要的步骤、顺序和分支，交互依据记录已有原型或交互材料中的关键约束；两者都不能替代字段、权限、决策或状态规则。
• 按核心业务对象及其完整状态生命周期确定模块归属，不按参与角色、操作页面或先后步骤拆分模块。多个角色围绕同一对象协作时，相关能力保留在同一模块；角色、规则或结果明显不同的独立动作可以拆成多个 FR。
• 只有具备独立业务对象、规则和生命周期，并被多个业务模块复用的能力才单独形成模块。其他跨模块能力作为 FR 放入负责最终业务结果的明确归属模块；被多个 FR 共用的规则统一放入共享业务规则，不另设“跨模块业务规则”章节。

工作流程

1. 读取用户描述、业务材料、原型和约束，提取业务目标、用户、核心场景和已明确事实。
2. 检查会导致 Agent 自行猜测的缺口：范围、角色、权限、数据边界、字段、枚举、状态、计算、日期、关联对象、反向结果和完成判定。
3. 对明确事实直接采用；对会改变业务行为的缺口，按“待人工确认事项”选定默认口径后继续产出。
4. 先闭合共享规则并分配 BR ID，再按业务能力拆分 FR；为关键独立结果编写 SC，为真实可执行的关键路径编写 AC。
5. 引用共享规则时写稳定 ID 和语义名称，并在使用点直接写出实现当前行为所必需的最小结论；大型字典、决策表和状态表保留单一来源，不整表复制。
6. 使用稳定 ID；更新已发布 Spec 时保留原 ID，新增使用新 ID，废弃保留 ID 并标明废弃。
7. 完成质量校验，交付 Markdown 文件和简短摘要。

待人工确认事项

• 待确认不作为默认交付门禁。确认前，FR、SC 和必要 AC 必须写成一个可开发、可验收的唯一行为。
• 依次优先采用：来源明确规则；多处材料相互印证的结论；与已确认规则一致且影响最小的方案；仍无法区分时采用权限更小、数据更可保留、操作更可撤回的方案。
• 不替代法规效力、政策资格或专业事实判断；需要时采用不启用、只读或人工复核等保守边界。
• 最终 Spec 只列仍待人工确认的事项，使用三列：ID | 需要人工确认的问题 | 确认前采用口径。已确认事项从清单移除，其规则保留在正文。
• 不在最终 Spec 中保留证据判定过程、推荐理由流水、未采用方案清单或核实日志；用户明确要求决策审计时才另附。
• 只有用户明确要求“先确认再写”时才暂停提问。

创建或澄清 Spec

• 使用精简模板，只保留对当前范围有实际内容的章节。
• 用户故事仅在有助于解释业务价值、范围或 FR 归属时保留；不为了完整模板机械生成。保留的每个用户故事必须至少关联一个 FR，或关联承接该故事的全局权限或共享业务规则。
• 共享规则只写一次；仅影响单个功能的规则放在对应 FR。先按核心业务对象及其状态生命周期确定模块，再按可独立交付的角色动作拆分 FR；不因参与角色不同而另建模块，也不把业务能力混入共享规则。
• 跨位置引用使用 `BR-XXX-001`（规则语义名称），不用章节号定位。关键判断、边界和失败结果在 FR 内同时写明；大型规则表只引用其 BR ID，并写明本 FR 怎样选择、校验或应用该表。
• 同一 FR 内引用局部规则时使用唯一的语义标题，例如“本 FR 的‘业务规则：家庭关系’”，不用“上述”“下方”“前表”等相对位置词。
• 同一 FR 存在多个独立规则主题时，分别使用“业务规则：[主题]”小节表达，并根据各主题选择规则列表、字段表、决策表或状态表。小节数量由实际规则主题决定；不得为了套用模板合并无关规则，也不得仅因存在多个规则主题就拆分一个仍属同一业务能力的 FR。
• 按 references/fr-writing-guide.md 的选择条件决定是否加入流程图或交互依据，并放在能够完整覆盖其内容的最小范围；不满足条件时直接省略，不为填充模板生成流程或界面约束。
• 将模糊目标转为明确的角色动作、前置业务状态、系统响应、可观察结果和拒绝结果，不用“支持”“正常”“合理”等词代替规则。
• 不把详细测试数据、等价类、执行步骤、选择器或自动化实现写入 Spec。

审查 Spec

• 默认只报告问题，不修改文件；用户明确要求修订时再实施。
• 先报告会造成开发分歧、权限漏洞或验收不稳定的问题，再报告组织和追踪问题。
• 每项问题指出具体条款、歧义原因和应形成的唯一业务结论。
• 不因个人偏好重写已满足要求的内容，不建议无关章节或通用技术异常。

更新 Spec

• 保留用户已有修改，不回退无关内容。
• 修改范围、角色、权限、状态、日期、删除影响或关联规则时，同步更新相关 FR、SC、AC 和版本记录。
• 更新现有 Spec 时，将规范性章节号和相对位置引用替换为稳定 BR ID；共享规则没有 ID 时新增 ID，不因章节移动或插入而改号。
• 把代码或测试反馈转化为目标业务行为，不把排查过程和当前实现载体写入最终 Spec。
• 仅在用户要求改写旧需求或证明历史覆盖时执行来源迁移审计；完整迁移矩阵作为工作审计或独立附录，不进入默认主 Spec。

质量校验

• 范围、非目标、角色、权限和数据边界是否唯一。
• 保留的每个用户故事是否至少关联一个 FR，或关联承接该故事的全局权限或共享业务规则。
• 模块是否按核心业务对象及其状态生命周期划分，而不是按角色、页面或步骤划分；多角色协作是否仍保留在负责该对象的模块内。
• 独立模块是否确实拥有可复用的业务对象、规则和生命周期；其他跨模块能力是否已作为 FR 归入负责最终业务结果的模块，共享业务规则中是否只包含被多个 FR 共用的规则。
• 每个 FR 是否明确目标、触发、前置状态、系统响应、可观察结果及必要反向结果。
• 同一 FR 的多个独立规则主题是否分别使用唯一的语义标题表达，且未被模板限制为固定数量或合并成含义混杂的单一规则块。
• 流程图和交互依据是否确有必要、位于最小适用范围，且没有重复规则表、引入材料中不存在的界面约束或替代规范性业务规则。
• 字段、枚举、日期、计算、状态迁移和关联对象变化是否闭合。
• 每个规范性引用是否指向唯一存在的稳定 ID；是否已消除“按第 X 节”“上述”“下方”“上表/下表”等依赖文档位置的表达。
• 全局权限是否具有稳定 BR-AUTH ID，并在受影响 FR 的 SC/AC 中得到验收；是否不存在没有父级 FR 的孤立 SC/AC。
• 仅阅读单个 FR 时，关键业务行为是否仍可直接确定；需要完整矩阵或字典时，是否能通过 BR ID 唯一找到定义。
• SC 是否覆盖关键独立结果且不机械复制规则表；AC 的 When 是否为真实界面动作，Then 是否为稳定可观察结果。
• 开发 Agent 是否仍需自行决定任何角色、字段、状态、边界或失败结果；测试 Agent 是否能据此形成确定断言。
• 最终文件是否无占位符、空章节、模糊规范性文案、技术实现和过程追踪。