AIでレガシーコードを解析するときは、リポジトリ全体を一度に説明させるのではなく、ファイル一覧、実行方法、入口、主要処理、外部依存、変更履歴を根拠付きで段階的に調べます。
この記事では、初見のコードベースから構造図、根拠ファイル一覧、変更リスク、不明点シートを作る手順を解説します。
情報確認日：2026年7月18日（日本時間）
結論：AIの役割は仮説作成、人の役割は根拠確認
- 安全な範囲でリポジトリの事実を集める
- 起動点から1つの主要処理を追う
- DB・API・Queue・File・設定の境界を特定する
- 変更リスクと未解決事項を分ける
- 根拠ファイル付きのコードベースマップを更新する
最初に確認：ソースコード、設定、顧客データを外部AIへ送信してよいとは限りません。組織が許可したツール、リポジトリ、処理環境だけを使い、秘密情報や本番データを入力しないでください。
1．リポジトリの事実を集める
AIへ質問する前に、読み取りだけのコマンドで規模と構成を確認します。
git status --short
git ls-files
git log --oneline -20
git grep -n "main\\|bootstrap\\|createServer\\|routes"生成物、vendor、依存パッケージ、巨大なminify済みファイルは主な解析対象から外します。ただし、ロックファイルは依存バージョンの根拠として残します。
| 確認対象 | 分かること | 根拠例 |
|---|---|---|
| README・docs | 目的、起動、既知の制約 | README.md |
| manifest・lock | 言語、framework、script、依存 | package.json、composer.json |
| config例 | 必要な外部サービス | 秘密値を含まないexampleのみ |
| entry point | 起動時の処理 | main、server、index |
| test | 期待する振る舞い | unit、integration、fixture |
| Git履歴 | 変更理由と頻出箇所 | 対象pathのlogとdiff |
2．AIへコードベースマップを作らせる
目的:
このリポジトリの現状を変更せずに把握する。
入力:
- 追跡対象ファイル一覧
- README
- dependency manifest
- 起動script
出力:
1. 言語・framework・runtime
2. 起動方法
3. directoryごとの責務
4. entry point候補
5. DB/API/queue/file systemとの接続候補
6. 各判断の根拠ファイル
7. 確認できない点
ルール:
- 根拠のない推測は「仮説」と表示
- file pathを必ず付ける
- 変更やcommand実行はしない最初の出力は完成版ではなく調査計画です。「確認済み」「仮説」「未確認」の3状態を付けると、AIのもっともらしい誤読を発見しやすくなります。
3．入口から主要処理を1本だけ追う
全機能を同時に読むのではなく、ログイン、注文登録、バッチ処理など重要なユースケースを1つ選びます。
HTTP request
↓ routes/orders
controller
↓ request validation
service
├─ database repository
├─ payment API
└─ event queue
response / retry / error log各矢印について、呼び出し元、呼び出し先、入力、出力、失敗時の処理を根拠行と一緒に記録します。長いファイルを分割して渡す場合は、前後の文脈が失われないようにします。入力量の考え方はコンテキストウィンドウとはを参照してください。
4．外部依存と副作用を地図にする
| 境界 | 確認する内容 | 変更時の代表リスク |
|---|---|---|
| Database | table、transaction、migration | 互換性、lock、rollback |
| External API | endpoint、timeout、retry、認証 | 二重実行、rate limit |
| Queue・Job | producer、consumer、再試行 | 重複処理、順序 |
| File system | 読書き先、権限、cleanup | 上書き、容量不足 |
| Configuration | 環境差、default、feature flag | 本番だけ異なる挙動 |
外部接続はコードだけでなく、インフラ設定、CI、運用手順にも隠れます。AIが「使われていない」と判断しても、動的呼び出しや定期実行がないか人が確認します。
5．変更リスクと不明点を分ける
risk_id,area,change,impact,evidence,test,unknown,owner
R-01,orders,送料計算変更,請求額,file:line,境界値test,外部帳票への反映,業務担当
R-02,auth,session更新,全利用者,file:line,integration test,旧mobile app互換,backend
R-03,batch,再試行回数,二重送信,file:line,staging replay,idempotency有無,SREリスクは影響範囲と根拠がある項目、不明点は追加調査が必要な項目です。不明点を推測で埋めず、担当者、確認方法、期限を付けます。
完成させる4つの成果物
- コードベースマップ：directory、入口、主要flow、外部境界
- 根拠ファイル一覧：結論ごとのpathと該当箇所
- 変更リスク表：影響、test、rollback、owner
- 未解決質問表：仮説、確認方法、担当、状態
成果物はコード変更と同じようにレビューし、実装の更新に合わせて直します。差分を見る観点はAIコードレビューのチェックリストが参考になります。
よくある失敗
- 全ファイルを一度に渡し、根拠のない概要を信じる
- READMEだけを現行仕様とみなす
- 秘密情報や顧客データを許可なく入力する
- 動的呼び出し、cron、CI、運用scriptを見落とす
- 解析と同時に大規模リファクタリングを始める
- 不明点を記録せず、AIの推測で埋める
よくある質問
コード全体をAIへ読み込ませれば早いですか？
量だけ増やしても精度は保証されません。目的に関係する入口と依存を段階的に渡し、根拠を求める方が検証しやすくなります。
テストがないコードは解析できませんか？
解析はできますが、期待する振る舞いの確度が下がります。利用側、ログ、履歴、仕様書を集め、characterization testを追加する前提で計画します。
AIにそのまま修正させてもよいですか？
まず解析成果物を人が確認します。その後、小さな差分、テスト、rollback手順を用意して修正します。ツール選びはAIコーディングツール比較を参照してください。
まとめ
AIによるレガシーコード解析では、ファイル一覧と履歴から事実を集め、入口から主要処理を1本ずつ追います。AIの説明は必ず根拠pathと結び付け、仮説と未確認事項を分けてください。
構造図、根拠一覧、変更リスク、不明点表が揃えば、次の調査や小さな修正を安全に計画できます。