GitHub CopilotのAgentモードを使って、I/F仕様書を自動生成してみた

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

こんにちは。JCBデジタルソリューション開発部 MyJCBアプリチームのバックエンドエンジニアの原田です。

私が所属するチームでは、GitHub Copilotを始めとしたAIを用いたシステム開発の効率化に取り組んでいます。

今回はGitHub CopilotのAgentモードを使ってI/F仕様書を自動生成するため、プロンプトを定義するマークダウンファイルを実装・検証しました。

実装する過程の工夫や検証を通して見つかった課題についてご紹介いたします。

1. はじめに

GitHub Copilotは、コーディングから設計・修正までを幅広く支援する開発者専用AIです。

特に「Agentモード」は、ファイルを横断して作業し特定のタスク（ワークフロー）を自動化できることが特徴です。

今回はこのAgentモードを活用し、指示書となるマークダウンファイルを読み込ませることで、I/F仕様書の自動生成を実現します。

2. 前提

MyJCBバックエンドシステム(以下、BE)は、下のシステム概要図のようにスマートフォンアプリと連携システムをつなぐ中継APIサーバとしての役割を担っています。

そのため、BEのI/F仕様は連携システムのI/F仕様に基づいた構成となっています。

I/F仕様書の作成・修正作業は連携システムのI/F仕様書（Googleスプレッドシート）を参照し、項目名やデータ型、桁数、項目の必須・非必須などの仕様を再定義してBEのI/F仕様書（YAMLファイル）に落とし込みます。

I/F仕様書の作成・修正作業は1APIあたり2,3時間ほどの時間を要します。

3. 目的

今回、I/F仕様書の自動生成に取り組む目的はI/F仕様書作成の作業時間を短縮することです。

I/F仕様書の作成は高頻度かつ定型的な作業であるため、AIによる自動化に非常に適していると考えました。

ここで削減した時間を開発やテスト業務に充てることで、システム開発のスピードアップおよび品質向上を目指します。

4. 実装

ここからはプロンプトで利用するファイルと処理の流れについて説明します。

プロンプトで利用するファイルは以下の4つです。下の3つのマークダウンファイルは自動生成するために実装したものです。

GoogleスプレッドシートのI/F仕様書：プロンプト実行時に読み込ませる
api_specification_prompt.md：プロンプトの手順や処理について定義
intermediate.md：YAMLに修正するための前処理として、Googleスプレッドシートをcsv→jsonに変換
api_specification_guideline.md：生成するYAMLファイルのテンプレート

処理の流れは以下のプロンプト概要図とapi_specification_prompt.mdの通りです。

api_specification_prompt.md

---
mode: 'agent'
---

CSVファイルを参考にしてI/F仕様書をYAMLファイルで作成することが目的です。

下記に従ってI/F仕様書作成を行ってください。

## 入力情報の取得

1. {csv_file_path} を対話式で指定させ、指定されたCSVファイルを読み込んでください（ローカルファイル）。
2. {api_category} を対話式で指定させてください（APIカテゴリ）。
3. {api_name} を対話式で指定させてください（APIの名称）。

## ファイル確認と差分表示

4. 対象ファイル `{api_category}/{api_name}.yaml` が既に存在するか確認してください。
   - **存在しない場合**: 新規作成モードで次のステップへ進みます。
   - **存在する場合**: 既存ファイルを読み込み、追加修正モードで次のステップへ進みます。

## I/F仕様書の作成・更新

5. 読み込んだCSVファイルの内容を分析し、以下の情報を抽出してください：
   - APIエンドポイント（パス、HTTPメソッド）
   - リクエスト/レスポンスパラメータ
   - データ構造・制約・説明

6. #file:api_specification_guideline.md の手順3のYAMLフォーマットに従って、I/F仕様書を作成または更新してください。
   - 新規作成の場合: 読み込んだ内容をもとにI/F仕様書を作成します。
   - 追加修正の場合: 既存ファイルとの差分を明示的に表示し、ユーザーに実装の確認を求めてください。ユーザーが承認したら変更を適用します。

## ファイル保存とバリデーション
7. 作成または更新したI/F仕様書を `{api_category}/{api_name}.yaml` に保存してください。
   - 既存ファイルがある場合は上書きします。

8. バリデーションを行い、フォーマットが正しいことを確認してください。

## HTML変換

9. 作成したYAMLファイルをRedocly（APIドキュメント生成ツール）でHTMLに変換してください。
   - HTMLファイルは同じディレクトリ（`{api_category}/`）に保存してください。

## 完了報告

10. 作成完了後、以下の情報を出力してください：
    - YAMLファイルパス
    - HTMLファイルパス
    - 作成内容の概要（エンドポイント一覧・主要スキーマ）