AIで既存コードを解説・ドキュメント化する方法｜引き継ぎ資料・README・コメントをAIに書かせる実践ガイド

引き継いだシステムのコードを開いた瞬間、「コメントが一切ない」「前任者はもう退職している」という状況に直面したことはないだろうか。ドキュメント整備の重要性はわかっていても、日常業務に追われて後回しになりがちだ。

この記事では、ChatGPT・Claude・GitHub Copilot Chatを活用して、既存コードの解説・README・インラインコメント・引き継ぎ資料を効率よく自動生成する実践的な方法を解説する。プログラミングが得意でない担当者でも、コピペで使えるプロンプト例とともにすぐ試せる内容だ。

AIでコードを解説・ドキュメント化するとは？

AIによるコードの解説・ドキュメント化とは、端的に言えば「コードをAIに貼り付けて、日本語で説明させる」ことだ。具体的には次のようなアウトプットをAIに生成させられる。

・コード解説文：関数・クラス・ファイル単位で「何をしているのか」を自然言語で説明
・README：プロジェクト全体の概要・セットアップ手順・使い方をMarkdown形式で自動生成
・インラインコメント：コード内に直接埋め込む説明文（#コメントや///形式）の追加
・引き継ぎ資料：システム構成・処理フロー・注意点をまとめたドキュメントの作成

従来はベテランエンジニアが数日かけて行っていた作業が、適切なプロンプトとAIの組み合わせで数時間に短縮できるようになった。特に「10年以上前のレガシーコード」への適用で効果が大きく、当時の開発者が不在で全体像を把握できないシステムでも、AIはコードを読んでひとまずの解説を生成できる。「何もない状態」から「たたき台がある状態」に変えるだけで、引き継ぎや改修の作業効率は大きく変わる。

具体的な使い方（ステップバイステップ）

1. AIにコードを読み込ませる準備

まず、ドキュメント化したいコードをAIに渡す方法を選ぶ。主な方法は次の3つだ。

・テキストとして貼り付ける（ChatGPT・Claude・Gemini）：コードをコピーしてチャット欄に貼り付ける。1回のやり取りで扱えるコード量は数百行が目安（ツールのコンテキスト上限による）
・ファイルごとアップロード（ChatGPT・Claude）：.py・.js・.javaなどのファイルを直接添付する。コードをコピーする手間が省ける
・GitHub Copilot Chat（VS Code拡張）：エディタ上でコードを選択し、Copilot Chatに直接質問できる。ファイルのコピーが不要で最も手軽

コードが長い場合は関数・クラス単位に分割して順番に渡すと精度が上がる。一度に大量のコードを投げ込むより、「この関数を解説して」と絞り込んだほうが的確な回答が得られる。

2. コード解説プロンプトの書き方

コードをAIに解説させる基本プロンプトを紹介する。そのままコピペして使える形にした。

基本の解説プロンプト（関数・処理単位）

以下のコードを解説してください。

【解説に含めること】
- このコードが「何をしているのか」を1～2文で要約
- 各関数・メソッドの役割を箇条書きで説明
- 引数と戻り値の意味
- 注意が必要な処理や副作用がある箇所の指摘

【対象コード】
（ここにコードを貼り付ける）

出力例（上記プロンプトへの回答イメージ）

【要約】
このコードは、ユーザーIDを受け取ってデータベースから注文履歴を取得し、
未払い注文が存在する場合にメール通知を送信する処理です。

【各関数の役割】
- get_orders(user_id): DBから指定ユーザーの注文一覧を取得
- filter_unpaid(orders): 支払い済みでない注文だけを抽出
- send_notification(user_email, orders): 対象者へメール通知を送信

【注意点】
- DBコネクションはグローバル変数を使用しており、並列実行時に競合の可能性あり
- メール送信部分にエラーハンドリングがないため、本番環境では要改修

3. READMEを自動生成する

プロジェクト全体のREADMEを生成したい場合は、ディレクトリ構造と主要機能の概要をセットで渡すと精度が高まる。

以下の情報をもとに、GitHubに掲載するREADME.mdを作成してください。

【プロジェクト概要】
（例：社内の発注管理システム。Pythonで動作し、PostgreSQLを使用している）

【ディレクトリ構造】
（例：
/src
  main.py
  order_handler.py
  db_connector.py
/tests
  test_order.py
README.md
requirements.txt
）

【主要な機能】
（例：発注の登録、未払い注文の抽出、担当者へのメール通知）

【セットアップ手順】
（例：1. リポジトリをクローン 2. requirements.txtをインストール 3. python main.pyを実行）

【README形式の要件】
- Markdown形式
- セクション：概要・前提条件・インストール・使い方・ライセンス
- 日本語で記述

4. インラインコメントを追加する

既存コードにコメントを追記してもらう際は、「コードを変更せずにコメントだけ追加」という制約を明示するのがポイントだ。ロジックを変えてしまうケアレスミスを防げる。

以下のコードに日本語のインラインコメントを追加してください。

【ルール】
- コードのロジックは一切変更しないこと
- 各処理の「なぜそうしているのか」がわかるコメントを優先する
- 1行につき1コメントまで（コメントの多用は避ける）
- Python形式（# コメント）で記述

【コード】
（ここにコードを貼り付ける）

5. 引き継ぎ資料・仕様書を自動作成する

コードを渡すだけでなく、システム全体の引き継ぎ資料を作らせることもできる。次のプロンプトは、業務システムの引き継ぎに特化した形式だ。

以下のコードとシステム情報をもとに、後任者向けの引き継ぎ資料を作成してください。

【システム情報】
- システム名：（例：受注管理バッチ処理）
- 実行環境：（例：Python 3.11, Ubuntu 22.04, cronで毎日8時に実行）
- 依存サービス：（例：PostgreSQL、SendGridメールAPI）

【コード】
（ここにコードを貼り付ける）

【資料に含める項目】
1. システム概要（1段落）
2. 処理の全体フロー（箇条書き）
3. 設定ファイル・環境変数の一覧と意味
4. よくあるエラーと対処法
5. 担当者が押さえておくべき注意点

実務での活用例（Before/After）

うまくいかない時の対処法

解説が抽象的すぎる場合

コードが長すぎると、AIは全体をざっくり説明しようとして抽象的になる。100行以下を目安に分割し、「この関数だけを解説して」と絞り込む。

ドメイン知識が必要な処理で説明が浅い場合

業界特有の業務ロジックが絡む箇所は、AIだけでは正確に解説できないことがある。「この処理は会計の月次締め処理です。その前提で解説してください」と背景情報を添えると精度が上がる。

古い言語・マイナー言語でAIが誤認する場合

VBA・COBOL・古いPerlなど、学習データが少ない言語では解析精度が落ちる。「これはVBA（Excel Visual Basic for Applications）です」と言語名を明記し、「古い文法が含まれている可能性がありますが、そのまま解析してください」と指示する。

機密情報が含まれるコードを渡せない場合

本番のパスワード・APIキー・個人情報が埋め込まれているコードは、クラウドAIにそのまま貼り付けるのはリスクがある。機密部分を「XXXXX」や「DUMMY_VALUE」に置換してから渡すのが基本だ。社内ルールによってはローカルで動くAIツール（ローカルLLM）の活用も検討する。

AIで解説したコードをさらに整理・改善したい場合は、AIでコードをリファクタリングする方法も参考にしてほしい。GitHub Copilot Chatを使ったエディタ統合の活用方法はGitHub Copilot Chatの使い方で詳しく解説している。APIドキュメントの整備を同時に進めるチームにはAIでAPIドキュメントを自動生成する方法もあわせて参照してほしい。

本記事のまとめ

AIによるコードの解説・ドキュメント化は、エンジニアだけでなくシステム担当者・プロジェクトマネージャー・引き継ぎを受けた非エンジニアにとっても強力な武器になる。コードをAIに貼り付けて質問するだけで、これまで数時間かかっていた理解作業が大幅に短縮できる。

まずは手元の「よくわからないコード」を1つ選び、この記事のプロンプトをそのままコピーして試してみてほしい。「AIに聞いたら意外とわかった」という体験が、ドキュメント化を習慣化する第一歩になる。

業務DX全体の推進戦略については、姉妹サイトDXマスターズ.TOKYOで詳しく解説している。