読者が抱える課題
ソースコードの修正に合わせてREADME、設計書、テスト仕様書などのドキュメントを更新する作業は、開発者にとって大きな負荷となります。実装とドキュメントの剥離（ドキュメントの陳腐化）が発生しやすく、保守性の低下やレビューコストの増加につながります。
この記事で分かること
- プロンプトとLLM CLIツールの連携によるドキュメント自動生成の手順
- 実務でそのまま使えるREADME、設計書、テスト仕様書生成用プロンプトテンプレート
- 生成物の精度を保つための出力生成チェックリストと注意点
対象読者・前提条件
- GitHub Copilot、ChatGPT、ClaudeなどのLLMを開発業務で利用しているエンジニア
- ソースコードからドキュメントを効率的に生成・更新したい方
自動生成の全体フローと構成例
ソースコード（PythonやTypeScript等）を解析し、構造化されたMarkdownドキュメントを出力させる基本フローです。CLIツール（例: gh copilot や llm コマンドなど）を活用することで、ターミナル上で一括処理が可能です。
処理の流れ
- 入力データの抽出: 対象となるソースコードファイル（および型定義）を指定
- プロンプト適用: 役割、コンテキスト、出力フォーマットを指定したプロンプトを投入
- 生成物の確認と修正: チェックリストに基づき、人間が差分を検証・微修正
実務用プロンプトテンプレートと実行例
1. README生成用プロンプトテンプレート
以下のテンプレートをテキストファイル（prompt_readme.md）として保存し、ソースコードと一緒にLLMへ入力します。
# 役割
あなたはテクニカルライターです。提供されたソースコードを解析し、プロジェクトのREADME.mdを作成してください。
# 条件
- 対象コードの主要機能を箇条書きで整理すること
- 依存関係と推奨動作環境を記載すること
- クイックスタート用のコマンド例（インストール、実行方法）を含めること
- 存在しない機能や環境設定を追加しないこと（コード内に存在する情報のみを使用する）
# 出力フォーマット
- プロジェクト概要
- 主な機能
- 動作環境・依存関係
- 導入手順
- 使用例
コマンド実行例（CLIを利用する場合）
# LLM CLI等を利用してコードからREADMEを生成する例（環境に合わせて調整してください）
cat prompt_readme.md src/index.ts > combined_input.txt
cat combined_input.txt | llm prompt > README.md
2. 基本設計書（モジュール設計）生成プロンプトテンプレート
ソースコードのクラス構造や関数のシグネチャから、システム仕様を整理するためのプロンプトです。
# 役割
あなたはシステムアーキテクトです。入力されたコードに基づき、モジュール単位の基本設計ドキュメントを作成してください。
# 入力ソースコード
{{ソースコードをここに貼り付け、またはファイル入力}}
# 抽出項目
1. モジュール概要（目的と主要クラス・関数の役割）
2. 入出力インターフェース（関数名、引数の型、返り値の型）
3. 依存関係（外部ライブラリおよび内部モジュール）
4. 例外処理・エラーハンドリングの仕様
# 制約事項
- 推測に基づく仕様追加は行わず、実装から読み取れる事実のみを記載すること
- 型定義はTypeScript/Pythonなどの標準表記に準拠すること
3. テスト仕様書生成プロンプトテンプレート
関数の正常系・異常系・境界値条件を網羅したテスト仕様書（Markdownテーブル形式）を作成させます。
# 役割
あなたはQAエンジニアです。以下の関数・クラス仕様をもとに、単体テスト仕様書を作成してください。
# 条件
- 正常系、異常系、境界値の観点を含めること
- 各テストケースに「テストID」「観点」「入力値」「期待される出力/挙動」を明記すること
- 出力フォーマットはMarkdownの表形式とすること
# 出力例フォーマット
| テストID | テスト区分 | テスト観点 | 入力値 | 期待される出力 |備考 |
|---|---|---|---|---|---|
| TC-001 | 正常系 | 有効な引数での実行 | `id=1` | Status 200, データ返却 | |
| TC-002 | 異常系 | Null値の入力 | `id=null` | TypeError発生 | |
生成ドキュメントの精度比較と用途分け
| ドキュメント種別 | 主な入力データ | AI生成の得意な点 | 人間による補正が必要な点 |
|---|---|---|---|
| README | リポジトリ全体の構成、環境定義 | 導入手順や標準的な使い方記述 | プロジェクト固有の運用ルールや注意事項 |
| 設計書 | クラス、関数、型定義ファイル | 関数のシグネチャ解析、入出力一覧化 | ドメイン知識に基づく設計意図や背景の補足 |
| テスト仕様書 | ロジック実装、バリデーション処理 | 境界値やNULLチェックの網羅 | ビジネスロジック上発生し得ないケースの除外 |
実務導入時のチェックリスト（確認事項）
AIによって自動生成されたドキュメントをリポジトリへコミットする前に、以下の項目を確認します。
- ハルシネーションの有無: ソースコードに存在しない架空のAPI、関数、引数が含まれていないか
- 機密情報の漏洩チェック: 接続文字列、APIキー、内部IPアドレスなどが含まれていないか
- 実行可能性の確認: READMEに記載されたコマンド例を実行してエラーが出ないか
- フォーマットの適合性: プロジェクトの既存ドキュメント規約にフォーマットが沿っているか
- 最新コードとの不整合: 修正漏れのファイルが存在しないか
導入時の注意点と運用上の判断基準
-
コードの機密性確保
- 利用するAIサービスの利用規約を確認し、入力データがモデルの再学習に使用されない設定（オプトアウト設定やエンタープライズ契約）になっているか確認してください。
-
完全自動化の回避とレビューの必須化
- 生成物をそのまま信頼してコミットするのではなく、必ずPull Request（PR）のプロセスで人間が差分（Diff）を確認するレビューフローを組んでください。
-
仕様変更時の再生成手順
- コードを変更した際はプロンプトを再実行するか、CI/CDパイプライン上で差分検出時に警告を出すなどの運用基準を定めておくと、ドキュメントの陳腐化を防止できます。
まとめ
AIによるドキュメント自動生成を活用することで、仕様書作成にかかる時間を削減し、コードとドキュメントの乖離を防ぐことが可能です。適切なプロンプトテンプレートを定義し、人間の確認プロセス（チェックリスト）を組み込むことで、実務で十分に活用できるクオリティを維持できます。利用環境のセキュリティポリシーに留意した上で導入を検討してください。