requirements-doc

根据规格说明书编制的需求文档

此 skill 基于一个规格说明书项目（skill specs-ui，以及 skill prototype-ui 的原型，如有）生成开发团队的需求文档。源文件为 Markdown，每个部分各一份。构建过程会将它们组装成两种格式：

• 一份 Markdown 文档，适用于代码仓库或文档工具；
• 一个作为构建产物发布的 HTML 页面：随阅读进度滚动的目录、按标识符搜索、RF / CA / NF / DT / RQ 标签、图表、浅色和深色主题，以及“复制 Markdown”按钮，可复制整份文档或其中一个部分。功能和 UI 部分通过提取自规格说明书（不进行任何重写）；技术部分（架构、技术栈、基础设施）会先提出方案，再与相关人员确认；批次拆分会给出带有假设的区间估算。

文档和交流均使用法语。脚本代码使用英语；注释使用法语。<skill> 指此 skill 的目录；脚本从包含 specs/ui/ 的目录运行。无需任何依赖：Node 即可。

节省 token（请先阅读）

产品规格说明书的 HTML 往往超过 1 MB；需求文档则有 150 至 300 KB 的 Markdown。请遵循以下规则：

1. specs/requirements/REQUIREMENTS.md 是记忆文件：恢复工作时先阅读，并尽可能只参考此文件。它记录了各来源的进度、约束、技术决策 DT、估算假设以及待确认事项。每个阶段结束时都要更新，控制在 150 行以内。
2. 绝不读取规格说明书的 HTML：extract.mjs 会将其内容提取为 specs/requirements/sources/generated/ 中的 Markdown（长度约为原文的 1/7）。主模型读取 generated/inventaire.md 和 specs/ui/CONTEXTE.md，然后按需分块读取批次相关摘录。
3. 绝不读取组装后的文档（requirements.json → output 指定的 specs/requirements/requirements.md 和 .html），也不读取 specs/requirements/publish/。工作应在 specs/requirements/sources/ 中进行（每个部分一个源文件），然后运行 build.mjs 和 check.mjs。
4. 每个部分一个文件：修改某个部分时，只修改其源文件，无需重新阅读整份文档。
5. 将任务委派给合适的模型：

角色	模型	任务
设计	主模型	范围界定、问题、架构、技术栈、基础设施、批次和估算、非功能需求、呈现、审阅、发布
撰写	sonnet	根据 generated/lot-<lot>.md 编写某个批次的验收标准（指引：references/redacteur.md）；每个批次安排一位撰写者，并行处理
机械执行	haiku	运行 extract、build、check、trace 并汇报结果

任务	阅读内容
所有阶段	REQUIREMENTS.md
计划、标识符、风格	references/plan.md
架构、技术栈、基础设施	references/architecture.md
批次和估算	references/estimations.md

阶段 0 · 前提条件与准备

此工作流的交付物位于项目根目录的 specs/ 中：specs/ui（规格说明书）、specs/prototype（原型）、specs/requirements（此需求文档）。对于采用旧版布局的项目（根目录下的 specs-ui/、cdc/、cdc.json、CDC.md），请使用 skill specs-ui 中的 migrate-layout.mjs 整理；在此之前，脚本仍会读取 cdc.json。

项目必须包含 specs-ui（含 sources/site.json）。否则，应先提议编写规格说明书（skill specs-ui）。相关人员提供的其他功能文档（简介、笔记）应在范围界定阶段阅读，并列为参考文档。

node <skill>/scripts/init.mjs --specs specs/ui --out specs/requirements [--prototype specs/prototype]

脚本会创建 specs/requirements/（包含 requirements.json、REQUIREMENTS.md，以及每个部分一份已填入已知信息的源文件），在 30-specs.md 中为每个批次创建一个章节，并启动提取流程。若目录已存在，则不会覆盖：这表示正在恢复工作。

步骤 1 · 确定范围

阅读 specs/ui/CONTEXTE.md 和 specs/requirements/sources/generated/inventaire.md。然后通过 AskUserQuestion 询问影响技术方案的约束条件：指定或倾向的托管方式、团队技能（语言、框架）、安全与合规（SSO、欧盟境内数据、审计）、预期用量、基础设施预算、截止日期。始终提供「没有约束」选项。将回答记录在 REQUIREMENTS.md 中。

步骤 2 · 架构、技术栈和基础设施

遵循 references/architecture.md：

1. 阅读 RF 规则和界面中的技术需求（实时处理、外部事件、长时间运行的处理、隔离执行、密钥、多租户……），并将每项需求关联到对应规则；
2. 对每项结构性决策，通过 AskUserQuestion 提出 2 或 3 个选项，并给出推荐方案（每轮 4 个问题，最多 2 轮）；
3. 将每项决策记录为 DT-xx，写入 REQUIREMENTS.md，然后编写 60-architecture.md、70-stack.md 和 80-infrastructure.md（托管、环境、网络、容器、CI/CD、IaC 和密钥、可观测性、备份、安全、成本）。

未经确认，不得将任何技术方案写成已决定事项：尚未定论的推荐方案应标注为「待确认」。

步骤 3 · 功能部分

• 验收标准：每批次并行安排一位 sonnet 编写者，使用 references/redacteur.md，填写其文件 generated/lot-<lot>.md 和源文件 lots/<lot>-criteres.md。阅读他们的报告：模糊的规则应列为「待确认」事项，或转化为向相关人员提出的问题。
• 主模型负责撰写：
  • 10-presentation.md；
  • 20-utilisateurs.md（根据 RF 制作角色矩阵）；
  • 40-interface.md（原则、组件、移动端、无障碍；tokens 自动生成）；
  • 50-exigences-non-fonctionnelles.md（量化指标，并优先采用 specs 中的值）。

步骤 4 · 批次、估算、风险

遵循 references/estimations.md：

• 批次：批次 0「基础」，然后是 specs 中的批次；
• 估算：按批次列出目标、范围、依赖关系、交付物、完成标准和天数范围；然后提供汇总、假设和计划（gantt）；
• 风险和决策：风险 RQ-xx 记录在 95-risques.md 中（自动纳入 specs 中的未决事项），产品决策按日期记录在 99-annexes.md 中。

步骤 5 · 构建、检查、发布

node <skill>/scripts/build.mjs specs/requirements
node <skill>/scripts/check.mjs specs/requirements

check.mjs 会报告：

• 缺失的部分；
• 未填写的 {{…}} 模板；
• 失效的内部链接（ASCII 锚点）；
• 引用了但未定义的标识符；
• 未纳入拆分或缺少范围的规格批次；
• 清单中缺失的屏幕；
• 未闭合的图表；
• 重复的标识符。

修复所有问题，直到问题数为零。

构建会生成三个文件：

• specs/requirements/requirements.md：Markdown 文档；
• specs/requirements/requirements.html：可在本地打开的完整页面，其中的图表已渲染；
• specs/requirements/publish/requirements.html：供 Artifact 工具使用的无外层封装页面（不纳入 git 仓库：该文件会重新生成）。

使用 Artifact 工具发布 specs/requirements/publish/requirements.html（prepare-publish.mjs specs/requirements 会说明是否有内容需要发布，以及对应的 URL）。标题取自 <title> 标签，mermaid 图表由该工具自行渲染。重新发布同一文件会保留原 URL；将 URL 记入 requirements.json → artifacts.requirements 和 REQUIREMENTS.md，然后运行 prepare-publish.mjs specs/requirements --confirm（指纹保存在 .published.json 中，需提交）。--check 会检查 artifact 是否落后于本地页面。该页面无法提供文件下载（阅读器禁止此操作）：可以通过“复制”按钮获取 Markdown，或使用本地 .md 文件。每次重要发布时，在 00-titre.md 中更新版本和状态。

修改规格

重新运行 extract.mjs specs/requirements（功能部分会自动跟进），然后运行 check.mjs：它会报告缺失的新屏幕和失效的链接。更新受影响批次的验收标准（由撰写者负责）、批次和估算、风险；记录新版本。

开发期间的维护

需求文档位于应用仓库的 specs/requirements/ 中，其中包含源文件、构建生成的 Markdown（requirements.md、sources/generated/，团队和 Agent 无需构建即可阅读）以及 .published.json。HTML 页面（requirements.html）需要重新构建，并像 publish/ 一样留在仓库外：将其加入项目的 .gitignore。需求文档会随规格更新，而规格会随实现更新（skill specs-ui，步骤 7）。

稳定标识符。 代码和测试会引用 CA-…、RF-… 和 NF-… 标识符：标识符的含义永不更改，也绝不重复使用。

• 新验收标准使用该批次的下一个编号，即使它插入列表中间也一样。
• 已弃用的验收标准予以保留，划掉并标记为“已移除（日期、原因）”。
• 修改后的验收标准若验证方式不变，则保留原编号；否则将其移除并替换。

与代码的可追溯性。 测试名称中应注明所验证的验收标准（“CA-CONN-27 · 拒绝 API 密钥”）。

node <skill>/scripts/trace.mjs specs/requirements [--code apps,packages] [--write] [--strict]

trace.mjs 按批次列出已测试、仅在代码中引用或未覆盖的验收标准。它会报告代码中引用但未在任何地方定义的标识符（已移除的验收标准、拼写错误），以及规格中标记为“已交付”但其部分验收标准尚未测试的屏幕。要分析的目录在 requirements.json → code 中配置（默认分析整个仓库，但不包括 specs/）。--write 会生成 sources/generated/couverture.md；如需发布进度，可将其纳入附录（``）；--strict 用于 CI。

每次迭代时：重新提取，更新受影响的验收标准，运行 build、check、trace，在 00-titre.md 中提升版本，发布，并在同一次变更中将源文件、构建生成的 Markdown 和 .published.json 与规格一并提交。