requirements-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cahier des charges à partir des specs

基于 specs 生成需求规格说明书

Ce skill part d'un projet de specs (skill

specs-ui

, et le prototype du skill

prototype-ui

s'il existe) et produit le cahier des charges de l'équipe de développement. Les sources sont en Markdown, une par partie. Le build les assemble en deux formats :

un document Markdown, pour un dépôt de code ou un outil de documentation ;
une page HTML publiée comme artifact : sommaire qui suit la lecture, recherche par identifiant, pastilles RF / CA / NF / DT / RQ, diagrammes, thème clair et sombre, boutons « Copier le Markdown », pour le document entier ou une partie. La partie fonctionnelle et UI vient des specs par extraction (aucune réécriture), la partie technique (architecture, stack, infrastructure) est proposée puis validée avec la personne, et le découpage en lots porte des estimations en fourchettes avec leurs hypothèses.

Document et échanges en français. Code des scripts en anglais ; commentaires en français.

<skill>

désigne le dossier de ce skill ; les scripts se lancent depuis le dossier qui contient

specs/ui/

. Aucune dépendance : Node suffit.

本 skill 以 specs 项目为起点（使用

specs-ui

skill；若存在，则也使用

prototype-ui

skill 的原型），为开发团队生成需求规格说明书。源文件采用 Markdown，每个部分对应一个文件。构建过程会将其汇编为两种格式：

一份 Markdown 文档，用于代码仓库或文档工具；
一份作为 artifact 发布的 HTML 页面：目录会随阅读位置同步定位，支持按标识符搜索、RF / CA / NF / DT / RQ 徽章、图表、浅色与深色主题，并提供“复制 Markdown”按钮，可复制整个文档或单个部分。功能与 UI 部分通过提取方式直接来自 specs（不作改写）；技术部分（架构、stack、基础设施）会先提出方案，再与用户确认；分 lot 拆分采用区间估算，并附估算假设。

文档和沟通使用法语。脚本代码使用英语；注释使用法语。

<skill>

表示本 skill 的目录；脚本从包含

specs/ui/

的目录运行。无需任何依赖：Node 即可。

Économiser les tokens (à lire en premier)

节省 tokens（首先阅读）

Les specs d'un produit pèsent souvent plus d'1 Mo de HTML ; le cahier des charges, 150 à 300 Ko de Markdown. Règles :

specs/requirements/REQUIREMENTS.md
est la mémoire : à lire en premier en reprise, et à s'en contenter tant que possible. Elle contient l'avancement par source, les contraintes, les décisions techniques DT, les hypothèses d'estimation et ce qui reste à valider. La tenir à jour à la fin de chaque étape, sous 150 lignes.
Ne jamais lire le HTML des specs :
```
extract.mjs
```
en tire la matière en Markdown dans
```
specs/requirements/sources/generated/
```
(environ 7 fois plus court). Le modèle principal lit
```
generated/inventaire.md
```
et
```
specs/ui/CONTEXTE.md
```
, puis seulement les extraits utiles des lots (par morceaux).

Ne jamais lire les documents assemblés (

specs/requirements/requirements.md

.html

, nommés par

requirements.json

→

output

), ni

specs/requirements/publish/

. On travaille dans

specs/requirements/sources/

(une source par partie), puis

build.mjs

check.mjs

Un fichier par partie : modifier une partie, c'est modifier sa source, pas relire le document.
Déléguer au bon modèle :

Rôle	Modèle	Tâches
Conception	modèle principal	Cadrage, questions, architecture, stack, infrastructure, lots et estimations, exigences non fonctionnelles, présentation, relecture, publication
Rédaction	`sonnet`	Critères d'acceptation d'un lot depuis `generated/lot-<lot>.md` (consigne : `references/redacteur.md` ) ; un rédacteur par lot, en parallèle
Exécution mécanique	`haiku`	Lancer `extract` , `build` , `check` , `trace` et rapporter

Tâche	À lire
Toute étape	`REQUIREMENTS.md`
Plan, identifiants, style	`references/plan.md`
Architecture, stack, infrastructure	`references/architecture.md`
Lots et estimations	`references/estimations.md`

产品 specs 往往会占用超过 1 MB 的 HTML，而需求规格说明书约为 150 至 300 KB 的 Markdown。规则如下：

specs/requirements/REQUIREMENTS.md
是记忆载体：续作时首先阅读，并尽可能只使用该文件。它包含各来源的进度、约束、技术决策 DT、估算假设以及尚待验证的事项。每一步结束时都要更新，并控制在 150 行以内。
绝不读取 specs 的 HTML：
```
extract.mjs
```
会从 specs 中提取内容并转换为 Markdown，保存到
```
specs/requirements/sources/generated/
```
（长度约缩短至七分之一）。主模型读取
```
generated/inventaire.md
```
和
```
specs/ui/CONTEXTE.md
```
，之后只按需读取各 lot 的相关片段（分块读取）。
绝不读取已汇编的文档（即
```
requirements.json
```
→
```
output
```
所指向的
```
specs/requirements/requirements.md
```
和
```
.html
```
），也不要读取
```
specs/requirements/publish/
```
。应在
```
specs/requirements/sources/
```
中开展工作（每个部分一个源文件），然后运行
```
build.mjs
```
和
```
check.mjs
```
。
每个部分一个文件：修改某一部分时，应修改其源文件，而不是重新读取整个文档。
将任务委派给合适的模型：

角色	模型	任务
设计	主模型	项目界定、问题澄清、架构、stack、基础设施、lots 与估算、非功能需求、项目介绍、审校、发布
编写	`sonnet`	根据 `generated/lot-<lot>.md` 编写某个 lot 的验收标准（规范见 `references/redacteur.md` ）；每个 lot 一名编写者，并行执行
机械执行	`haiku`	运行 `extract` 、 `build` 、 `check` 、 `trace` 并汇报

任务	需读取
每个步骤	`REQUIREMENTS.md`
规划、标识符、样式	`references/plan.md`
架构、stack、基础设施	`references/architecture.md`
lots 与估算	`references/estimations.md`

Étape 0 · Prérequis et préparation

步骤 0 · 前置条件与准备

Les livrables de la chaîne vivent dans

specs/

à la racine du projet :

specs/ui

(specs),

specs/prototype

(prototype),

specs/requirements

(ce cahier des charges). Un projet à l'ancienne disposition (

specs-ui/

cdc/

à la racine,

cdc.json

CDC.md

) se range avec

migrate-layout.mjs

du skill

specs-ui

; d'ici là, les scripts lisent encore

cdc.json

Il faut un projet

specs-ui

(avec

sources/site.json

). Sinon, proposer d'abord les specs (skill

specs-ui

). D'autres documents fonctionnels donnés par la personne (brief, notes) se lisent au cadrage et se citent en documents de référence.

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

Le script crée

specs/requirements/

(

requirements.json

REQUIREMENTS.md

, une source par partie avec les valeurs connues déjà remplies), un chapitre par lot dans

30-specs.md

, et lance l'extraction. Un dossier existant n'est pas écrasé : c'est une reprise.

该工作流的交付物位于项目根目录的

specs/

下：

specs/ui

（specs）、

specs/prototype

（原型）、

specs/requirements

（本需求规格说明书）。采用旧目录布局的项目（根目录下的

specs-ui/

、

cdc/

、

cdc.json

、

CDC.md

）应使用

specs-ui

skill 的

migrate-layout.mjs

进行迁移；完成迁移前，脚本仍读取

cdc.json

。

必须具备一个

specs-ui

项目（包含

sources/site.json

）。否则，应先建议创建 specs（使用

specs-ui

skill）。用户提供的其他功能文档（brief、笔记）应在项目界定阶段读取，并列为参考文档。

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

脚本会创建

specs/requirements/

（包括

requirements.json

、

REQUIREMENTS.md

，以及每个部分一个源文件并预先填入已知内容），在

30-specs.md

中为每个 lot 创建一个章节，并启动提取。已有目录不会被覆盖：这属于续作。

Étape 1 · Cadrage

步骤 1 · 项目界定

Lire

specs/ui/CONTEXTE.md

specs/requirements/sources/generated/inventaire.md

. Puis demander avec AskUserQuestion les contraintes qui pèsent sur la technique : hébergement imposé ou souhaité, compétences de l'équipe (langages, frameworks), sécurité et conformité (SSO, données en UE, audit), volumes attendus, budget d'infrastructure, échéance. Toujours une option « pas de contrainte ». Noter les réponses dans

REQUIREMENTS.md

读取

specs/ui/CONTEXTE.md

和

specs/requirements/sources/generated/inventaire.md

。随后使用 AskUserQuestion 询问对技术方案有影响的约束：指定或期望的托管方式、团队技能（语言、frameworks）、安全与合规（SSO、EU 数据、审计）、预期负载量、基础设施预算、截止时间。始终提供“无约束”选项。将回答记录到

REQUIREMENTS.md

。

Étape 2 · Architecture, stack et infrastructure

步骤 2 · 架构、stack 与基础设施

Suivre

references/architecture.md

lire les besoins techniques dans les règles RF et les écrans (temps réel, événements externes, traitements longs, exécution isolée, secrets, multi-tenant…), chacun rattaché à sa règle ;
proposer 2 ou 3 options par décision structurante, avec une recommandation, par AskUserQuestion (4 questions par série, 2 séries au plus) ;
noter chaque décision DT-xx dans
```
REQUIREMENTS.md
```
, puis rédiger
```
60-architecture.md
```
,
```
70-stack.md
```
et
```
80-infrastructure.md
```
(hébergement, environnements, réseau, conteneurs, CI/CD, IaC et secrets, observabilité, sauvegardes, sécurité, coûts).

Rien de technique ne s'écrit comme décidé sans validation : une recommandation non tranchée est notée « à valider ».

按照

references/architecture.md

执行：

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

未经确认，任何技术内容都不得写成已决定事项；尚未定夺的推荐方案应标记为“待确认”。

Étape 3 · Partie fonctionnelle

步骤 3 · 功能部分

Critères d'acceptation : un rédacteur
```
sonnet
```
par lot, en parallèle, avec
```
references/redacteur.md
```
, son fichier
```
generated/lot-<lot>.md
```
et la source
```
lots/<lot>-criteres.md
```
à remplir. Lire leurs comptes rendus : une règle floue devient un point « À valider » ou une question à la personne.
Le modèle principal rédige :
- ```
10-presentation.md
```
  ;
- ```
20-utilisateurs.md
```
  (matrice des rôles depuis les RF) ;
- ```
40-interface.md
```
  (principes, composants, mobile, accessibilité ; les tokens sont générés) ;
- ```
50-exigences-non-fonctionnelles.md
```
  (chiffrées, en reprenant d'abord les valeurs des specs).

验收标准：每个 lot 安排一名
```
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 中的数值）。

Étape 4 · Lots, estimations, risques

步骤 4 · Lots、估算与风险

Suivre

references/estimations.md

lots : lot 0 « Socle », puis les lots des specs ;
estimations : par lot, objectif, périmètre, dépendances, livrables, critères de fin et fourchette en jours ; puis synthèse, hypothèses et planning (
```
gantt
```
) ;
risques et décisions : les risques RQ-xx vont dans
```
95-risques.md
```
(les points ouverts des specs y sont inclus automatiquement), les décisions produit datées dans
```
99-annexes.md
```
.

按照

references/estimations.md

执行：

lots：lot 0“底座”，然后是 specs 中的各 lot；
估算：按 lot 列出目标、范围、依赖关系、交付物、完成标准以及以天为单位的区间；随后给出汇总、假设和排期（
```
gantt
```
）；
风险与决策：RQ-xx 风险写入
```
95-risques.md
```
（specs 中的待决事项会自动纳入），带日期的产品决策写入
```
99-annexes.md
```
。

Étape 5 · Construire, contrôler, publier

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

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

check.mjs

signale :

les parties manquantes ;
les gabarits
```
{{…}}
```
non remplis ;
les liens internes cassés (ancres en ASCII) ;
les identifiants cités sans définition ;
les lots des specs absents du découpage ou sans fourchette ;
les écrans de l'inventaire absents ;
les diagrammes non refermés ;
les identifiants en double.

Corriger jusqu'à zéro problème.

Le build écrit trois fichiers :

```
specs/requirements/requirements.md
```
: le document Markdown ;
```
specs/requirements/requirements.html
```
: la page complète, ouvrable en local, avec les diagrammes rendus ;
```
specs/requirements/publish/requirements.html
```
: la même page sans enveloppe, pour l'outil Artifact (hors du dépôt git : elle se régénère).

Publier
specs/requirements/publish/requirements.html
avec l'outil Artifact (

prepare-publish.mjs specs/requirements

dit s'il y a quelque chose à publier et vers quelle URL). Le titre vient de la balise

<title>

, et l'outil rend les diagrammes

mermaid

lui-même. Republier ce même fichier garde l'URL ; la noter dans

requirements.json

→

artifacts.requirements

et dans

REQUIREMENTS.md

, puis lancer

prepare-publish.mjs specs/requirements --confirm

(empreinte dans

.published.json

, à commiter).

--check

dit si l'artifact est en retard sur la page locale. La page ne peut pas faire télécharger de fichier (le lecteur l'interdit) : le Markdown se récupère par les boutons « Copier », ou dans le fichier

.md

local. Passer la version et le statut dans

00-titre.md

à chaque publication notable.

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

check.mjs

会指出：

缺失的部分；
未填写的
```
{{…}}
```
模板；
失效的内部链接（ASCII 锚点）；
被引用但未定义的标识符；
在拆分中缺失或没有估算区间的 specs lots；
清单中缺失的界面；
未正确闭合的图表；
重复的标识符。

修正直到没有任何问题。

构建过程会写入三个文件：

```
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；将其记录在

requirements.json

→

artifacts.requirements

和

REQUIREMENTS.md

中，然后运行

prepare-publish.mjs specs/requirements --confirm

（哈希指纹写入

.published.json

，需提交至版本库）。

--check

会指出 artifact 是否落后于本地页面。页面不能提供文件下载功能（阅读器禁止此操作）：Markdown 可通过“复制”按钮获取，或从本地

.md

文件获取。每次有重要发布时，将版本和状态更新到

00-titre.md

。

Specs modifiées

Specs 更新

Relancer

extract.mjs specs/requirements

(la partie fonctionnelle suit seule), puis

check.mjs

: il signale les nouveaux écrans absents et les liens cassés. Mettre à jour les critères des lots touchés (rédacteur), les lots et estimations, les risques ; noter la nouvelle version.

重新运行

extract.mjs specs/requirements

（功能部分会自动同步），然后运行

check.mjs

：它会指出新增但缺失的界面和失效链接。更新受影响 lot 的验收标准（由编写者完成）、lots、估算和风险；记录新版本。

Maintenir pendant les développements

开发期间持续维护

Le cahier des charges vit dans le dépôt de l'application (

specs/requirements/

), avec ses sources, le Markdown construit (

requirements.md

sources/generated/

, que l'équipe et les agents lisent sans rien construire) et

.published.json

. La page HTML (

requirements.html

) se reconstruit et reste hors du dépôt, comme

publish/

: l'ajouter au

.gitignore

du projet. Il suit les specs, qui suivent l'implémentation (skill

specs-ui

, étape 7).

Identifiants stables. Le code et les tests citent les identifiants CA-…, RF-… et NF-… : un identifiant ne change jamais de sens et n'est jamais réutilisé.

Un nouveau critère prend le numéro suivant du lot, même s'il s'insère au milieu de la liste.
Un critère abandonné reste, barré et marqué « Retiré (date, raison) ».
Un critère modifié garde son numéro si la vérification reste la même ; sinon il est retiré et remplacé.

Traçabilité avec le code. Un test cite le critère qu'il vérifie dans son nom (« CA-CONN-27 · refuse une clé d'API »).

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

trace.mjs

donne, par lot, les critères testés, seulement référencés dans le code, ou non couverts. Il signale les identifiants cités dans le code mais définis nulle part (critère retiré, faute de frappe) et les écrans « Livré » dans les specs dont des critères ne sont pas testés. Les dossiers à analyser se règlent dans

requirements.json

→

code

(par défaut, tout le dépôt sauf

specs/

--write

produit

sources/generated/couverture.md

, à inclure dans une annexe (

<!-- include: generated/couverture.md -->

) quand on veut publier l'avancement ;

--strict

sert à la CI.

À chaque évolution : réextraire, mettre à jour les critères touchés,

build

check

trace

, monter la version dans

00-titre.md

, publier, et commiter les sources, le Markdown construit et

.published.json

avec les specs, dans le même changement.

需求规格说明书与应用代码一同保存在仓库中（

specs/requirements/

），包括源文件、构建后的 Markdown（

requirements.md

、

sources/generated/

，团队和 agents 无需构建即可读取）以及

.published.json

。HTML 页面（

requirements.html

）需要重新构建，并像

publish/

一样保留在仓库之外：应将其加入项目的

.gitignore

。需求规格说明书跟随 specs 更新，而 specs 跟随实现更新（

specs-ui

skill，第 7 步）。

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

新验收标准使用该 lot 的下一个编号，即使插入在列表中间也是如此。
废弃的验收标准仍会保留，但应加删除线，并标记为“已撤回（日期、原因）”。
修改后的验收标准若验证内容不变，则保留原编号；否则应撤回并替换。

与代码的可追溯性。 测试名称中会引用其验证的标准（

CA-CONN-27 · refuse une clé d'API

）。

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

trace.mjs

会按 lot 列出已测试、仅在代码中引用或未覆盖的标准。它会指出代码中引用但任何地方都未定义的标识符（标准已撤回或拼写错误），也会指出 specs 中标记为 Livré 却仍有标准未经测试的界面。分析目录在

requirements.json

→

code

中配置（默认分析除

specs/

外的整个仓库）。

--write

会生成

sources/generated/couverture.md

；如需发布进展，可将其纳入附录（

<!-- include: generated/couverture.md -->

）。

--strict

用于 CI。

每次演进：重新提取、更新受影响的验收标准、运行

build

、运行

check

、运行

trace

、在

00-titre.md

中更新版本号、发布，并将源文件、构建后的 Markdown 和

.published.json

与 specs 在同一次变更中提交。