【生成AIによる業務変革LOG #11】

図を作る時間がない！GitHub Copilot × Mermaidでコードから図解を自動生成する実践例

• 1.
  はじめに
• 2.
  現場の課題：コード理解はなぜ難しいのか
• 3.
  図解の重要性と「作るのが大変」というジレンマ
• 4.
  今回使用したツール：vscode-mermAIdとは
• 5.
  出力を安定させるための工夫
• 6.
  実際の利用から得られた意見
• 7.
  さいごに

業務でコードを読むとき、「処理の流れがつかみにくい」「全体像を理解するのに時間がかかる」と感じたことはないでしょうか。特に初見のアプリを担当するとき、この壁にぶつかる方は多いと思います。
私自身も、初めて触れるアプリの担当が増える中で、コード理解に多くの時間を費やしていました。「図があればすぐわかるのに、その図を作る余裕がない」このジレンマを解消できないかと考えたのが、今回の取り組みのきっかけです。
本記事では、Copilot Chatとvscode-mermAIdを使ってソースコードから図解資料を自動生成した事例を紹介します。

初めて触れるコードの全体像を掴むのには、どうしても時間がかかります。主な理由としては次のようなものが挙げられます。

• 処理が分散している
  画面遷移やデータ更新の流れが複数ファイルにまたがっており、前後の実装を行き来しながら読む必要がある
• 頭の中で組み立て直す負担
  コードを読み進めるたびに処理の流れを再構築する必要があり、複雑な処理では理解に抜け漏れが発生しやすい
• 経験による差
  理解速度に個人差が出やすく、チーム全体での認識合わせに時間がかかる
• ドキュメントの不足
  開発の過程で設計書が更新されず、最新の仕様がコードにしか残っていないケースも多い

このように、コードだけを手がかりに処理の流れをつかむ作業には一定の難しさがあり、全体像を把握するためには工夫が必要です。

シーケンス図やフローチャートがあると、コード理解は格段に楽になります。視覚的に処理の流れを確認できるため、頭の中で構造を組み立てる負担が大きく減ります。
しかし、こうした図の作成・維持には課題があります。

• 作成・更新の負荷が大きい
  処理を読み解いて図として整理し、さらに変更のたびに更新を続ける必要があるため、作成・維持の双方で稼働(人的コスト)がかかる
• 図と実装が乖離しやすい
  記述量が増えるほど修正の負荷も増し、更新が後回しになった結果、図と実装の内容が乖離していく
• 整備が定着しにくい
  役立つとわかっていても、作成・更新にかかる工数の問題などから十分に整備されないケースが多い

図による理解支援は有効ですが、作成し維持していくのは大変ですよね。この「作成・更新の手間」をAIツールで軽減できないか、というのが今回の取り組みの目的です。

今回は図解資料の作成に、Visual Studio Code（VS Code）で利用できる拡張機能 vscode mermAId を使用しました。Visual Studio Code Marketplace上で公開されており、拡張機能一覧から簡単に導入できます（図1）。これは GitHub Copilot Chat と連携して動作し、コードを解析して Mermaid 記法の図を自動で生成することができます。VS CodeとCopilot Chatが利用できる環境であれば拡張機能の導入のみで無料で利用でき、既存の開発環境に組み込みやすい点が特徴です。

図1 vscode-mermAIdの配布ページ（出典:Visual Studio Marketplace）

• ※
  Visual Studio Marketplace公式ページ
• ※
  GitHubリポジトリ
• ※
  Mermaid記法
  Mermaidはテキストベースで図を記述できる記法です。シーケンス図やフローチャート、クラス図などをコードのように記述することができます。
  参考:Mermaid公式サイト

導入手順は簡単で、VS Code の拡張機能一覧から「vscode mermAId」を検索してインストールするだけです（図2）。追加のセットアップは不要で、他の Copilot 機能と同じ環境のまま利用できました。

図2 拡張機能検索結果

基本的な使い方は、Copilot Chat を開き、図にしたいコードファイルをチャットに添付して、@mermAId を付けて「シーケンス図を作成してください」などと指示するだけです（図3）。

図3 拡張機能を使用したプロンプト入力例

コード量や構成にもよりますが、大体1分もかからずに図が生成されます（図4）。生成結果は Mermaid 記法で出力されるため、必要に応じて追記・調整がしやすい点も有用でした。

図4 出力されたシーケンス図

対応する図の種類は、シーケンス図・フローチャート・クラス図など、Mermaid で表現できる代表的な形式です。用途に応じて出力形式を切り替え、処理の流れや構造の把握に用いることができます（図5）。

図5 出力されたフローチャート

実際に図を生成してみると、コードの内容や与え方によって出力結果にばらつきが生じる場合がありました。そのため、より安定した図を得るためにいくつかの工夫を取り入れながら利用しました。

モデルの選択

プロンプトの工夫

図の作成自体はシンプルなプロンプトのみでも十分可能ですが、ドキュメントとして残したい場合、ある程度統一感のある図を作成したいという要望も生まれると思います。その場合は、カスタムインストラクションを活用することで、図の形式や表現方法にある程度の統一感を持たせることができました。たとえばノード名の付け方や順序などをあらかじめ指定しておくことで、生成される図の見た目が大きく崩れにくくなります（図6）。

図6 作成したカスタムインストラクション

添付ファイルの工夫

vscode mermAId の有効性を確認するために、社内のエンジニア数名にも実際に利用してもらったところ、全体的にコード理解の補助として役に立つという前向きな意見が多く寄せられました。

ポジティブな意見

• 全体像の把握に有用
  コードを読み始める前に処理の大枠を図で確認でき、理解のとっかかりになる
• コメント情報の反映
  コード内のコメントアウトに書かれた補足情報も取り込まれるため、処理の意図を掴みやすい
• 理解の深掘り
  関心のある処理について追加ファイルを渡すと、Copilot Chatがさらに詳しい説明を返してくれる
• その他
  「以前は図を作りづらかったが、この拡張機能で簡単にフローチャートを作れた」
  「テストケースを検討するような場面で概要の把握に役立ちそう」

改善が必要な点

• 階層構造の表現
  詳細を伝えた後に全体図を再生成すると、全て同じ粒度の要素として並んでしまうケースがある
• クラス図の精度
  単一ファイルのみでは属性が不足することがあり、関連ファイルをまとめて渡す必要がある

全体として、コード理解の補助ツールとして十分に実用的であるという評価が得られました。改善点についても、入力の工夫次第で対処できる範囲であり、今後の活用に期待が持てる結果となっています。

今回の取り組みを通じて、図解自動生成ツールが想像以上に手軽かつ高精度であることがわかりました。
特に実感したのは、「とりあえず図にして頭を整理したい」と思ったときにすぐ形にできる手軽さです。内容が多少足りなくても、まず図が出てくることで、ゼロから描き始めるよりも圧倒的に作業のハードルが下がります。
一方で、添付ファイルやプロンプトの与え方によって出力に差が生じる場面もあり、AIに適切な情報を渡す工夫は必要です。ただ、本記事で紹介したモデル選択やカスタムインストラクションの活用で、十分に実用的な結果が得られることは確認できました。
「コードを読んでもなかなか全体像が掴めない」「図を作りたいけど時間がない」もし同じような課題を感じている方がいれば、まずは手元のコードで一度試してみてください。拡張機能を入れてプロンプトを投げるだけなので、数分で効果を体感できるはずです。
図解の作成を「自分で描く」から「ツールに任せる」へ切り替えることで、本質的な理解や設計に集中できる時間が生まれます。本記事がそのきっかけになれば幸いです。

• ※
  本記事では、業務で実際に使用しているコードを例にご紹介しました。ただし、機密情報の保護やセキュリティ上の理由から、変数名や数値等の一部内容は修正しています。
• ※
  本記事中のスクリーンショットはVisual Studio Codeの画面をキャプチャしたものです。
• ※
  GitHubは、GitHub Inc. の商標または登録商標です。
• ※
  Copilotは、米国Microsoft Corporation の米国およびその他の国における登録商標です。
• ※
  Visual Studio CodeはMicrosoft Corporation の商標または登録商標です。