古いWebアプリの構造をAIでつかむ:読み取り専用で使う質問テンプレート集

まず「変更できない状態」を作る

質問の前に、ツール側で編集できない状態にしておきます。「変更しないで」と文章で頼むだけより確実です。

• Cursor:公式ヘルプによると、Askモードは「コードベースを理解するための読み取り専用モード」です。Agentパネルを開き、Shift + Tabでモードを切り替えるか、モード選択から選べます。コード変更につながる質問はAgentモードに切り替える、という位置づけです(Cursor: Ask mode)。
• Claude Code:planモードはコードベースの探索に使えます。Shift + Tabで切り替えられます。/planやclaude --permission-mode planで開始する方法もあります。planモードで自動承認される操作は、autoモードが利用できるかなどの条件によって異なります。bypass権限が有効な対話セッションでは、plan中でも保護対象のパスへの書き込みが自動承認される場合があります。起動方法や設定を確認してから使ってください(Claude Code: Choose a permission mode)。
• Claude CodeのManualモード:読み取りと検索は作業ディレクトリ内なら承認不要です。ファイル編集は承認が必要で、シェルコマンドも読み取り専用として扱われる組み込みコマンド以外は原則承認を求められます(Claude Code: Configure permissions)。

上記は公式ページを2026年10月29日に確認した内容です。モード名や挙動は更新されることがあるため、使う時点の設定と画面で確認してください。

一つ注意があります。読み取り専用は「編集できない」ことを意味するだけで、「ファイルの内容がAIに送られない」ことは意味しません。社外秘のコードや、鍵・パスワード・個人情報を含むファイルは、会社のルールを確認してから読ませます。設定ファイルの実値は、ダミーに置き換えるか、読ませる範囲から外してください。

質問の順番:構造 → 依存 → 影響範囲

Cursorの学習ページでは、未知のコードには広い質問から始めて具体化する進め方、変更を頼む前にまず探索させる進め方が紹介されています(Cursor: Understanding your codebase)。この考え方に沿って、次の3段階にします。

• 1. 構造、知りたいこと：入口、ディレクトリの役割、処理の流れ、人が確認する方法：挙げられたファイルを開き、入口から実際にたどる
• 2. 依存、知りたいこと：ライブラリ、DB、外部API、設定、バッチ、人が確認する方法：依存定義ファイルと検索結果で照合する
• 3. 影響範囲、知りたいこと：ある関数・テーブル・画面を変えると何に響くか、人が確認する方法：全文検索の件数と一致するか確かめる

質問テンプレート集

【 】の部分を自分の情報に置き換えて使います。どれも先頭に共通の前置きを付けます。

共通の前置き

これは読み取り専用の調査です。ファイルの作成・編集・削除、
コマンドによる変更、パッケージのインストールはしないでください。
回答は次の3種類に分けてください。
- 確認済み:読んだファイルのパスと行番号を添える
- 推測:根拠が間接的なもの。何から推測したかを書く
- 未確認:読めていない、または判断できないもの

この3分類が後で効きます。AIは推測も断定口調で書きがちなので、分類を強制しておくと、人が確認すべき箇所が見えます。

構造を尋ねる

【フレームワークや言語が分かれば書く】製のWebアプリです。
1. リクエストの入口になるファイルと、ルーティングの定義場所を挙げてください。
2. トップレベルの各ディレクトリの役割を1行ずつ説明してください。
3. 「【画面名や機能名】」が表示されるまでの処理を、
   入口から順にファイル名と関数名で並べてください。

依存を尋ねる

このリポジトリが依存しているものを次の観点で一覧にしてください。
- ランタイムとライブラリ(定義ファイルのどこに書かれているか)
- 接続しているDB・キャッシュ・外部API(接続設定を読んでいる箇所)
- 環境変数と設定ファイル(キー名だけ。値は出力しないこと)
- 定期実行・バッチ・キューなど、リクエスト以外で動く処理
定義が見つからないものは「未確認」にしてください。

「値は出力しない」と書くのは、設定の実値が会話ログに残るのを避けるためです。

影響範囲を尋ねる

【関数名/テーブル名/URL】を変更した場合に影響を受けそうな箇所を調べてください。
1. 直接参照している箇所(検索に使った語句と件数を書く)
2. 間接的に影響しそうな箇所(文字列で組み立てられた呼び出し、
   動的な読み込み、SQLの文字列など、検索で拾いにくいもの)
3. 該当箇所に対応するテストの有無
修正案は出さないでください。

古いアプリでは、文字列連結で作られた呼び出しや動的な読み込みが影響範囲の見落としになりやすいので、2番を独立した項目にしています。

聞き返しテンプレート

いまの回答のうち「推測」と「未確認」だけを抜き出し、
それぞれ人が何を見れば確かめられるか(ファイル、画面、ログ、担当者への質問)を
書いてください。

説明用の例:入力と記録

次は、架空の社内予約システム(PHP製を想定)での説明用の例です。実在のコードを調べた結果ではありません。

入力例:共通の前置き + 「予約確認メールの送信処理を変更した場合の影響範囲」

記録の例(AIの回答を貼ったあと、人が追記した形)

• 送信関数の定義、内容：lib/mail.php の send_confirm()、区分：確認済み、人の確認：開いて確認
• 呼び出し元、内容：予約完了画面、管理画面の再送ボタン、区分：確認済み、人の確認：全文検索で2件と一致
• 夜間バッチからの呼び出し、内容：あるかもしれない、区分：推測、人の確認：cron設定を要確認
• 件名テンプレート、内容：DBの設定テーブルか、区分：未確認、人の確認：担当者に質問

ここでは「推測」が人の作業リストになります。1回の調査で全部を埋めようとせず、未確認を次の質問や担当者への確認に回します。

記録の取り方

記録は、あとで自分や他の人が読み返せることを優先します。次の項目を1件ずつ残せば足ります。

1. 日付と対象:調査した日、ブランチやコミット(コードが変わると答えの有効性が変わるため)
2. 質問文:使ったテンプレートと置き換えた語句
3. 回答の要点:確認済み・推測・未確認に分けて転記
4. 人の確認結果:確認した方法と、一致したか、食い違ったか
5. 次の一手:未確認を誰が何で確かめるか

AIの回答をそのまま長文で保存するより、人が確認した結果だけを表に残すほうが、後から信頼できます。食い違いがあった場合は、それも消さずに残してください。どの種類の質問でAIが外しやすいかが分かり、次回の前置きを改善できます。

人が確認すること、AIに任せること

• AIに任せる:ファイルの探索、候補の列挙、処理の流れの下書き、図の元になる文章
• 人が確認する:挙げられたパスと行番号が実在するか、検索件数が一致するか、「ない」という主張(見つからなかっただけの可能性がある)
• まだ頼まない:修正、リファクタリング、依存の更新。構造の記録が固まり、テストなど戻す手段がそろってからにします

特に「ない」「使われていない」という回答は、検索で拾えない呼び出しがあると誤りになります。削除の判断には使わず、必ず自分で検索して確かめてください。