GitHub Copilotでドキュメント作成を効率化｜VS Code×Mermaidで設計意図を可視化する方法
プログラムを書いて、動作確認まで終わった。
「よし、これで完成！」
……と思ったところで、最後に待っているのがドキュメント作成です。
正直なところ、ここが一番面倒に感じることはありませんか？
コードを書くときは、実際に動くものが目の前にできていくので楽しいんですよね。
ところがドキュメントとなると、
- この処理は何のためにあるのか
- どのファイルがどの処理を担当しているのか
- 処理の流れはどうなっているのか
- 他の人が見たときに理解できるか
といったことを整理して文章にしなければなりません。
そこで今回使ってみたのがGitHub Copilotです。
今回は、これまで作成してきた天気予報アプリを題材に、GitHub Copilotでコードからドキュメントを作成し、Mermaid記法を使って設計意図を図として見える化する方法を試してみました。
実際に操作してみると、単純に文章を書いてもらうだけではありません。
「コードを理解する」→「設計を整理する」→「図にする」→「表示できない問題をAIに相談する」という流れまで、GitHub Copilotを開発パートナーのように使えることが分かりました。
この記事では、その一連の流れを実体験ベースで紹介していきます。
GitHub Copilotでドキュメントを作成するメリット
まず、今回の作業で感じた大きなメリットは、ドキュメントを書くための「整理作業」をGitHub Copilotに手伝ってもらえることです。
もちろん、最終的に内容を確認するのは人間です。
ただ、ゼロから文章や設計図を作ろうとすると、それだけでかなりの時間がかかります。
GitHub Copilotにコードの内容を確認してもらい、ドキュメントのたたき台を作ってもらえば、そこから人間がレビューするという進め方ができます。
特に便利だと感じたのが、次のような作業です。
- ソースコードの処理内容を説明する
- プログラムの構造を整理する
- 処理の流れを可視化する
- 概要図やシーケンス図を作成する
- Markdown形式のドキュメントを作る
- エラーや表示問題について質問する
GitHub Copilotは、コードを書くだけのツールではありません。
「コードを理解して、説明する」ためにも使えるというのが今回のポイントです。
GitHub CopilotのAskモードでコードを確認する
それでは、実際にドキュメントを作成していきます。
今回の対象は、これまで作成してきた天気予報アプリのMain.pyです。
まずはVS CodeでGitHub Copilot Chatを開きます。
ここでは、コードの内容を確認したり、質問したりするためにAskモードを利用します。
現在のGitHub Copilotでは、Askモードはコードや技術的な質問への回答、コードベースの理解などに向いています。一方、複数ステップの作業をCopilotに進めてもらう場合はAgentモードが適しています。([GitHub Docs](https://docs.github.com/en/copilot/how-tos/chat-with-copilot/chat-in-ide?quot=&tool=jetbrains&utm_source=chatgpt.com))
今回のように「まずコードを理解して、ドキュメント化する」という場面では、最初にAskモードで内容を確認していくと進めやすいでしょう。
VS Codeで対象ファイルを開いておく
ここで、ちょっとしたポイントがあります。
GitHub Copilotに質問するときは、どのファイルを対象にしているのかを意識してください。
今回、ドキュメント作成の対象はMain.pyです。
ところが、ReadMeファイルを開いた状態でプロンプトを送ってしまうと、CopilotがReadMeを中心に回答してしまう可能性があります。
そこで、ReadMeに記載されているプロンプトをコピーしたら、ReadMeを閉じてMain.pyをエディターで開きます。
このひと手間が、AIに正しいコンテキストを渡すうえで重要です。
GitHub Copilotは、開いているファイルや選択したコードなどをコンテキストとして利用できます。必要に応じてファイルを明示的に参照させることもできます。([GitHub Docs](https://docs.github.com/en/enterprise-cloud%40latest/copilot/how-tos/chat-with-copilot/chat-in-ide?tool=visualstudio&utm_source=chatgpt.com))
GitHub Copilotのスラッシュコマンドでコードを説明してもらう
次に、GitHub Copilotへドキュメント生成を依頼します。
今回利用したのが、スラッシュコマンドです。
GitHub Copilot Chatでは、プロンプト欄に「/」を入力すると利用可能なスラッシュコマンドを確認できます。
例えば、現在の環境では/explainを使って、選択したコードやアクティブなコードの説明を求めることができます。([GitHub Docs](https://docs.github.com/en/copilot/reference/chat-cheat-sheet?tool=xcode&utm_source=chatgpt.com))
今回の作業では、ワークスペースの内容を確認しながら、Main.pyの処理内容や設計意図を説明してもらう形で進めます。
ReadMeに用意しておいたプロンプトをコピーして、GitHub Copilot Chatへ貼り付けます。
そして、Main.pyを対象としてドキュメント生成を指示します。
送信すると、GitHub Copilotがコードを確認しながら回答を生成していきます。
画面上に処理の進行が表示され、しばらくするとドキュメントの提案が返ってきます。
ここは、ちょっとワクワクする瞬間です。
「自分が書いたコードを、AIはどう理解したんだろう？」
そんな気持ちで生成された内容を確認していきます。
AIが生成したドキュメントをそのまま使わない
ここで大切なのが、GitHub Copilotが生成したドキュメントを、そのまま完成版として扱わないことです。
AIが作った文章や図は、あくまでも提案です。
そのため、次のポイントをチェックします。
- 自分が想定していた処理になっているか
- ファイル構成の理解に間違いがないか
- 処理の順番が正しいか
- 実際のプログラムと説明が一致しているか
- 図の内容に矛盾がないか
- 専門用語の使い方が適切か
もし「ここはどういう意味だろう？」と感じる部分があれば、その場でGitHub Copilotに質問してみましょう。
一度で完璧な答えを出してもらおうとするより、生成→確認→質問→修正という流れで進めるほうが、実際の開発では使いやすいと思います。
Mermaid記法でシステム構成や処理の流れを可視化する
今回、GitHub Copilotから生成してもらったドキュメントでは、Mermaid記法を利用しました。
Mermaidは、テキストベースでフローチャートやシーケンス図などを記述できる記法です。
例えば、プログラムの処理を文章だけで説明するよりも、図にしたほうが一目で理解できることがあります。
今回の天気予報アプリでも、
- アプリ全体の処理の流れ
- 各処理の関係
- ユーザーからの入力
- APIとの通信
- 天気情報の取得
- 結果の表示
などを図にすると、プログラムの構造がかなり分かりやすくなります。
概要図とシーケンス図を作成する
今回のドキュメントには、主に概要図とシーケンス図を用意しました。
概要図では、システム全体がどのような構成になっているのかを確認します。
一方、シーケンス図では「誰が」「どのタイミングで」「何をするのか」という処理の流れを確認できます。
文章だけでは少し分かりづらかった処理でも、図にすると関係性が見えてきます。
これがドキュメントにMermaidを使う大きなメリットです。
MarkdownファイルにGitHub Copilotの提案を挿入する
次に、GitHub Copilotが生成したMermaidコードをMarkdownファイルへ移していきます。
今回使用するファイルはドキュメント.mdです。
VS Codeのエクスプローラーからドキュメント.mdを開きます。
ファイルの中には、あらかじめ概要図とシーケンス図を記述するための枠を用意しています。
ここにGitHub Copilotが生成したコードを挿入していきます。
まず概要図を入れる位置にカーソルを合わせます。
そしてGitHub Copilotの回答に表示されているコードの挿入ボタンを選択します。
すると、カーソルを合わせた位置にMermaidコードが挿入されます。
同じように、シーケンス図についてもコードを挿入します。
ここまで来ると、ドキュメントの形がかなり見えてきました。
VS CodeでMarkdownをプレビューしてみる
では、作成したドキュメントを実際に確認してみましょう。
VS Codeでドキュメント.mdを右クリックします。
表示されたメニューから「プレビューを開く」を選択します。
すると、MarkdownをHTMLのように整形したプレビュー画面が表示されます。
「おお、ちゃんとドキュメントになっている！」
……となればよかったのですが、ここで問題が発生しました。
Mermaidのコードが、図ではなくコードそのものとして表示されているのです。
「あれ？記述方法が間違っているのかな？」
最初はそう思いました。
しかし、Mermaidの記述自体を確認すると、どうやら書き方は間違っていません。
同じコードをMermaidに対応した別の環境で確認すると、ちゃんと図として表示されます。
つまり、問題はMarkdownの内容ではなく、VS Code側のプレビュー環境にありそうです。
MermaidがVS CodeのMarkdownプレビューで表示されないときの対処法
こういう「なんかおかしいな」という状況こそ、GitHub Copilotに聞いてみます。
今回の質問内容はシンプルです。
「VS CodeのMarkdownプレビューでMermaid記法が図として表示されないのはなぜ？」
このように、現在起きている現象を具体的に伝えます。
するとGitHub Copilotが原因と考えられるポイントや、解決方法をいくつか提示してくれます。
ここで大切なのは、単純に「動きません」と伝えるのではなく、
- 使用しているエディター
- 対象ファイル
- 発生している症状
- 期待している結果
- 現在の設定や拡張機能
などをできるだけ具体的に伝えることです。
AIに渡す情報が増えるほど、原因を絞り込みやすくなります。
VS CodeのMermaid対応は現在どうなっている？
ここは現在の読者向けに、少し補足しておきます。
以前は、VS CodeのMarkdownプレビューでMermaidを表示するために「Markdown Preview Mermaid Support」という拡張機能を利用する方法がよく使われていました。
しかし現在は状況が変わっています。
VS Code 1.121では、このMermaid対応機能がVS Code側へ統合され、Markdown PreviewでMermaid図を表示できる機能が組み込まれています。そのため、古い記事にある「必ず拡張機能をインストールする」という手順とは異なる場合があります。([Visual Studio Code](https://code.visualstudio.com/updates/v1_121?utm_source=chatgpt.com))
つまり、現在のVS Codeを利用している場合は、まずVS Codeを最新版へ更新してMermaidのMarkdownプレビューを確認するのがおすすめです。
一方、古いVS Codeや互換エディターを利用している場合は、拡張機能が必要になることがあります。
このあたりはバージョンによって環境が変わるため、エラーメッセージや現在のVS Codeのバージョンを確認することが重要です。
Mermaid対応で確認したいポイント
- VS Codeが古いバージョンになっていないか
- Markdownファイルとして開いているか
mermaidのコードフェンスが正しく記述されているか- Mermaid構文にエラーがないか
- 拡張機能が必要な環境では適切な拡張機能がインストールされているか
- 表示に時間がかかっていないか
特にMermaidのコードは、少し記述を間違えただけでも図としてレンダリングされないことがあります。
GitHub Copilotにエラー解決を相談してみる
今回のように問題が発生した場合、すぐに検索エンジンで答えを探す方法もあります。
もちろん、それも有効です。
ただ、今回のような開発中の問題では、まずGitHub Copilotに相談するのもかなり便利です。
なぜなら、Copilotには現在開いているコードやプロジェクトのコンテキストを渡せるからです。
例えば、次のような質問ができます。
VS CodeのMarkdownプレビューで
Mermaid記法が図として表示されません。
現在のMarkdownファイルとMermaidコードを確認して、
考えられる原因と解決方法を教えてください。
これだけでも、原因を探すためのスタート地点になります。
もし回答の中に「拡張機能をインストールしてください」といった提案があれば、その内容を確認して進めます。
ただし、AIの回答をそのまま信じるのではなく、拡張機能の提供元や現在のVS Codeのバージョン、公式ドキュメントなども確認することをおすすめします。
GitHub Copilotの回答は毎回同じとは限らない
ここは、今回の学習で改めて感じたポイントです。
GitHub Copilotに同じ質問をしても、毎回まったく同じ回答が返ってくるとは限りません。
そのため、1回目の回答でうまく解決できなかったとしても、そこで諦める必要はありません。
質問内容を少し具体的にしたり、エラーメッセージを追加したり、現在の環境を伝えたりすることで、回答の方向性を変えられます。
つまり、AIをうまく使うにはプロンプトが重要ということです。
GitHub Copilotで重要なのはプロンプトの作り方
例えば、
Mermaidが表示されません。だけでは、Copilotからすると情報が少なすぎます。
それよりも、
VS CodeのMarkdownプレビューでMermaid記法を使っています。
Mermaidのコード自体は別の環境では正常に図として表示されますが、
VS Codeではコードがそのまま表示されます。
使用しているVS Codeのバージョン、
Markdownファイルの内容、
現在の設定を前提に、
考えられる原因と具体的な解決方法を教えてください。
このように、「何をしているのか」「何が起きたのか」「本来どうなってほしいのか」を伝えるだけでも、質問の質はかなり変わります。
AIへの質問で意識したい3つのポイント
- 現状：何をしているのか
- 問題：何が起きているのか
- 期待：どうなってほしいのか
この3つを意識すると、GitHub Copilotへの質問がかなり作りやすくなります。
うまくいかなければ再試行するのもAI活用のコツ
AIを使った開発では、「最初から正解を出してもらう」という考え方よりも、対話しながら答えを絞り込んでいくという考え方のほうが向いています。
例えば、
- まず質問する
- 回答を確認する
- 実際に試す
- エラーが出たらエラー内容を伝える
- 再度質問する
- 解決したらドキュメントへ反映する
このサイクルを回していきます。
今回もまさにこの流れでした。
「Mermaidが表示されない」
↓
「GitHub Copilotに質問する」
↓
「解決方法を確認する」
↓
「VS Codeの環境を確認する」
↓
「Markdownプレビューを再確認する」
という流れです。
Mermaidの概要図とシーケンス図が表示された瞬間
設定や環境を確認したところで、もう一度ドキュメントをプレビューします。
すると……。
今度はちゃんと図が表示されました。
コードがずらっと並んでいた画面から、きれいな概要図とシーケンス図へ変わっています。
この瞬間は、やっぱり気持ちいいですね。
自分が書いたPythonコードと、GitHub Copilotが理解した内容が、今度は図として目の前に現れました。
文章だけで読むよりも、アプリケーションの構造がずっと分かりやすく感じられます。
場合によっては図の生成や表示に少し時間がかかることもあります。
そのため、表示されないからといってすぐにコードを修正するのではなく、少し待ってからプレビューを確認することも大切です。
Mermaidでエラーが出たときはエラーメッセージを活用する
もちろん、すべての環境で一発成功するとは限りません。
Mermaidの構文によってはエラーが表示されることもあります。
そんなときにおすすめなのが、エラーメッセージをそのままGitHub Copilotに渡す方法です。
例えば、
このMermaidコードをMarkdownプレビューすると
エラーが表示されます。
以下がエラーメッセージです。
【ここにエラー内容】
原因を説明して、
修正後のMermaidコードを提示してください。
このように質問すれば、原因調査から修正案の作成までAIに手伝ってもらえます。
ただし、ここでも重要なのは修正されたコードを人間が確認することです。
AIが生成した図が「それっぽく見える」だけでは不十分です。
実際のプログラムの処理と一致しているかを確認しましょう。
GitHub Copilotでドキュメント作成を自動化すると開発が変わる
今回の作業を通して感じたのは、GitHub Copilotは単純なコード生成ツールではないということです。
コードを書いているときだけではなく、
- コードを理解する
- 設計を整理する
- ドキュメントを作る
- 図を作成する
- エラーを調査する
- 改善案を考える
といった、開発工程のさまざまな場面で利用できます。
特にドキュメント作成は、後回しにされがちな作業です。
「あとでREADMEを書こう」
「あとで設計書を整理しよう」
と思っているうちに、気がついたらコードだけが残ってしまう。
そんな経験をしたことがある人も多いのではないでしょうか。
GitHub Copilotを使えば、コードを書いた直後に、そのコードの説明や構造を整理することができます。
結果として、「コードを書く」と「ドキュメントを残す」の距離を縮められるのではないかと思います。
GitHub Copilotでドキュメントを作るときのポイントまとめ
今回の内容をまとめてみます。
- 対象ファイルを明確にする
- Askモードでコードの内容を確認する
- /explainなどのスラッシュコマンドを活用する
- GitHub Copilotにドキュメントのたたき台を作ってもらう
- 生成された内容は必ず人間がレビューする
- Mermaidで処理の流れを図にする
- Markdownファイルにドキュメントをまとめる
- VS CodeのMarkdownプレビューで表示を確認する
- Mermaidが表示されない場合は環境やバージョンを確認する
- エラーメッセージをGitHub Copilotに渡して原因を調査する
- AIへの質問では「現状・問題・期待する結果」を具体的に伝える
まとめ｜GitHub Copilotを「コードを書くAI」から「開発パートナー」へ
今回は、天気予報アプリを題材に、GitHub Copilotを使ってドキュメントを作成してみました。
最初は「ドキュメントを書くのは面倒だな」というところから始まった作業でした。
ところが実際にGitHub Copilotを使ってみると、コードの内容を整理してもらい、概要図やシーケンス図まで作成できました。
さらに、Mermaidの表示で問題が発生したときには、その問題についてもGitHub Copilotに相談することができました。
ここで大切なのは、GitHub Copilotに全部任せることではありません。
AIにたたき台を作ってもらい、人間が内容を確認する。
問題があればAIに質問する。
回答を試して、また確認する。
この繰り返しによって、開発作業を効率化していくことがポイントだと思います。
そして今回、特に印象に残ったのがプロンプトの重要性です。
「動かない」「分からない」とだけ伝えるのではなく、現在の環境やエラー、期待している結果を具体的に伝える。
これだけでもAIとのコミュニケーションは大きく変わります。
GitHub Copilotを使い始めたばかりの頃は、「コードを書いてもらうためのAI」というイメージが強いかもしれません。
でも、実際に使ってみると、コードを書く前の設計から、コードを書いた後のドキュメント作成、さらにエラー解決までサポートしてくれます。
GitHub Copilotを「コード生成ツール」だけで終わらせず、「開発パートナー」として使ってみる。
今回のドキュメント作成を通して、そんなAI活用の可能性を感じることができました。
これからも、実際に手を動かしながらGitHub Copilotを使った開発効率化について試していきたいと思います。
0 件のコメント:
コメントを投稿