requirements-doc

仕様書から要件定義書を作成

このスキルは仕様書プロジェクト（スキル specs-ui と、存在する場合はスキル prototype-ui のプロトタイプ）を基に、開発チーム向けの要件定義書を作成します。ソースはパートごとに1つの Markdown ファイルで作成します。ビルドでは、次の2つの形式にまとめます。

• コードリポジトリやドキュメントツール向けの Markdown ドキュメント。
• artifact として公開される HTML ページ。読み進める位置に追従する目次、ID 検索、RF / CA / NF / DT / RQ のバッジ、図、ライトテーマとダークテーマ、「Markdown をコピー」ボタンを備え、ドキュメント全体またはパートごとにコピーできます。機能面と UI の内容は仕様書から抽出します（書き換えは一切行いません）。技術面（アーキテクチャ、スタック、インフラストラクチャ）は提案したうえで、担当者と確認します。ロット分割では、前提条件とともに幅を持たせた見積もりを提示します。

ドキュメントとやりとりはフランス語で行います。スクリプトのコードは英語、コメントはフランス語です。<skill> はこのスキルのフォルダーを指します。スクリプトは specs/ui/ を含むフォルダーから実行します。依存関係はなく、Node だけで動作します。

トークンを節約する（最初にお読みください）

製品仕様書は HTML で 1 MB を超えることが多く、要件定義書も Markdown で 150～300 KB になります。次のルールに従ってください。

1. specs/requirements/REQUIREMENTS.md がメモリです：作業を再開するときは最初に読み、できる限りこれだけを参照してください。ソースごとの進捗状況、制約、技術的決定 DT、見積もりの前提条件、未確認の事項を記載しています。各ステップの最後に更新し、150 行未満に保ってください。
2. 仕様書の HTML は決して読まないでください：extract.mjs が内容を Markdown に抽出し、specs/requirements/sources/generated/ に保存します（約 7 分の 1 の長さです）。メインモデルは generated/inventaire.md と specs/ui/CONTEXTE.md を読み、その後、ロットごとの必要な抜粋のみを（分割して）読みます。
3. **結合済みドキュメント（specs/requirements/requirements.md と .html。出力先は requirements.json の output で指定）や specs/requirements/publish/ は決して読まないでください。**作業対象は specs/requirements/sources/（パートごとに1つのソース）です。その後、build.mjs と check.mjs を実行します。
4. パートごとにファイルを1つ作成します：パートを変更する場合は、そのソースを変更し、ドキュメントを読み直さないでください。
5. 適切なモデルに作業を委任します：

役割	モデル	タスク
設計	メインモデル	スコープの設定、質問、アーキテクチャ、スタック、インフラストラクチャ、ロットと見積もり、非機能要件、プレゼンテーション、レビュー、公開
執筆	sonnet	generated/lot-<lot>.md を基にしたロットの受け入れ基準（指示：references/redacteur.md）；ロットごとに1人の執筆者を割り当て、並行して作業
機械的な実行	haiku	extract、build、check、trace を実行し、結果を報告

タスク	読むもの
すべてのステップ	REQUIREMENTS.md
計画、ID、スタイル	references/plan.md
アーキテクチャ、スタック、インフラストラクチャ	references/architecture.md
ロットと見積もり	references/estimations.md

ステップ 0 · 前提条件と準備

この一連の成果物は、プロジェクトのルートにある specs/ に配置します。具体的には、specs/ui（仕様書）、specs/prototype（プロトタイプ）、specs/requirements（この要件定義書）です。旧来の構成（ルートに specs-ui/、cdc/、cdc.json、CDC.md があるプロジェクト）は、スキル specs-ui の migrate-layout.mjs を使って整理します。それまでは、スクリプトは引き続き cdc.json を読み込みます。

specs-ui プロジェクト（sources/site.json を含む）が必要です。ない場合は、まず仕様書の作成を提案してください（スキル 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つずつ作成して、抽出を実行します。既存のフォルダーは上書きされません。既存の場合は、作業再開として扱います。

ステップ 1 · 要件の整理

specs/ui/CONTEXTE.md と specs/requirements/sources/generated/inventaire.md を読みます。次に、技術上の制約（指定または希望するホスティング、チームのスキル（言語、フレームワーク）、セキュリティとコンプライアンス（SSO、EU 内のデータ保管、監査）、想定される利用規模、インフラ予算、期限）について、AskUserQuestion で質問します。必ず「制約なし」の選択肢を用意します。回答を REQUIREMENTS.md に記録します。

ステップ 2 · アーキテクチャ、スタック、インフラ

references/architecture.md に従います。

1. RF のルールと画面にある技術的ニーズ（リアルタイム、外部イベント、長時間の処理、隔離された実行環境、シークレット、マルチテナントなど）を読み取り、それぞれを対応するルールに紐づけます。
2. 構造上重要な判断ごとに、AskUserQuestion を使って2〜3 個の選択肢と推奨案を提示します（1 回につき 4 問まで、最大 2 回）。
3. 各判断を DT-xx として REQUIREMENTS.md に記録し、60-architecture.md、70-stack.md、80-infrastructure.md（ホスティング、環境、ネットワーク、コンテナー、CI/CD、IaC とシークレット、オブザーバビリティ、バックアップ、セキュリティ、コスト）を作成します。

技術的な内容は、承認を得ずに決定事項として記載してはいけません。結論が出ていない推奨案は「要確認」と記載します。

ステップ 3 · 機能面

• 受け入れ基準：references/redacteur.md、各自の generated/lot-<lot>.md ファイル、記入する lots/<lot>-criteres.md を使い、各ロットにつき sonnet のライターを 1 名ずつ並行して割り当てます。作成された報告書を読み、不明瞭なルールは「要確認」事項または担当者への質問にします。
• メインモデルが作成するもの：
  • 10-presentation.md；
  • 20-utilisateurs.md（RF に基づくロールのマトリクス）；
  • 40-interface.md（原則、コンポーネント、モバイル、アクセシビリティ。トークンは生成されます）；
  • 50-exigences-non-fonctionnelles.md（数値で記載し、まず仕様書の値を使用）。

ステップ 4 · ロット、見積もり、リスク

references/estimations.md に従います。

• ロット：ロット 0「基盤」、続いて仕様書のロット。
• 見積もり：ロットごとに、目標、範囲、依存関係、成果物、完了基準、日数の範囲を記載します。その後、サマリー、前提条件、計画（gantt）を作成します。
• リスクと判断：リスク RQ-xx は 95-risques.md に記載します（仕様書の未解決事項は自動的に含まれます）。プロダクトに関する判断は日付を付けて 99-annexes.md に記載します。

ステップ 5 · ビルド、確認、公開

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

check.mjs は次の項目を報告します。

• 不足している部分
• 未入力の {{…}} テンプレート
• 壊れた内部リンク（ASCII のアンカー）
• 定義されていない引用識別子
• 分割に含まれていない、または範囲が設定されていない仕様のロット
• インベントリにない画面
• 閉じられていない図
• 重複した識別子

問題がゼロになるまで修正します。

ビルドでは、3 つのファイルが出力されます。

• 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/。チームとエージェントはビルドせずにこれを読みます）、.published.json とともに置きます。HTML ページ（requirements.html）は再ビルドするため、publish/ と同様にリポジトリ外に置きます。プロジェクトの .gitignore に追加してください。要件定義書は仕様に従い、仕様は実装に従います（スキル specs-ui、ステップ 7）。

安定した識別子。 コードとテストでは CA-…、RF-…、NF-… の識別子を参照します。識別子の意味は決して変えず、再利用もしません。

• 新しい基準には、リストの途中に追加する場合も、ロット内の次の番号を付けます。
• 廃止した基準は残し、取り消し線を付けて「Retiré (date, raison)」と記します。
• 変更した基準は、検証内容が同じなら番号を維持します。異なる場合は廃止して置き換えます。

コードとのトレーサビリティ。 テスト名には検証対象の基準を記載します（「CA-CONN-27 · API キーを拒否する」）。

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

trace.mjs はロットごとに、テスト済み、コードで参照のみ、または未カバーの基準を示します。また、コードで引用されているもののどこにも定義されていない識別子（廃止された基準、タイプミス）と、仕様で「Livré」とされた画面のうち、基準がテストされていないものを報告します。解析するディレクトリは requirements.json → code で設定します（デフォルトでは、specs/ を除くリポジトリ全体です）。--write を指定すると sources/generated/couverture.md が生成されます。進捗を公開する場合は、これを付録（``）に含めます。--strict は CI 用です。

変更のたびに：再抽出し、影響を受ける基準を更新して、build、check、trace を実行します。00-titre.md のバージョンを上げて公開し、仕様と同じ変更にソース、ビルド済みの Markdown、.published.json を含めてコミットします。