excel-spec-generator

Excel設計書生成スキル

Excelテンプレート（方眼紙形式）をベースに、JSON定義ファイルから機能追加設計書を自動生成するスキルです。

When to Use This Skill

• ユーザーが「Excel設計書を作りたい」「設計書を作成したい」と発言した場合
• 新機能の追加設計書をExcel形式で生成する必要がある場合
• 既存のExcelテンプレートに情報を流し込みたい場合

Prerequisites

• dotnet-script がインストールされていること（dotnet tool install -g dotnet-script）
• .NET 10 ランタイムが利用可能であること
• テンプレートファイル {追加機能概要}機能_設計書_テンプレート.xlsx はスキル内の templates/ に同梱済み

スクリプト一覧

スクリプト	説明
common.csx	ClosedXML参照・共通ヘルパー関数群（MergeWrite, WriteTable, SVG保存等）
generate-spec.csx	メインジェネレーター（JSON読み込み→テンプレート加工→Excel出力）

テンプレート構成（9シート）

シート名	内容	処理方式
表紙	タイトル・メタ情報・改訂履歴	プレースホルダー置換 + 行追加
1.概要	背景目的・スコープ・サービス一覧・用語定義	再構築
2.機能要件	要件テーブル・制限テーブル・遷移図	再構築（可変セクション数）
3.データモデル変更	テーブル定義・ER図・マイグレーション	再構築（3.X 繰り返し）
4.画面設計	画面改修・UI要素テーブル・モックアップ	再構築（4.X 繰り返し）
5.API設計	API一覧・詳細	再構築
6.ビジネスルール	新規ルール・既存影響	再構築
7.開発計画	フェーズ・テスト方針・リスク	再構築
8.ユーザー運用フロー	運用シナリオ	再構築

ワークフロー

Step 1: 情報収集

ユーザーから以下の情報を収集する（対話形式で段階的に質問してよい）:

1. 基本情報: 機能名、文書ID、バージョン、作成者、レビュー者
2. 概要: 背景・目的、ビジネス価値、スコープ
3. 対象サービス: サービス名、課金方式等のリスト
4. 機能要件: 要件ID・要件名・内容・優先度のリスト
5. データモデル変更: テーブル名・カラム定義、ER図、マイグレーションSQL
6. 画面設計: 対象画面・変更点・UI要素定義、モックアップ
7. API設計: API一覧・詳細（リクエスト/レスポンス）
8. ビジネスルール: 新規ルール・既存ルールへの影響
9. 開発計画: フェーズ・テスト方針・リスク
10. 運用フロー: シナリオ定義

Step 2: JSON定義ファイル生成

収集した情報をもとに、docs/specs/ 配下にJSON定義ファイルを作成する。 ファイル名: {機能名略称}-spec-def.json

Step 3: Excel設計書生成

cd /workspaces/ai-sdlc-demo/.github/skills/excel-spec-generator/scripts
dotnet-script generate-spec.csx -- /workspaces/ai-sdlc-demo/docs/specs/{機能名略称}-spec-def.json

Step 4: 結果確認

生成されたExcelファイルのパスをユーザーに報告する。SVG図がある場合はSVGファイルも報告する。

JSON定義ファイル仕様

基本構造

{
  "output": "機能名_設計書.xlsx",
  "templatePath": "(省略可: テンプレートのフルパス)",
  "cover": { ... },
  "overview": { ... },
  "requirements": [ ... ],
  "dataModel": { ... },
  "screenDesign": [ ... ],
  "apiDesign": { ... },
  "businessRules": { ... },
  "devPlan": { ... },
  "operationFlow": { ... }
}

省略可能: 各セクションはオプション。省略されたセクションはテンプレートのまま。

テーブル定義の共通フォーマット

すべてのテーブルは以下の形式で定義する:

{
  "headers": ["列名1", "列名2", "列名3"],
  "columnWidths": [10, 20, 26],
  "rows": [
    ["値1", "値2", "値3"],
    ["値4", "値5", "値6"]
  ]
}

• headers: テーブルヘッダーのテキスト配列
• columnWidths: 各列の方眼紙グリッド幅（合計が56になるように調整。列3〜58 = 56マス分）
• rows: データ行の2次元配列

headers を省略した場合、各シートのデフォルトヘッダーが使用される。 columnWidths を省略した場合、各シートのデフォルト幅が使用される。

各セクション詳細

cover（表紙）

{
  "cover": {
    "タイトル": "試用機能の有効化 追加設計書",
    "文書ID": "DES-TRL-001",
    "バージョン": "1.0",
    "作成日": "2026-03-15",
    "作成者": "開発チーム",
    "レビュー者": "レビュアー",
    "ステータス": "ドラフト",
    "改訂履歴": [
      {
        "版数": "1.0",
        "日付": "2026-03-15",
        "変更者": "開発チーム",
        "変更内容": "初版作成"
      }
    ]
  }
}

overview（1.概要）

{
  "overview": {
    "背景目的": "テキスト（改行は\\nで記述）",
    "ビジネス価値": "テキスト",
    "スコープ": "テキスト",
    "tables": [
      {
        "title": "1.3 対象サービス",
        "headers": ["No.", "サービス名", "課金方式", "備考"],
        "columnWidths": [4, 19, 15, 18],
        "rows": [["1", "予約管理", "月額固定", ""]]
      },
      {
        "title": "1.4 用語定義",
        "headers": ["用語", "定義"],
        "columnWidths": [13, 43],
        "rows": [["試用期間", "無料で利用できる期間"]]
      }
    ]
  }
}

requirements（2.機能要件）— 配列

各サブセクションを配列で定義する。テーブルまたはSVG図を含むことができる。

{
  "requirements": [
    {
      "title": "2.1 機能要件名",
      "description": "(省略可) セクション説明テキスト",
      "headers": ["要件ID", "要件名", "要件内容", "優先度"],
      "columnWidths": [10, 13, 25, 8],
      "rows": [["FR-TRL-01", "試用開始", "説明", "高"]]
    },
    {
      "title": "2.3 ステータス遷移図",
      "description": "遷移の説明テキスト",
      "svg": "<svg ...>...</svg>"
    }
  ]
}

デフォルト列定義:

• 要件テーブル: [10, 13, 25, 8] = 要件ID / 要件名 / 要件内容 / 優先度
• サービス制限: [4, 19, 9, 16, 8] = No. / サービス名 / 試用期間 / 機能制限 / 備考

dataModel（3.データモデル変更）

3.X セクションはテーブル数に応じて自動的に番号付けされる。

{
  "dataModel": {
    "tables": [
      {
        "name": "CONTRACT",
        "type": "変更",
        "overview": "説明テキスト",
        "headers": ["カラム名", "データ型", "NULL", "説明"],
        "columnWidths": [12, 11, 7, 26],
        "rows": [["trial_start_date", "DATE", "NULL可", "試用開始日"]]
      }
    ],
    "erDiagram": { "svg": "<svg ...>...</svg>" },
    "migration": "ALTER TABLE ... (改行は\\nで記述)"
  }
}

デフォルト列定義: [12, 11, 7, 26] = カラム名 / データ型 / NULL / 説明

screenDesign（4.画面設計）— 配列

4.X セクションは画面数に応じて自動番号付け。

{
  "screenDesign": [
    {
      "target": "テナント詳細",
      "overview": "試用開始ボタンの追加",
      "changes": "変更点の説明テキスト",
      "headers": ["No.", "UI要素", "仕様", "権限"],
      "columnWidths": [4, 14, 25, 13],
      "rows": [["1", "試用開始ボタン", "仕様説明", "admin, sales"]],
      "mockup": { "svg": "<svg ...>...</svg>" }
    }
  ]
}

デフォルト列定義: [4, 14, 25, 13] = No. / UI要素 / 仕様 / 権限

apiDesign（5.API設計）

{
  "apiDesign": {
    "apis": {
      "headers": ["種別", "メソッド", "エンドポイント", "説明", "権限"],
      "columnWidths": [6, 6, 21, 15, 8],
      "rows": [
        ["新規", "POST", "/api/v1/trials/start", "試用開始", "admin, sales"]
      ]
    },
    "details": [
      {
        "title": "5.2 API名",
        "description": "概要テキスト",
        "request": "POST /api/v1/...\nContent-Type: application/json\n{...}",
        "response": "200 OK\n{...}",
        "errorCodes": "400: エラー説明\n404: 説明"
      }
    ]
  }
}

デフォルト列定義: [6, 6, 21, 15, 8] = 種別 / メソッド / エンドポイント / 説明 / 権限

businessRules（6.ビジネスルール）

{
  "businessRules": {
    "newRules": {
      "headers": ["ルールID", "ルール名", "ルール内容"],
      "columnWidths": [10, 13, 33],
      "rows": [["RULE-TRL-01", "ルール名", "内容"]]
    },
    "existingImpact": {
      "headers": ["既存ルールID", "影響箇所", "変更内容"],
      "columnWidths": [10, 13, 33],
      "rows": [["RULE-xxx", "影響箇所", "変更内容"]]
    }
  }
}

デフォルト列定義:

• 新規ルール: [10, 13, 33] = ルールID / ルール名 / ルール内容
• 既存影響: [10, 13, 33] = 既存ルールID / 影響箇所 / 変更内容

devPlan（7.開発計画）

{
  "devPlan": {
    "phases": {
      "headers": ["フェーズ", "内容", "期間", "主な成果物", "担当"],
      "columnWidths": [6, 17, 13, 12, 8],
      "rows": [["Phase 1", "DB設計・API実装", "2週間", "成果物", "BE担当"]]
    },
    "testPolicy": "テスト方針テキスト（複数行は\\nで区切り）",
    "risks": {
      "headers": ["No.", "リスク・課題", "対策", "ステータス"],
      "columnWidths": [4, 14, 25, 13],
      "rows": [["1", "リスク内容", "対策", "未対応"]]
    }
  }
}

デフォルト列定義:

• フェーズ: [6, 17, 13, 12, 8] = フェーズ / 内容 / 期間 / 主な成果物 / 担当
• リスク: [4, 14, 25, 13] = No. / リスク・課題 / 対策 / ステータス

operationFlow（8.ユーザー運用フロー）

{
  "operationFlow": {
    "scenarios": {
      "headers": ["フェーズ", "内容", "期間", "主な成果物", "担当"],
      "columnWidths": [6, 17, 13, 12, 8],
      "rows": [["申込", "操作内容", "即時", "結果", ""]]
    }
  }
}

デフォルト列定義: [6, 17, 13, 12, 8] = フェーズ / 内容 / 期間 / 主な成果物 / 担当

SVG図の取り扱い

• SVG文字列は JSON 内の svg プロパティに格納する
• 生成時、SVGファイルは出力Excelと同じディレクトリに保存される
• Excel内には [図: ファイル名.svg を参照] のテキストが挿入される
• ステータス遷移図、ER図、画面モックアップなどに使用

SVG構築のガイドライン

• 幅600〜800px、高さ200〜600pxを推奨
• テキストは font-size="12" 以上で可読性を確保
• 色はプロジェクトのカラースキーム（青: #0070C0, 緑: #4CAF50, オレンジ: #FF9800）を推奨
• 矢印にはSVG marker を使用

複数行テキスト

• JSON内の文字列で \n を使うと、Excel上では複数行に展開される
• 各行は個別の行（セル）として出力される

columnWidths 設計ガイド

方眼紙のグリッドでは列3〜58の 56マス がデータ領域。columnWidths の合計が56になるように設定する。

よく使うパターン:

パターン	列数	columnWidths
2列（名前+説明）	2	[13, 43]
3列（ID+名前+内容）	3	[10, 13, 33]
4列（ID+名前+内容+優先度）	4	[10, 13, 25, 8]
4列（No.+要素+仕様+権限）	4	[4, 14, 25, 13]
4列（名前+型+NULL+説明）	4	[12, 11, 7, 26]
5列（種別+メソッド+EP+説明+権限）	5	[6, 6, 21, 15, 8]
5列（フェーズ+内容+期間+成果物+担当）	5	[6, 17, 13, 12, 8]

Troubleshooting

問題	解決方法
dotnet-script が見つからない	dotnet tool install -g dotnet-script
テンプレートが見つからない	スキルの templates/ ディレクトリに {追加機能概要}機能_設計書_テンプレート.xlsx が存在するか確認。または JSON内 templatePath で指定
JSONパースエラー	JSONのエスケープ（特に \n, " の扱い）を確認
列がはみ出す	columnWidths の合計が56を超えていないか確認
シートが空になる	JSONのセクションキー名（cover, overview 等）が正しいか確認