古から続くExcelベースの画面設計書から卒業したい話

本稿はJCB Advent Calendar 2025の 12 月 5 日の記事です。

デジタルソリューション開発部アプリチームの服部です。
突然ですが、皆さまは以下のようなドキュメントを一度は目にしたことがあるのではないでしょうか。

呼び方はプロジェクトごとに異なると思いますが（画面設計書、画面項目定義書など）、いずれも画面が持つ項目や振る舞いなどを定義するためのドキュメントです。
私が所属しているプロジェクトでも、同様のドキュメントを Google スプレッドシートで作成しています。

しかし Excel ベースのドキュメントであるがゆえに、次のような課題を感じていました。

生成 AI との連携が限定的
複雑な処理フローの可視化を効率的に行うことが難しい
バージョン管理と差分確認が不便

特に最初の課題については、AI 駆動でシステム開発を進めていくに当たっての大きな障壁になるように思っています。
これらの課題を解消し、効率的に可読性の高いドキュメントを作成すべく、「AI フレンドリーな markdown 形式への移行」と「作成・更新プロセスへの AI 活用」を検討しました。

前提

本記事の内容は VSCode ✕ GitHub Copilot での実行を前提に記載しています（他の AI エージェントでも同様のことは実現可能です）。
プロンプトファイルやカスタム命令ファイル、MCP サーバーに関する記述が登場しますが、それぞれの概要や設定方法についての説明は割愛します。

概観

今回ご紹介する取り組みの全体像は次のとおりです。

AI エージェントが Figma Dev Mode MCP Server やコードベースから情報収集を行い、markdown 形式のテンプレートを読み込んだうえでドキュメントを生成します。
方式自体はシンプルですが、その中でも考慮した点や工夫点を以降で解説します。

開発プロセスへの導入を考慮する

まずどのようなアウトプットにするかではなく、どのように開発プロセスへ組み込むかを重視しました。
AI 活用自体が目的化し、画面設計書の作成・更新手順が煩雑化したり、時間が余計にかかったりしては本末転倒です。誰が実施しても同じ手順で再現でき、チームの標準プロセスとして定着できることを目指しました。

そのため、画面設計書の作成・更新に特化したプロンプトファイルを用意しました。プロンプトファイルの中身においても単なる命令の羅列ではなく、対話式で進行する設計にすることで再現性を高めています。
文量の都合上、以下は一部省略したサンプルです。実際にはこの内容に沿って運用しています。

パス及びファイル名: .github/prompts/create-screen-doc.prompt.md

---
name: create-screen-doc
description: "Figmaデザインまたはコードベースを読み取り、画面設計書を新規作成する"
---

## 目的

Figma のデザインデータまたはコードベースを読み取り、画面が持つ画面項目に関する情報を抽出し、指定された設計ドキュメントを生成することが目的です。

## 手順

下記に従って、画面設計書を作成してください。

1.  はじめに、設計書の作成元を対話式で指定させてください。

    - 対話時は`画面設計書の作成元を選択してください (Figma / Code)`と質問してください。

2.  **Figma を選択した場合**:

    - 対象となる Figma デザインの URL を対話式で指定させてください。(`FigmaデザインのURLを教えてください。`)
    - Figma MCP を使用してデザインデータを読み取り、情報を抽出してください。

3.  **Code を選択した場合**:
    - 対象となるファイルのパスを対話式で指定させてください。(`読み込み対象のページファイルのパスを教えてください。`)
    - **解析手順**:
      <!-- 省略 -->
4.  抽出した情報を基に、以下のテンプレートファイルを使用して、画面設計書を Markdown 形式で作成してください。

    - テンプレートファイルのパス: `docs/screen-designs/screen-design-template.md`

5.  各セクションは以下の instructions ファイルを参照し、記述してください。
    - インストラクションファイルのパス: `.github/instructions/screen-design.instructions.md`
6.  入力ソースからだけでは判断が難しい項目や、開発上の確認が必要な項目については、無理に各セクションを埋めず、空のままとし、その旨をコメントとして明記してください。
7.  作成した画面設計書は、以下の命名規則で`docs/screen-designs`下に保存してください。

成果物品質の安定化（テンプレート）

次に重視したのは成果物の品質安定化です。

「画面仕様が明確であること」はドキュメントの本質ですが、プロジェクトの成果物である以上、基本的なコンテンツ構成やレイアウトは統一されていることが望ましいと考えます。そこでテンプレートを作成し、AI エージェントには中身の記載に専念させるアプローチを採用しました。

以下はテンプレートの一部です。

これにより、生成ごとの記載の揺れを防げています。

成果物品質の安定化（記載粒度）

ただしテンプレートを用意しただけでは、品質は十分に安定しませんでした。

「テンプレートの中身を記載する」という抽象的な指示では自由度が高く、特に処理詳細の部分において記載粒度がばらつきました。

そのため、テンプレートの各項目について「何を書くか」「どの形式・文体で書くか」をカスタム命令ファイルで厳密に定義しました。
例えば以下は、画面の要素一覧を記載するセクションにおける記載ルールです。

パス及びファイル名: .github/instructions/screen-design.instructions.md

<!-- 画面テンプレートの2. 要素一覧に対する記載指示の一部抜粋 -->

- **2. 要素一覧**:
  - 画面内の UI 要素（ボタン、入力フォーム、テキスト、画像など）を洗い出し、テーブルに記載します。
    - 項目名: 画面上に表示されるラベル名や識別名を記載します。
    - 種類: UI 要素のタイプ（例: ボタン、テキストフィールド、ドロップダウンなど）を記載します。
    - 参照元エンドポイント: 要素が参照する API エンドポイントのパスを記載します。（例: /hoge/fuga）
    - イベント： 要素に関連する主要なイベント（例: クリック、要素選択など）を記載します。
      - `[イベント]時、[処理]を実行する`という形式で記載してください。
        - イベント: ユーザー視点での記載を行ってください。`submit`、`onClick`などの記載はしない。
        - 処理: インタラクションによって発生する主要な処理内容を記載します。（例: フォーム送信、モーダル表示など）内部仕様ではなく、外部仕様としての記載を行ってください。
      - 入力フォームのバリデーションに関しては、`3. バリデーション定義`で記述するため、本セクションでは記述しない。

執筆時点でも試行錯誤中ですが、カスタム命令ファイル等で具体的な制約を設けることで記載粒度の統一が進み、AI エージェントの成果物品質が安定することは確認できています。

実践

最後に、Figma から情報を読み取り、画面設計書を新規作成するフローを実践します。

まずプロンプトを実行します。

AI エージェントからの問いに回答して進めます。今回は Figma から生成するため、Figmaと回答します。

対象画面のデザインデータの URL を連携します。

URL を連携すると、MCP サーバー経由でデザインデータを取得し、続いて画面設計書テンプレートを読み込みます。
カスタム命令ファイルの制御により、「対象データから読み取れない内容は無理に記載しない」などのポリシーが適用され、画面設計書が生成されていく様子が確認できます。

生成後は、作業者が生成された成果物の内容を確認・修正を行い、レビュープロセスへと移っていきます。
作業全てを完全に AI エージェントに委譲する事は出来ていませんが、ゼロから作成する事に比べれば遥かに効率化できます。また私のプロジェクトでは、これまで文章ベースで記載していた以下のような処理フローなども生成させることで視認性も向上したと感じており、現時点では好感触を得ています。