requirements-docx

USDM/EARS 要件文書 — Word エクスポート

要件文書の書式設定を専門としています。USDM/EARS 形式の Markdown 要件文書を、クライアントへの提出に適した、プロフェッショナルな形式の Word（.docx）ファイルに変換します。

重要：要件の作成や変更は行いません。それは usdm および ears スキルの役割です。既存の Markdown 要件文書を Word 形式に書式設定するだけです。

入力

USDM テンプレート構造（skills/usdm/templates/usdm-requirements.md）に準拠した Markdown ファイルを受け付けます。入力ファイルには、次の内容が含まれます。

• メタデータ表：文書 ID、バージョン、ステータス、作成者、日付
• チケット参照表
• ステークホルダー表
• 用語集表
• 要件セクション：Reason、Description、および SPEC-NNN 仕様を含む REQ-NNN 階層
• トレーサビリティマトリックス表
• 未解決の質問表
• 変更履歴表

EARS 形式の仕様（WHEN、WHILE、IF、THEN、WHERE のキーワードを含む）は、要件セクション内でサポートされています。

ワークフロー

ステップ 1：入力の解析と検証

1. ユーザーが指定したソース Markdown ファイルを読み込みます。
2. メタデータ表からメタデータ項目を抽出します。
   • Document ID、Version、Status、Author、Created、Last Updated
3. すべての要件（### REQ-{NNN}: {Title} または #### REQ-{NNN}-{N}: {Title} に一致する見出し）と、それらの Reason/Description フィールド（太字で始まる段落 **Reason**: および **Description**:）を抽出します。
4. すべての仕様（#### SPEC-{NNN}: {Title}、##### SPEC-{NNN}: {Title}、または ###### SPEC-{NNN}: {Title} に一致する見出し）とその本文を抽出します。
5. すべての表（チケット参照、ステークホルダー、用語集、トレーサビリティマトリックス、未解決の質問、変更履歴）を抽出します。
6. 検証：
   • 必須のメタデータ項目（Document ID、Version、Author）が不足している場合は、ユーザーに通知し、続行する前に入力を求めます。
   • 要件に仕様が 1 つもない場合は、ユーザーに警告し、該当する要件 ID を一覧表示します。
7. 解析結果（検出した REQ、SPEC、表の数）をユーザーに報告します。

ステップ 2：文書レイアウトの計画

文書の構成を決定します。

1. セクション 1 — 表紙：タイトル、ロゴのプレースホルダー、メタデータ表、機密保持に関する通知
2. セクション 2 — 目次：見出しスタイルから自動生成
3. セクション 3 — 本文：
   • ステークホルダー表
   • 用語集表
   • 要件（Reason/Description/仕様を含む完全な階層）
   • トレーサビリティマトリックス表
   • 未解決の質問表
   • 変更履歴表

続行する前に、レイアウトをユーザーに確認します。

ステップ 3：docx-js の落とし穴ガイドを読む（必須）

コードを生成する前に、docx-js の落とし穴ガイドを必ず読んでください。

このスキルのディレクトリにある references/docx-js-pitfalls.md ファイルを読み込みます。

ステップ 4：docx-js スクリプトの生成と実行

1. このスキルのディレクトリにある references/docx-style-definitions.md からスタイル定義を読み込みます。
2. このスキルのディレクトリにある references/document-structure-mapping.md からドキュメント構造のマッピングを読み込みます。
3. プロジェクトのルートに scripts/usdm-md-to-docx.js という変換スクリプトがすでに存在するか確認します。
   • 存在する場合：既存のスクリプトを使用します。スクリプトが失敗する場合、または出力に問題がある場合は、新しい一時スクリプトを作成せず、既存のスクリプトをその場で修正します。
   • 存在しない場合：JavaScript ファイルを scripts/usdm-md-to-docx.js（永続的な場所）に生成します。.tmp/ にスクリプトを生成したり、実行後に削除したりしないでください。
4. 生成するスクリプトでは、以下を実装する必要があります。
   • ロゴのプレースホルダー、タイトル、メタデータ表、機密保持に関する通知を含む表紙
   • Heading 1 から Heading 4 を参照する目次
   • 表紙の後、および目次の後に改ページ
   • 適切な見出しレベルを使用した、すべての内容セクション
   • 仕様テキスト内の EARS キーワードの太字書式
   • ヘッダー行のスタイルを設定した、すべての表
   • ヘッダーとフッター
5. node でスクリプトを実行し、.docx ファイルを生成します。

ステップ 5：出力と検証

1. .docx ファイルを現在の作業ディレクトリに保存します。
2. メタデータの Document ID を使用してファイル名を付けます（例：REQ-DOC-20260221-001-requirements-docx.docx）。Document ID が見つからない場合は、入力ファイル名に .docx 拡張子を付けます。
3. 出力ファイルのパスとサイズをユーザーに報告します。
4. レイアウトに問題があると思われる場合は、内部構造を検証します。

   # Check heading styles are applied (pStyle should appear)
   unzip -p <output.docx> word/document.xml | xmllint --format - | grep pStyle
   # Check table grid columns are not defaulting to 100
   unzip -p <output.docx> word/document.xml | xmllint --format - | grep gridCol
   

5. LibreOffice による視覚的な検証は、soffice がインストールされている場合のみ利用できます。

   which soffice && soffice --headless --convert-to pdf <output.docx>
   

ドキュメント構造のマッピング

見出しレベルのマッピング

Markdown 要素	Word スタイル	説明
# Document Title	表紙のタイトル（28pt、太字、中央揃え）	表紙用に抽出し、本文では繰り返しません
## Section Name	Heading 1	最上位のセクション（Stakeholders、Glossary、Requirements など）
### REQ-NNN: Title	Heading 2	最上位の要件
#### REQ-NNN-N: Title	Heading 3	サブ要件
#### SPEC-NNN: Title	Heading 3	最上位要件の直下にある仕様
##### SPEC-NNN: Title	Heading 4	サブ要件の下にある仕様
##### REQ-NNN-N-N: Title	Heading 4	サブサブ要件
###### SPEC-NNN: Title	Heading 4	サブサブ要件の下にある仕様

フィールドの書式設定

フィールド	書式
**Reason**: text	「Reason:」ラベルを太字にし、同じ行の後ろに通常の太さのテキストを配置
**Description**: text	「Description:」ラベルを太字にし、同じ行の後ろに通常の太さのテキストを配置

EARS キーワードの書式設定

仕様本文（SPEC-NNN 見出しの下のテキスト）では、EARS キーワードを太字にします。

• キーワード：WHEN、WHILE、IF、THEN、WHERE
• 仕様テキストをキーワードの境界で TextRun セグメントに分割します
• キーワードの TextRun は太字にし、その前後のテキストは通常の太さにします
• キーワードは、大文字の \b(WHEN|WHILE|IF|THEN|WHERE)\b という正規表現で識別します
• shall と may のキーワードも太字にします

変換例：

Input:  "WHEN the user submits valid credentials, the system shall authenticate the user."
Output: [Bold:"WHEN"] [Normal:" the user submits valid credentials, the system "] [Bold:"shall"] [Normal:" authenticate the user."]

表の書式設定

すべての表には共通の書式を適用します。

• ヘッダー行：太字テキスト＋薄い青色の背景（#D5E8F0）
• 罫線：薄いグレー（#CCCCCC）、単線
• セルのパディングは表レベルのマージンで設定

表	列数	備考
メタデータ	2（フィールド、値）	最初の列を太字にする
チケット参照	3（ソース、ID、タイトル）	標準
ステークホルダー	3（役割、名前／チーム、懸念事項）	標準
用語集	2（用語、定義）	用語の列を太字にする
トレーサビリティマトリクス	4（ソース、REQ、SPEC、検証方法）	標準
未解決の質問	4（番号、質問、起票者、ステータス）	標準
変更履歴	4（バージョン、日付、作成者、説明）	標準

表紙レイアウト

┌─────────────────────────────────┐
│                                 │
│     [Logo Placeholder Area]     │  ← Gray bordered rectangle, centered
│     (Company Logo)              │
│                                 │
│                                 │
│     ┌───────────────────────┐   │
│     │   Document Title      │   │  ← 28pt bold, centered
│     │   (from H1 heading)   │   │
│     └───────────────────────┘   │
│                                 │
│     ┌───────────────────────┐   │
│     │ Document ID │ value   │   │  ← Metadata table
│     │ Version     │ value   │   │
│     │ Status      │ value   │   │
│     │ Author      │ value   │   │
│     │ Created     │ value   │   │
│     │ Last Updated│ value   │   │
│     └───────────────────────┘   │
│                                 │
│     CONFIDENTIAL                │  ← Confidentiality notice, centered
│                                 │
└─────────────────────────────────┘

ヘッダーとフッター（メインコンテンツセクション）

• ヘッダー：ドキュメント ID（左揃え）＋ドキュメントタイトル（右揃え）
• フッター：「全 Y ページ中 X ページ目」（中央揃え）

スタイルのリファレンス

references/docx-style-definitions.md のスタイルを適用します。主なポイント：

• フォント：Arial（ascii/hAnsi）＋ Yu Gothic（eastAsia、日本語対応）
• 本文：11pt（サイズ：半ポイント単位で 22）
• TOC との互換性を保つため、適切な outlineLevel を設定した見出しスタイルのオーバーライドを使用します
• 表の網かけ：黒い背景になる問題を避けるため、常に ShadingType.CLEAR を使用します

リファレンス

• references/docx-js-pitfalls.md — docx-js の使用時に注意すべき重要な落とし穴（CRLF、見出しスタイル）
• references/document-structure-mapping.md — docx-js のコードパターンを含む、Markdown から Word への詳細なマッピング
• references/docx-style-definitions.md — 再利用可能な docx-js スタイルオブジェクトの定義
• examples/conversion-example.md — 変換前後の手順例