「いまどきAIに任せれば、レガシーコードの調査なんて一発でしょう」
そう言われてClaude Codeに対象のリポジトリを丸ごと放り込んだ結果、返ってきた解説が現場の仕様とまるで噛み合わない。そんな経験はないでしょうか。
受託開発の現場でよく起きるのは、こんな場面です。
- 10年もののレガシー業務システムの改修案件で、影響範囲をClaude Codeに聞いたら「このクラスは未使用です」と断言されたが、実際は夜間バッチから動的に呼ばれていた
- 機能追加の前にClaude Codeに仕様を要約させたら、それらしい説明文は出てきたが、肝心の決済まわりの分岐が完全に抜け落ちていた
- 「とにかくファイルを全部渡せばいい」と判断したテックリードが、トークン上限に当たるたびに渡す範囲を削り、その削り方が個人技になっていた
問題はモデルの賢さではなく、こちらの文脈の渡し方にあります。レガシーコードの調査でClaude Codeが外す原因の大半は、ファイルや説明の量ではなく、何を読ませて何を読ませないかの設計が抜けていることです。
本記事では、受託開発のテックリード・PMがClaude Codeをレガシー調査の戦力として運用するための「入口ファイル・依存関係・調査仮説・除外範囲」という4点のコンテキスト設計を解説します。読み終えたあと、自分のリポジトリでも同じ枠で文脈を渡せるようになるはずです。
なぜClaude Codeはレガシーコードでズレるのか
Claude Codeが的外れな回答をする原因は、おおよそ次の3つに分けられます。
- 前提が渡っていない（業務知識・命名の意図・歴史的経緯）
- 渡しすぎてノイズになっている（無関係なファイルや古い試作コードまで読ませている）
- 何を確かめてほしいのかが曖昧（「このコードを説明して」だけ）
レガシーコードの調査でズレが目立つのは、3つ全部が同時に起きやすいからです。新規プロジェクトなら設計ドキュメントが整っていることもありますが、受託で引き継いだ古い案件では「コードがすべての仕様」になっており、コミットメッセージも「修正対応」しかない、ということがざらにあります。
そこに対象のソースを丸ごと渡せば、Claude Codeはそのコードの中だけで完結する解釈をします。結果として、夜間バッチから呼ばれる前提や、過去の障害対応で残った例外分岐が見えないまま、「未使用」「冗長」と判断してしまう。
この種類のズレは、プロンプトを少し直す程度では再発します。必要なのは、渡す情報そのものを設計するという考え方です。
レガシー調査のコンテキスト設計：4点フレーム
そこで、受託開発の現場で扱いやすいフレームとして「入口ファイル・依存関係・調査仮説・除外範囲」の4点を提案します。
ファイルを丸投げするのでもなく、説明文をだらだら書きすぎるのでもない、この4点を埋めるやり方です。
1. 入口ファイル：どこから読むかを固定する
最初に決めるのは「どのファイルを起点に読ませるか」です。
レガシーコードでも、業務的な入口は意外と少数です。たとえば次のようなものが入口になります。
- Web画面なら、ルーティング定義と該当コントローラ
- バッチなら、エントリポイントのスクリプトと起動シェル
- 外部連携なら、受信処理のエンドポイントとスケジューラ設定
この入口を、Claude Codeに最初に読ませるファイルとして明示します。たとえば「まず src/batch/nightly_billing.rb を読んでほしい。これは夜間バッチのエントリポイントで、ここから呼ばれているクラスだけが今回の調査対象」といった具合です。
入口を固定する効果は2つあります。
ひとつは、Claude Codeがコード全体をフラットに見るのではなく、呼び出しの流れに沿って読み進めるようになること。もうひとつは、後工程で「この機能はバッチ経由でも動きます」とこちらから補足しなくても、勝手に夜間バッチ前提の解釈をしてくれること。
入口を1〜3個に絞れない調査は、そもそもスコープが広すぎる可能性が高いと考えてください。
2. 依存関係：周辺をどこまで読ませるか
入口を決めたら、次は「入口から先のどこまでを読ませるか」を決めます。
ここでよくある失敗が、呼ばれているクラスをすべて再帰的に読ませようとすることです。レガシーコードでは共通ユーティリティが肥大化しており、たどっていくとプロジェクト全体に行き着いてしまいます。
代わりに、依存の段数を意図的に区切ると扱いやすくなります。
- 1段目：入口ファイルから直接呼ばれるクラス・関数
- 2段目：1段目から呼ばれる業務ロジックのクラス
- 3段目以降：共通ユーティリティ、ライブラリラッパー（基本は読ませない）
そのうえで、Claude Codeへの指示にも「2段目までを精読対象、3段目以降は名前と引数だけ把握すればよい」と書きます。
これは人間が短期間でレガシーを読むときと同じ動き方です。AIに任せる場合も、どこまで深追いするかを人間側で決めて渡すほうが、結果として精度が安定します。
3. 調査仮説：何を確かめたいかを宣言する
3つ目が、もっとも軽視されがちですが、もっとも効きます。
「このコードを説明して」「リファクタの提案をして」といった抽象的な依頼ではなく、仮説を持った問いを渡します。
たとえばこんな形です。
- 「夜間バッチの
nightly_billing.rbから、当月の売上集計が二重カウントされる経路があると疑っている。そのような分岐があるか確認してほしい」 - 「決済まわりの例外処理が、Slack通知だけで握りつぶされているのではないかと疑っている。例外をcatchしている箇所と、そこから先のフローを洗ってほしい」
- 「
Userモデルのstatusカラムが、ドキュメントにない値（‘archived’ など）で運用されている可能性がある。実際に書き込みうる値の集合を、コードから列挙してほしい」
ポイントは、仮説を「Yes/Noで答えられる粒度」まで絞ることです。
仮説のない依頼は、Claude Code側で「たぶんこのへんが大事だろう」という推測が入り、結果としてズレやすくなります。逆に、検証可能な仮説を1つに絞って渡せば、出力は「ある／ない／部分的にある」のいずれかに収束し、人間側のレビューも一気に楽になります。
4. 除外範囲：読ませない場所を明示する
最後の1点が、見落とされがちな「読ませない場所の明示」です。
レガシー業務システムには、たいてい次のような領域が混在しています。
- すでに使われていない旧機能のコード（残してあるだけ）
- 検証用・調査用の使い捨てスクリプト
- 自動生成されたコード（マイグレーション、APIクライアントなど）
- ベンダー製の組み込みライブラリ
- テスト用のフィクスチャやダミーデータ
ここまでをClaude Codeに読ませると、出力が現役の業務ロジックと旧コードを区別せずに説明し始めます。「このメソッドはこういう用途で〜」という解説の半分が、実は誰も呼んでいないコードについての説明だった、ということが起きます。
そこで、入口・依存と同じレベルで「今回の調査では読まなくてよい場所」を宣言します。
実務では、次のような書き方で十分機能します。
- 「
legacy/配下は今回触らないので無視してほしい」 - 「
db/migrate/のマイグレーションは仕様の変遷を追うため以外には参照しないでほしい」 - 「
scripts/oneshot/は過去の調査用スクリプトなので、業務仕様の根拠としては使わないでほしい」
除外範囲をはっきり伝えるほど、Claude Codeの出力は現役の業務仕様に寄っていきます。
4点をテンプレ化して渡す
4点が揃ったら、テンプレートとして固定し、案件ごとに穴埋めで使えるようにしておきます。たとえば次のような構造です。
【入口ファイル】
- src/batch/nightly_billing.rb（夜間バッチのエントリポイント）
- 補助: config/schedule.rb（cron 設定）
【依存の深さ】
- 1〜2段目までを精読対象
- 共通ユーティリティ（lib/utils/ 配下）はシグネチャのみで OK
【調査仮説】
- 月次集計が二重計上されうる分岐があるのではないか
- 具体的には status=canceled の扱いに矛盾があると疑っている
【除外範囲】
- legacy/v1/ 配下（旧サービスの残骸）
- spec/, test/ 配下（今回は本体の挙動だけ確認したい）
- db/seeds/ 配下
【出力してほしいこと】
- 仮説に対する Yes/No と根拠ファイル/行
- 二重計上の経路があるなら、その呼び出しチェーンこのテンプレートを最初にClaude Codeに渡してから、コードを共有します。順番が重要で、コードより先に文脈設計を渡すほうが、初手の解釈が安定します。
よくある失敗
ここまでのフレームを使い始めるときに、現場でよく見かける失敗を3つだけ挙げておきます。
ひとつ目は、入口ファイルと調査仮説を兼用してしまうこと。「nightly_billing.rb を見てほしい」とだけ渡しても、それは入口を示しただけで、何を確かめたいかは伝わっていません。
ふたつ目は、除外範囲を口頭の前提に閉じ込めること。テックリードの頭の中では「あの旧モジュールはもう使ってない」と分かっていても、Claude Codeには書かれた情報しか届きません。書かないと、必ず読みにいきます。
3つ目は、1回の調査でやらせすぎること。「全体把握」「リスク洗い出し」「リファクタ提案」を一度にお願いすると、どの仮説に答えているのかが曖昧になります。1回1仮説、を目安に分けるほうが結果的に早く進みます。
個人技から、チームの型へ
ここまでの4点設計は、本来「できるテックリードが頭の中でやっていたこと」をそのまま外に出したものです。
入口を見極め、依存をどこまで追うかを判断し、仮説を持って読み、関係ない場所を切り捨てる。レガシーコードに強い人ほど、この4つを無意識に切り替えています。
Claude Codeを使うときに同じ4点を明示的にテンプレ化しておくと、次のような副次効果が出てきます。
- 若手メンバーがレガシー調査に入るときの、思考のフレームになる
- 案件引き継ぎの際、調査依頼をClaude Code経由で標準化できる
- 「AIに任せたら何が出てくるか」が個人差で揺れにくくなる
つまり、コンテキスト設計のテンプレ化はAI活用の話であると同時に、レガシー調査という属人化しがちな業務を仕組みに寄せる打ち手でもあります。
AIへのインプット設計やレビュー観点を業務文書側で整理した記事として、PMの板挟みをAIで解決。営業要望を仕様書に変えるプロンプト術 や、AIをコンサル化するPMのリスク管理プロンプト術 も合わせて読むと、文脈設計の発想が業務全体でつながります。
まとめ
レガシーコードの調査でClaude Codeが外すのは、モデルの問題ではなく、こちら側の文脈設計の不在であることがほとんどです。
押さえるべきは4点だけです。
- 入口ファイル：どこから読み始めるか
- 依存関係：どの段数まで深追いするか
- 調査仮説：何をYes/Noで確かめたいか
- 除外範囲：どこは読ませないか
この4点をテンプレ化し、コードよりも先に渡す。それだけで、Claude Codeの出力はだいぶ業務仕様に寄ってきます。あとは、案件ごとに1回1仮説で運用していけば、個人技だったレガシー調査がチームの型に変わっていきます。
この4点設計をドキュメント業務やプロジェクト運用全体のAI活用に広げて体系的に学びたい方は、以下の関連講座をご覧ください。
- 【生成AI実践】仕様書・報告書・議事録を半分の時間で仕上げる技術（AIX-101）：プロンプト設計からレビュー、テンプレート化までを実務文書の単位で扱います
- 【生成AI実践】進捗・課題・リスク管理をAIで加速する運用設計（AIX-102）：本記事の発想を、PMの管理運用そのものに展開した内容です
レガシー調査での4点設計は、それ単体でも有効ですが、AI活用を業務改善として定着させるところまで進めると効果が大きく変わります。手元の案件で次の調査依頼をClaude Codeに投げる前に、まずこの4点を埋めることから始めてみてください。