コードは書けるけど、ドキュメント書くのは面倒…。そんな悩み、ありませんか？
実は私も同じでした。関数のコメント、README、API仕様書。どれも重要なのは分かっているけど、つい後回しにしてしまう。結果、過去の自分が書いたコードの意図が分からず、メンテナンスに時間がかかる日々…。
そこでGitHub Copilotを使ってドキュメント生成を自動化したところ、ドキュメント作成時間が従来の1/3に短縮、しかも品質が向上しました。
この記事では、GitHub Copilotを使ったドキュメント自動生成の実践テクニックと、プロンプト設計のコツを実体験ベースで解説します。
背景・課題：ドキュメント作成が常に後回しになる問題
エンジニアなら誰しも経験があると思いますが、コードを書くのは楽しいけど、ドキュメントを書くのは苦痛ですよね。
私が実際に直面していた問題：
- 関数のコメントが不十分：引数の型や戻り値の説明が曖昧で、後から見返した時に「これ何だっけ？」となる
- READMEが古い：新機能を追加しても更新を忘れ、新メンバーが混乱する
- API仕様書が存在しない：口頭やSlackで説明するだけで、正式なドキュメントがない
結果として、レビュー時に質問が増え、オンボーディングに時間がかかり、バグの温床になるという悪循環に陥っていました。
「ドキュメントは大事」と分かっていても、締め切りに追われて後回しにしてしまう。この課題を解決するために、GitHub Copilotの活用を本格的に検討しました。
使用したツール・環境
今回使用したのは以下の環境です：
- GitHub Copilot（Individual プラン：月額$10）
- Visual Studio Code（GitHub Copilot拡張機能インストール済み）
- GitHub Copilot Chat（VS Code内のチャットインターフェース）
- 対象言語：TypeScript、Python（他の言語でも同様に適用可能）
なぜGitHub Copilotを選んだか？
- VS Codeとシームレスに統合されており、エディタから離れずに使える
- コード補完だけでなく、Chatでドキュメント生成を依頼できる
- 既存のコードベースを理解して、一貫性のあるドキュメントを生成できる
- 2025年現在、エージェント機能も追加され、より自律的な支援が可能に
実際に使ったプロンプト
GitHub Copilot Chatで、以下のプロンプトを使ってドキュメントを生成しました。
1. 関数のコメント（JSDoc/docstring）生成
使用したプロンプト
以下の関数に対して、JSDoc形式のコメントを追加してください。
要件：
- 関数の目的を簡潔に説明
- 各引数の型、説明、デフォルト値を明記
- 戻り値の型と説明を明記
- 例外が発生する可能性がある場合は@throwsで記載
- 使用例を@exampleで追加
対象コード：
[ここに関数のコードを貼り付け]
2. README.md生成
使用したプロンプト
このプロジェクトのREADME.mdを生成してください。
含めるべき項目：
- プロジェクト概要（何をするプロジェクトか）
- 主要機能のリスト
- インストール手順（依存関係のインストール方法）
- 基本的な使い方（コード例を含む）
- ディレクトリ構成
- 開発環境のセットアップ方法
- ライセンス情報
対象プロジェクト：
プロジェクト名：[プロジェクト名]
主要な技術スタック：[使用している技術]
3. API仕様書生成
使用したプロンプト
以下のAPIエンドポイントに対して、Markdown形式の仕様書を作成してください。
含める情報：
- エンドポイント名とURL
- HTTPメソッド
- 説明（このAPIが何をするか）
- リクエストパラメータ（クエリ、パス、ボディそれぞれ）
- 名前、型、必須/任意、説明
- レスポンス例（成功時・エラー時）
- ステータスコード一覧
- 使用例（curlコマンド）
対象エンドポイント：
[ここにコードまたはルーティング定義を貼り付け]
プロンプト設計のポイント
GitHub Copilotから高品質なドキュメントを引き出すために、以下の点を工夫しました：
1. 出力フォーマットを明確に指定する
「JSDoc形式」「Markdown形式」など、具体的なフォーマットを指定することで、一貫性のあるドキュメントが生成されます。チーム全体で同じ形式を使えば、可読性が向上します。
2. 必要な項目をリスト化する
「引数の型、説明、デフォルト値」のように、含めるべき項目を箇条書きで明示すると、漏れのないドキュメントが生成されます。曖昧な指示だと、重要な情報が抜け落ちることがあります。
3. コンテキストを与える
対象のコードや技術スタックをプロンプトに含めることで、プロジェクト固有の文脈を理解したドキュメントが生成されます。例えば、TypeScriptを使っているなら型定義も含めて生成されます。
4. 使用例を含めるよう指示する
「@exampleで使用例を追加」「curlコマンドで使用例」のように、実際の使い方を示す例を含めると、読み手の理解が格段に深まります。特に新メンバーのオンボーディングで効果的です。
5. 段階的に生成する
一度にすべてのドキュメントを生成しようとせず、関数ごと、モジュールごとに段階的に生成することで、精度が上がります。大量のコードを一度に投げると、詳細が省略されることがあります。
実行結果・効果
GitHub Copilotを使ったドキュメント生成を導入した結果、以下の成果が得られました：
Before（手動でドキュメント作成）
- 関数10個のコメント作成：約60分
- README.md作成：約90分
- APIエンドポイント5個の仕様書作成：約120分
- 合計：約4.5時間
After（GitHub Copilot使用）
- 関数10個のコメント作成：約15分（生成+レビュー）
- README.md作成：約30分（生成+カスタマイズ）
- APIエンドポイント5個の仕様書作成：約40分（生成+確認）
- 合計：約1.5時間（従来の1/3）
品質面での向上
- 一貫性のある記述：同じフォーマットで統一されたドキュメントが生成される
- 漏れの防止：必須項目（引数、戻り値、例外など）が網羅される
- 可読性の向上：人間が書くより整理された構造になることが多い
- 最新性の維持：コード変更時に再生成すれば、常に最新の状態を保てる
特に驚いたのは、Copilotが生成したドキュメントの方が、自分で書いたものより詳細だったこと。例えば、エッジケースの説明や、引数の制約条件など、手動では忘れがちな情報まで含まれていました。
応用パターン・カスタマイズ例
基本的なドキュメント生成以外にも、以下のような応用が可能です：
1. 既存コードの説明生成
レガシーコードや他人が書いたコードに対して「このコードが何をしているか、日本語で説明してください」とCopilot Chatに依頼すると、コードリーディングの時間を大幅に短縮できます。
2. コミットメッセージの自動生成
変更内容を選択して「この変更に対する適切なコミットメッセージを生成してください」と依頼すると、Conventional Commits形式のメッセージを提案してくれます。
3. プルリクエストの説明文生成
差分を見せながら「このPRの説明文を作成してください。変更内容、背景、テスト方法を含めて」と依頼すると、レビュアーに優しい説明文が生成されます。
4. テストケースのドキュメント化
テストコードに対して「このテストケースが何を検証しているか説明してください」と依頼すると、テストの意図を明確化できます。
注意点・限界
GitHub Copilotによるドキュメント生成は非常に便利ですが、以下の点に注意が必要です：
1. 生成されたドキュメントは必ずレビューする
Copilotは優秀ですが、完璧ではありません。プロジェクト固有の用語や業務ロジックを誤解することがあります。特にドメイン知識が必要な部分は、人間の目で確認が必須です。
2. セキュリティ情報は含めない
API キーやシークレット、内部システムの詳細など、機密情報を含むコードをCopilotに渡さないよう注意してください。企業利用の場合は、GitHub Copilot Businessでデータ管理ポリシーを確認しましょう。
3. コンテキストの制約
Copilotが一度に理解できるコードの量には限界があります。巨大なファイルや複雑な依存関係がある場合、段階的にドキュメント化するか、重要な部分を抽出して依頼する必要があります。
4. 過度な依存は避ける
ドキュメント生成を完全にAIに任せると、自分で書く力が衰える可能性があります。基本的な構成やベストプラクティスは自分で理解した上で、効率化の手段として活用しましょう。
まとめ
- GitHub Copilotでドキュメント作成時間を1/3に短縮できる。関数コメント、README、API仕様書すべてに対応可能。
- プロンプト設計が重要。フォーマット指定、必要項目のリスト化、コンテキスト提供で品質が向上する。
- 生成されたドキュメントは必ずレビューする。機密情報の取り扱いにも注意が必要。
まず試してほしいこと：
今書いている関数1つに対して、GitHub Copilot Chatで「この関数にJSDoc形式のコメントを追加してください」と依頼してみてください。その生成スピードと品質に驚くはずです。
ドキュメント作成を後回しにする時代は終わりました。AIを活用して、コードと同じくらいドキュメントも大切にできる開発スタイルを手に入れましょう。
