生成AIにコードを解説させるプロンプト集｜処理の流れを図にする手順

生成AIにコードを解説させるときは、「全体の役割 → 入口から出口までの流れ → 関数ごと → 分からない行」の順に、範囲を狭めながら聞くと理解が早く進みます。 いきなり「このコードを説明して」と頼むと、1行ずつの言い直しが返ってきて、全体として何をしているのかがつかみにくくなります。

この記事では、段階ごとのプロンプトテンプレート（概要、処理の流れ、具体的な値で追う、呼び出し関係、データの変化、用語集）、処理の流れを Mermaid の図で出させるプロンプトと見本、そして AI の説明をそのまま信じずに確かめる手順をまとめました。コードを「直す」ためではなく「理解する」ための聞き方に絞っています。特定のツールに依存しない形で書いているので、チャットでもエディタの AI 機能でも使えます。

確認環境：Ubuntu 24.04、Python 3.11.15、Node.js 22.22.2、@mermaid-js/mermaid-cli 12.0.0（Mermaid 12.1.0）＋ Chromium（確認日 2026-10-05）。題材のコード、行番号の付け方、確かめ用のスクリプトの出力は、この環境で実行した結果です。Mermaid の見本はすべて mermaid-cli で SVG に描画できることを確かめています。プロンプトの考え方は、同日に開いた Anthropic と GitHub Docs の公式ガイドの記載に沿っています。この記事はテンプレート集で、AI の回答例は載せていません。

この記事の結論

• 聞く順番は全体の役割 → 流れ → 関数ごと → 分からない行。広い範囲から狭い範囲へ
• コードは行番号つきで渡し、説明には行番号と引用を付けさせる
• 流れは具体的な値を1組決めて追わせると、あいまいな説明が減る
• 図は目的で選ぶ。分岐はフローチャート、やり取りの順番はシーケンス図、構造はクラス図
• 説明は仮説として扱い、引用の照合・テスト・ログで確かめる

コードを解説させるプロンプトの早見表

準備：コードを行番号つきで渡す

この記事では、架空の図書貸出システムの次のコード（lending.py）を題材にします。

from dataclasses import dataclass, field
from datetime import date, timedelta

LOAN_DAYS = 14
MAX_ITEMS = 3


@dataclass
class Member:
    name: str
    borrowed: list[str] = field(default_factory=list)


@dataclass
class Item:
    code: str
    title: str
    due: date | None = None


class Library:
    def __init__(self) -> None:
        self.items: dict[str, Item] = {}
        self.log: list[str] = []

    def add(self, item: Item) -> None:
        self.items[item.code] = item

    def lend(self, member: Member, code: str, today: date) -> date:
        item = self._find(code)
        self._check(member, item)
        item.due = today + timedelta(days=LOAN_DAYS)
        member.borrowed.append(code)
        self.log.append(f"{today} lend {code} to {member.name}")
        return item.due

    def _find(self, code: str) -> Item:
        if code not in self.items:
            raise KeyError(f"unknown item: {code}")
        return self.items[code]

    def _check(self, member: Member, item: Item) -> None:
        if item.due is not None:
            raise ValueError(f"{item.code} is on loan until {item.due}")
        if len(member.borrowed) >= MAX_ITEMS:
            raise ValueError(f"{member.name} already has {MAX_ITEMS} items")


if __name__ == "__main__":
    lib = Library()
    lib.add(Item("B001", "設計の本"))
    sato = Member("sato")
    print(lib.lend(sato, "B001", date(2026, 10, 5)))
    print(sato.borrowed, lib.log)

2026-10-19
['B001'] ['2026-10-05 lend B001 to sato']

チャットに貼るときは、行番号を付けてから渡します。あとで「何行目の話か」を AI と人の両方が指させるようになり、説明の照合もしやすくなります。

nl -ba lending.py | sed -n '30,35p'

    30          item = self._find(code)
    31          self._check(member, item)
    32          item.due = today + timedelta(days=LOAN_DAYS)
    33          member.borrowed.append(code)
    34          self.log.append(f"{today} lend {code} to {member.name}")
    35          return item.due

nl -ba は空行にも番号を振ります（cat -n でも同じ番号になります）。全体を渡すときは nl -ba lending.py の出力をそのまま貼ります。

どの段階のプロンプトでも、次の3つを共通の前置きにします。

<code file="lending.py">
{nl -ba lending.py の出力をここに貼る}
</code>

<context>
このコードについて分かっていること：{例：図書貸出システムの貸出処理。Python 3.11}
自分の立場：{例：このコードを初めて読む。Python の文法は分かる}
知りたい理由：{例：貸出の上限を変える修正を頼まれた}
</context>

# 共通の約束
- 説明には、根拠になる行番号と、その行の引用を付ける
- コードから読み取れることと、推測は分けて書く。推測には「推測：」と付ける
- 貼られていないファイルの中身は想像で補わず、「このファイルには無い」と書く

Anthropic の公式ガイドには、長い資料は質問より前に置くこと、資料をタグで囲むこと、先に関連箇所を引用させてから作業させることが載っています。上の前置きはその並びに合わせています。

段階ごとのプロンプトテンプレート

以下は、共通の前置き（code と context と約束）の後ろに続けて書く部分です。

1. 概要：全体の役割をつかむ

このコードの全体像を、次の項目で教えてください。各項目1〜2行です。
1. 何のためのコードか（一言で）
2. 入力（どこから何を受け取るか）
3. 出力（何を返す、何を書き換える、何を表示するか）
4. 外部とのやり取り（ファイル、データベース、通信、時刻など。無ければ「無し」）
5. 入口になる関数やメソッド（外から呼ばれるもの）と、その行番号

概要の段階では、細かい処理は聞きません。「入口はどこか」が分かれば、次の段階で追う場所が決まります。

2. 処理の流れ：入口から出口まで番号つきで

{入口の関数名。例：Library.lend} が呼ばれてから値を返すまでの流れを、
番号つきのステップで説明してください。
- 1ステップは1つの処理。各ステップに行番号を付ける
- 条件で分かれる箇所は「〜の場合」と分けて、それぞれの行き先を書く
- 例外が出る箇所は、どの条件で、何の例外が出るかを書く
- 別の関数を呼ぶ箇所は、呼び先の中の説明に入らず「（→ _find）」と書くだけにする

最後の指定がポイントです。呼び先の中身まで一度に説明させると、流れの筋が見えにくくなります。呼び先は段階4と、関数ごとの質問で別に聞きます。

3. 具体的な値で追う

次の入力で {Library.lend} を実行したときの動きを、1行ずつ追ってください。

入力：
- lib.items には Item("B001", "設計の本", due=None) が1件
- member は Member("sato", borrowed=[])
- code は "B001"、today は date(2026, 10, 5)

出力の形：実行される順に、次の列の表にする
| 順番 | 行番号 | 実行される行 | この時点で変わる値 |

最後に、戻り値と、呼び出しのあとで変わっているオブジェクトの状態をまとめる。

抽象的な説明が分かりにくいときは、値を決めるのが近道です。この段階の説明は、自分で実行して照らし合わせられるという利点もあります（後述）。境界の値（上限ちょうど、空、存在しないコード）を入力にして、もう一度同じプロンプトを使うと、分岐の理解が深まります。

4. 呼び出し関係

このファイルの中の関数・メソッドの呼び出し関係を、次の表にしてください。
| 呼ぶ側 | 呼ばれる側 | 呼んでいる行番号 | 何のために呼ぶか（10字程度） |

- このファイルで定義されているものだけを対象にする
- 標準ライブラリや外部ライブラリの呼び出しは、表の下に名前だけ並べる
- どこからも呼ばれていない関数があれば、最後に挙げる

5. データの変化

このコードの中で、オブジェクトの状態を書き換えている箇所をすべて挙げてください。
| 行番号 | 書き換える対象（例：item.due） | 書き換え前 → 書き換え後 | どのメソッドの中か |

そのうえで、次の点を教えてください。
- 例外が出たとき、途中まで書き換わった状態が残る箇所はあるか（行番号つきで）
- 引数として受け取ったオブジェクトを書き換えている箇所はどれか

「どこで値が変わるか」は、読むだけでは見落としやすい点です。引数を書き換える関数は、呼び出す側から見えない変化を起こすので、修正の前に押さえておきます。

6. 用語集づくり

このコードに出てくる名前の用語集を作ってください。
| 名前 | 種類（定数・クラス・属性・メソッド・引数） | 意味 | 根拠の行番号 |

- 意味はコードから読み取れる範囲で書く。業務上の意味が読み取れないものは「不明（確認が必要）」と書く
- 同じものを指す別の名前（例：code と item.code）があれば、まとめて書く
- 単位がある値（日数、件数など）は単位を書く

用語集は、チームに質問するときの土台になります。「不明（確認が必要）」と出た名前が、人に聞くべきことの一覧です。

関数ごと・分からない行を聞く

範囲を狭めた質問は短くて構いません。

{_check} メソッド（42〜46行目）だけを説明してください。
- 引数と戻り値
- 例外を出す条件を、条件ごとに1行で
- このメソッドが状態を書き換えるかどうか

45行目の「>=」は、なぜ「>」ではないのですか。
MAX_ITEMS が 3 のとき、borrowed が 2件・3件・4件の場合にそれぞれどうなるかを表で示してください。

1行について聞くときも、具体的な値を並べさせると、説明が合っているかを自分で判断しやすくなります。

処理の流れを図にするプロンプトとMermaidの見本

Mermaid は、テキストで図を書く記法です。AI に Mermaid のコードで出させれば、対応しているエディタや Web 上のツールに貼って図として見られます。

どの図をいつ選ぶか

フローチャートを出させる

{Library.lend} の処理の流れを、Mermaid のフローチャート（flowchart TD）で書いてください。
- 分岐はひし形にし、矢印に条件を書く
- 例外で終わる経路も省かずに書く
- ノードの文字はすべて二重引用符で囲む
- 呼び先の関数の中の条件も、1つの図に展開する
- 出力は Mermaid のコードブロックだけにする

出力の形の見本です（題材のコードに合わせて手で書き、描画を確かめたもの）。

flowchart TD
    A["lend(member, code, today)"] --> B{"code は items にあるか"}
    B -- "無い" --> E1["KeyError"]
    B -- "ある" --> C{"item.due は None か"}
    C -- "None ではない（貸出中）" --> E2["ValueError: on loan"]
    C -- "None" --> D{"borrowed の件数 >= MAX_ITEMS か"}
    D -- "はい" --> E3["ValueError: already has 3 items"]
    D -- "いいえ" --> F["item.due = today + 14日"]
    F --> G["member.borrowed に code を追加"]
    G --> H["log に1行追加"]
    H --> I["item.due を返す"]

シーケンス図を出させる

{__main__ から Library.lend を呼んで結果が返るまで} のやり取りを、
Mermaid のシーケンス図（sequenceDiagram）で書いてください。
- 登場するものは、呼び出し元、Library、Item、Member
- 自分自身のメソッドを呼ぶ箇所は、自分への矢印で書く
- 例外で戻る場合と、最後まで進む場合を alt / else で分ける
- 矢印には、メソッド名と、分かる範囲の具体的な値を書く
- 出力は Mermaid のコードブロックだけにする

sequenceDiagram
    participant M as __main__
    participant L as Library
    participant I as Item
    participant Me as Member
    M->>L: lend(sato, "B001", 2026-10-05)
    L->>L: _find("B001")
    L->>L: _check(sato, item)
    alt 貸出中 または 上限に達している
        L-->>M: ValueError
    else 貸し出せる
        L->>I: due = 2026-10-19
        L->>Me: borrowed.append("B001")
        L->>L: log.append(...)
        L-->>M: 2026-10-19
    end

クラス図を出させる

このファイルのクラスを、Mermaid のクラス図（classDiagram）で書いてください。
- 各クラスに、属性（型つき）とメソッド（引数と戻り値の型つき）を書く
- 名前がアンダースコアで始まるメソッドは「-」、それ以外は「+」を付ける
- クラスどうしの関係は、コードから読み取れるものだけを線で結び、線に根拠（属性名や引数）を書く
- 出力は Mermaid のコードブロックだけにする

classDiagram
    class Library {
        +dict~str, Item~ items
        +list~str~ log
        +add(item) None
        +lend(member, code, today) date
        -_find(code) Item
        -_check(member, item) None
    }
    class Item {
        +str code
        +str title
        +date due
    }
    class Member {
        +str name
        +list~str~ borrowed
    }
    Library "1" o-- "0..*" Item : items
    Library ..> Member : lend の引数

図が描画されないときの直し方

AI が出した Mermaid のコードは、そのままでは描画できないことがあります。よくあるのは、ノードの文字にかっこが入っている場合です。次のコードを mermaid-cli に通すと、構文エラーになります。

flowchart TD
    A[lend(member, code, today)] --> B{code は items にあるか}
    B -- 無い --> E1[KeyError]

Error: Parse error on line 2:
...wchart TD    A[lend(member, code, today
----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', …（省略）…, got 'PS'

ノードの文字を二重引用符で囲むと描画できます（上の見本はすべて囲んであります）。プロンプトに「ノードの文字はすべて二重引用符で囲む」と入れておくのは、このためです。エラーが出たときは、エラー文をそのまま貼って「このエラーが出ないように直してください。図の内容は変えないでください」と頼みます。

AIの説明を確かめるチェック表

AI の説明は、もっともらしくても、行がずれていたり、条件が少し違っていたりすることがあります。説明は仮説として受け取り、次の方法で確かめます。

行番号と引用を出させて照合する

いまの説明の根拠を、タブ区切りで出してください。
1行目は「line（タブ）quote」。2行目から、行番号と、その行のコードをそのまま（前後の空白を除いて）書く。
説明に使ったすべての行を挙げる。

受け取った表を claims.tsv に保存し、次のスクリプトで元のコードと照合します。

"""AI の説明に付いた「行番号と引用」が、元のコードと一致するかを確かめる"""
import csv
import sys

src_path, claims_path = sys.argv[1], sys.argv[2]
lines = open(src_path, encoding="utf-8").read().splitlines()

ok = True
for row in csv.DictReader(open(claims_path, encoding="utf-8"), delimiter="\t"):
    no, quote = int(row["line"]), row["quote"].strip()
    actual = lines[no - 1].strip() if 1 <= no <= len(lines) else ""
    if quote == actual:
        print(f"一致   {no:>3}行目: {quote}")
        continue
    ok = False
    found = [i + 1 for i, l in enumerate(lines) if l.strip() == quote]
    if found:
        print(f"行ずれ {no:>3}行目 → 実際は {found} 行目: {quote}")
    else:
        print(f"不一致 {no:>3}行目: 引用「{quote}」はファイルに無い（実際: {actual}）")
sys.exit(0 if ok else 1)

動きを確かめるために、わざと1行ずらした引用と、記号を1つ変えた引用を混ぜた表（手で作ったもの）で試した結果です。

line    quote
31  self._check(member, item)
33  item.due = today + timedelta(days=LOAN_DAYS)
45  if len(member.borrowed) > MAX_ITEMS:

python3 check_claims.py lending.py claims.tsv

一致    31行目: self._check(member, item)
行ずれ  33行目 → 実際は [32] 行目: item.due = today + timedelta(days=LOAN_DAYS)
不一致  45行目: 引用「if len(member.borrowed) > MAX_ITEMS:」はファイルに無い（実際: if len(member.borrowed) >= MAX_ITEMS:）

3つ目のように、>= と > の1文字の違いは目で読むと見逃しやすい箇所です。機械的に照合すると確実に拾えます。「不一致」が出た説明は、その部分をもう一度聞き直します。

推測と事実を分けさせる

いまの説明を、次の3つに分けて表にしてください。
| 説明の内容 | 区分 | 根拠 |

区分は次のどれか：
- 事実：貼られたコードの行から直接読み取れる（根拠に行番号）
- 推測：名前や一般的な書き方からの見立て（根拠に、そう考えた理由）
- 不明：貼られたコードだけでは分からない（根拠に、何があれば分かるか）

「推測」と「不明」に入った項目は、コードの別の場所を読むか、書いた人に聞いて確かめます。

実行して流れの順番を確かめる

Python には、実行された行を順に表示する trace モジュールが標準で入っています。段階2・3の説明と、実際に通った行を照らし合わせられます。

python3 -m trace --trace lending.py | grep '^lending.py' | sed -n '/(30)/,/(35)/p'

lending.py(30):         item = self._find(code)
lending.py(38):         if code not in self.items:
lending.py(40):         return self.items[code]
lending.py(31):         self._check(member, item)
lending.py(43):         if item.due is not None:
lending.py(45):         if len(member.borrowed) >= MAX_ITEMS:
lending.py(32):         item.due = today + timedelta(days=LOAN_DAYS)
lending.py(33):         member.borrowed.append(code)
lending.py(34):         self.log.append(f"{today} lend {code} to {member.name}")
lending.py(35):         return item.due

30行目から 38・40行目に移り、31行目に戻っているのが分かります。呼び出し関係は --trackcalls で出せます。

python3 -m trace --trackcalls lending.py | grep -E '^\s+lending\.Library'

    lending.Library.lend -> lending.Library._check
    lending.Library.lend -> lending.Library._find

段階4の表と見比べれば、呼び出し関係の説明が実際の動きと合っているかを確かめられます（実行時に通った経路だけが出る点に注意します）。

説明を小さなテストにして確かめる

説明の1文を、そのまま確かめるコードにします。

from datetime import date

from lending import Item, Library, Member


def make():
    lib = Library()
    lib.add(Item("B001", "設計の本"))
    return lib


# 説明「返却期限は貸出日の14日後」を確かめる
lib = make()
assert lib.lend(Member("sato"), "B001", date(2026, 10, 5)) == date(2026, 10, 19)

# 説明「3冊借りている会員は4冊目を借りられない」を確かめる
lib = make()
try:
    lib.lend(Member("sato", ["B101", "B102", "B103"]), "B001", date(2026, 10, 5))
    print("例外は出なかった")
except ValueError as e:
    print("ValueError:", e)

# 説明「貸出中の本を借りようとすると、会員の一覧は変わらない」を確かめる
lib = make()
lib.lend(Member("sato"), "B001", date(2026, 10, 5))
ito = Member("ito")
try:
    lib.lend(ito, "B001", date(2026, 10, 6))
except ValueError as e:
    print("ValueError:", e)
print("ito.borrowed =", ito.borrowed, "/ log =", len(lib.log), "件")

ValueError: sato already has 3 items
ValueError: B001 is on loan until 2026-10-19
ito.borrowed = [] / log = 1 件

3つの説明は、どれも実際の動きと合っていました。テストを書く部分も AI に頼めます。

いまの説明のうち、実行して確かめられるものを、1つずつ assert か print で確かめる
Python のコードにしてください。各確認の前に、確かめる説明をコメントで書いてください。
テストが通ることを前提にせず、説明と違う結果になりうる箇所も含めてください。

デバッグ用・レビュー用プロンプトとの違い

コードを AI に渡す場面は似ていますが、目的によって渡すものと出力が変わります。

解説のプロンプトでは、「改善点は挙げなくてよい」と書いておくと、説明に指摘が混ざらず、流れに集中できます。

確かめて分かったこと

• Mermaid のノードにかっこを含む文字をそのまま書くと、構文エラーになった。二重引用符で囲むと描画できます。メソッド名を図に入れるときに当たりやすい点です
• 1文字違い（>= と >）や1行のずれは、スクリプトの照合で拾えた。引用を出させておくと、確かめる作業が機械的になります
• 引用の表をカンマ区切りにすると、コードの中のカンマで列が分かれてしまった。タブ区切りで出させると、そのまま読み込めます
• python3 -m trace --trace の出力は、説明の「ステップの順番」とそのまま見比べられる。呼び先に移って戻る様子も行番号で分かります
• --trackcalls に出るのは、その実行で通った呼び出しだけ。例外の経路など、通らなかった分岐は別の入力で実行して確かめます

よくある質問

Q. 他の人が書いたコードを生成AIに読ませるとき、最初に何を聞けばよいですか？ A. 最初は全体の役割と入口を聞きます。「何のためのコードか、入力と出力、外部とのやり取り、入口になる関数」の5項目を各1〜2行で答えさせると、次に追う場所が決まります。

Q. コードが長くて一度に貼れないときはどうすればよいですか？ A. 入口のファイルと、そこから呼ばれるファイルの順に分けて渡します。先にファイルの一覧と各ファイルの冒頭だけを渡して「この機能を理解するために読むべきファイルの順番」を聞き、その順に段階1〜2を繰り返します。

Q. 生成AIの説明が正しいかどうかは、どう確かめればよいですか？ A. 行番号と引用を出させて元のコードと照合し、流れや値は実行して確かめます。引用が一致しない説明や、「推測」に分けられた項目は、そのまま信じずに聞き直すか、コードを読んで確かめます。

Q. フローチャートとシーケンス図の違いは何ですか？ A. フローチャートは条件による分岐を、シーケンス図は登場するものどうしのやり取りの順番を表します。1つの関数の中の if を整理したいならフローチャート、クラスや関数をまたぐ流れを見たいならシーケンス図を選びます。

Q. コードを外部のAIサービスに貼ってもよいですか？ A. 所属先の利用ルールと契約で認められた範囲で使います。貼る前に、鍵・パスワード・接続情報・個人の情報が含まれていないかを確かめます。

まとめ

• 聞く順番は全体の役割 → 入口から出口までの流れ → 関数ごと → 分からない行
• コードは行番号つきで渡し、説明に行番号と引用を付けさせる
• 流れは具体的な値を1組決めて追わせ、境界の値でもう一度聞く
• 図は、分岐ならフローチャート、やり取りの順番ならシーケンス図、構造ならクラス図
• Mermaid のノードの文字は二重引用符で囲むよう、プロンプトで指定する
• 説明は仮説として扱い、引用の照合・実行・小さなテストで確かめる
• 理解が目的のときは、改善点を求めないと書いて流れに集中する

参考・出典

• Anthropic「Prompting best practices」 https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices （2026年10月5日に閲覧）
• GitHub Docs「Prompt engineering for GitHub Copilot Chat」 https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering （2026年10月5日に閲覧）

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。