Claude Codeでレガシーコードを解析する方法

Claude Codeとは

Claude Codeは、コードベースを読みながら開発者の調査、理解、修正、テスト作成を支援するAIツールです。

レガシーコードを扱うときは、単にコードを書かせるためではなく、複雑な処理を整理して人が判断しやすくするために使うと効果的です。

既存システムの保守では、コード量が多いことよりも、どこに何が書かれているのか分からないことが大きな負担になります。

Claude Codeは、その負担を減らすために、コードの構造、処理の流れ、影響範囲、注意点を言葉に変換する補助役として使えます。

レガシーコード解析で使う前提

レガシーコード解析では、Claude Codeに作業を丸投げするのではなく、人がコードを理解するための補助役として使うことが大切です。

古いコードには、仕様書に書かれていない業務ルール、過去の障害対応で入った分岐、担当者しか知らなかった例外処理が残っていることがあります。

Claude Codeはそれらを整理する手がかりを出せますが、最終的に正しいかどうかはコード、テスト、ログ、実行結果で確認する必要があります。

特にレガシーコードでは、コメントが古いまま残っていたり、関数名と実際の役割がずれていたりすることがあります。

そのため、Claude Codeの説明が自然に見えても、すぐに仕様として確定せず、根拠となるコードの行や処理を確認する姿勢が欠かせません。

できることと苦手なこと

Claude Codeは、ディレクトリ構成の整理、処理フローの説明、複雑な関数の分解、テスト観点の洗い出し、リファクタリング案の比較に向いています。

一方で、実際の本番データ、運用上の暗黙ルール、外部サービス側の仕様、古いコメントと現在の挙動の違いまでは自動で保証できません。

そのため、Claude Codeの説明は便利な仮説として受け取り、確認作業とセットで使う姿勢が重要です。

たとえば、Claude Codeが「この処理は未使用に見える」と説明しても、設定ファイル、バッチ、外部ジョブ、動的呼び出しから使われている可能性があります。

便利な分析結果ほど、そのまま採用したくなりますが、実務では「何を根拠にそう判断したのか」を確認することが安全な使い方になります。

レガシーコード解析でClaude Codeが役立つ場面

Claude Codeは、読みづらい既存コードを前にして、どこから調べればよいかわからないときに役立ちます。

特に、保守担当の交代、仕様書の不足、改修前の影響調査、テスト不足のコード改善では、調査の入口を作る道具として使いやすいです。

人が一からすべてのファイルを読む前に、Claude Codeで全体像や候補箇所を整理しておくと、調査の優先順位を決めやすくなります。

ただし、役立つ場面は「判断を代わりにしてもらう場面」ではなく、「判断するための材料を集める場面」だと考えると失敗しにくくなります。

仕様書が古い、または存在しない場合

仕様書が古かったり存在しなかったりする場合は、コードから現在の動作を逆算する必要があります。

Claude Codeには、対象ファイルを読ませて、入力、処理、出力、例外時の動きを機能仕様の形で整理してもらうと便利です。

ただし、コードから読み取れることと、業務上そう運用されているはずという推測は分けて残すべきです。

仕様書が残っている場合でも、最終更新日が古い、現在の画面と記述が違う、廃止された機能が混ざっていることがあります。

そのようなときは、Claude Codeに「コードから確認できる現行仕様」と「仕様書と差がありそうな点」を分けて整理してもらうと、確認作業を進めやすくなります。

担当者がいない既存システムを引き継ぐ場合

担当者が退職していたり、詳しい人が少なかったりする既存システムでは、最初の全体把握に時間がかかります。

Claude Codeに主要ディレクトリ、重要ファイル、処理の入口、設定ファイルを整理してもらうと、読み始める場所を絞りやすくなります。

引き継ぎ直後は、細かい修正よりも、まずシステムの地図を作ることを優先すると安全です。

たとえば、どのディレクトリが画面側で、どこがAPIで、どこにDBアクセスが集まっているのかを把握できるだけでも、調査の迷いはかなり減ります。

さらに、次に確認すべきファイルや、変更リスクが高そうな領域を候補として出してもらうと、引き継ぎ初期の作業計画を立てやすくなります。

改修前に影響範囲を知りたい場合

レガシーコードでは、一見小さな修正でも、共通関数、設定値、DB更新、外部連携に影響することがあります。

Claude Codeに呼び出し元、呼び出し先、参照している設定、更新しているデータを洗い出してもらうと、変更前の確認漏れを減らせます。

影響範囲の調査では、修正対象のファイルだけでなく、その周辺で何が起きているかを見ることが大切です。

特に共通処理は、ひとつの画面のために直したつもりでも、別の画面やバッチ処理まで変えてしまうことがあります。

Claude Codeには、変更候補を出してもらう前に、まず影響しそうな機能、テスト、設定、外部連携を整理してもらうと安全です。

Claude Codeを使う前の準備

Claude Codeでレガシーコードを解析する前に、目的、範囲、安全面を整理しておくと回答の質が上がります。

準備をせずに大きなリポジトリを一気に読ませると、回答が抽象的になったり、重要な前提が抜けたりしやすくなります。

最初に準備をする目的は、Claude Codeにきれいな答えを出してもらうためだけではありません。

人間側が何を判断したいのかを明確にし、回答を検証しやすい形にするためでもあります。

目的を先に決める

最初に、何のためにコードを解析するのかを決めます。

たとえば、全体像を知りたいのか、特定機能を改修したいのか、テストを追加したいのか、仕様書代わりの資料を作りたいのかで聞き方は変わります。

目的が曖昧なまま依頼すると、Claude Codeは広く浅い説明を返しやすくなります。

「この決済処理の影響範囲を知りたい」「この関数を安全に分割する前に責務を整理したい」のように目的を具体化すると、実務で使いやすい回答になります。

目的を決めるときは、最終的に何を判断したいのかまで書いておくとさらに効果的です。

たとえば、「修正すべきファイルを知りたい」のか、「修正前に追加すべきテストを知りたい」のか、「仕様としてドキュメント化したい」のかで、必要な出力は変わります。

読ませる範囲を小さく区切る

レガシーコード解析では、リポジトリ全体を一度に読ませるより、機能単位やファイル単位に分けたほうが精度が上がります。

まずはディレクトリ構成や主要ファイルを見てもらい、次に対象機能の入口、最後に複雑な関数という順番で深掘りすると整理しやすくなります。

範囲を区切ると、Claude Codeの説明に対して人間側もレビューしやすくなります。

大きな依頼を小さく分けることは、AIのためだけでなく、チーム内で調査結果を共有するうえでも有効です。

また、範囲を小さくすると、Claude Codeがどの情報を根拠に回答したのかを追いやすくなります。

最初は広く浅く、次に狭く深くという順番にすると、調査の抜け漏れと誤読の両方を減らしやすくなります。

機密情報や不要な情報を整理する

コード解析にAIを使う前には、環境変数、APIキー、個人情報、顧客情報、社内固有の秘密情報が含まれていないか確認します。

解析に不要なログ、生成ファイル、巨大な依存ライブラリ、古いバックアップファイルも、回答のノイズになることがあります。

安全に使うためには、必要なファイルだけを対象にし、機密情報を扱うルールをチームで決めておくことが重要です。

特にレガシーシステムでは、古い設定ファイルや一時ファイルに、現在は使っていない認証情報が残っていることもあります。

Claude Codeに読ませる前に、対象範囲を整理し、マスクすべき値は伏せ、社内ルールに沿った使い方になっているか確認しておくと安心です。

プロジェクト全体の概要を把握する

最初の解析では、細かい関数に入る前に、プロジェクト全体の構造をつかむことが大切です。

全体像がないまま一部のコードだけを読むと、その処理がどの機能に属しているのか、どこに影響するのかを見誤りやすくなります。

全体像を把握する段階では、完璧な仕様理解を目指す必要はありません。

まずは、主要な構成要素、処理の入口、データの流れ、外部連携の有無を大まかにつかむことが目的です。

ディレクトリ構成から役割を推測する

Claude Codeには、まずディレクトリ構成を見せて、各フォルダの役割を推測してもらいます。

画面、API、バッチ、ドメインロジック、DBアクセス、設定、テストなどに分けて整理してもらうと、プロジェクトの地図が作れます。

この時点では細かい実装の正確さよりも、どこに何がありそうかを把握することが目的です。

ディレクトリ名が古かったり、現在の役割と一致していなかったりする場合もあります。

そのため、Claude Codeには「推測である箇所」と「ファイル名や構成から確認できる箇所」を分けて出してもらうと便利です。

エントリーポイントを探す

次に、アプリケーションの入口を探します。

Webアプリならルーティング、コントローラー、APIハンドラ、フロントエンドの初期化処理が入口になりやすいです。

バッチやCLIなら、実行コマンド、メイン関数、スケジューラ設定、ジョブ定義を確認します。

Claude Codeに「このプロジェクトの処理の入口になっていそうなファイルを挙げてください」と依頼すると、読み始める場所を絞れます。

エントリーポイントが分かると、ユーザー操作や外部イベントがどの処理につながるのかを追いやすくなります。

逆に入口が分からないまま内部の関数だけを読んでも、その関数がいつ、どの条件で動くのか判断しづらくなります。

最初に作ってもらう概要メモ

全体把握の段階では、Claude Codeに長い説明ではなく、短い概要メモを作ってもらうと便利です。

主要機能、重要そうなファイル、外部連携、データの流れ、次に調べるべき箇所を箇条書きでまとめてもらいます。

この概要メモは、後から調査を進めるときの目次になります。

未確認の内容は「推測」として分けてもらうと、あとで検証しやすくなります。

概要メモには、確実に分かったことだけでなく、次に確認すべき疑問も残しておくと役立ちます。

たとえば、「この設定ファイルが本番で使われているか未確認」「この外部APIの仕様は別途確認が必要」のように書いておくと、調査漏れを防げます。

処理フローを解析する

プロジェクトの全体像が見えたら、次は特定機能の処理フローを追います。

処理フローの解析では、入口から出力までを順番にたどり、どのファイルで何が起きているかを整理します。

レガシーコードでは、処理が複数の層に分かれていたり、逆にひとつの関数に多くの責務が詰め込まれていたりします。

Claude Codeを使うと、そうした読みにくい流れを、人が確認しやすい手順や表に変換できます。

ユーザー操作からコードの流れを追う

ユーザー操作がある機能では、画面操作からAPI呼び出し、サービス処理、DB操作、レスポンス生成までを一連の流れとして追います。

Claude Codeには、「この機能が実行されたときの処理フローを、ファイル名と関数名を含めて順番に説明してください」と依頼します。

ファイル名や関数名が入っていると、後から人が実コードを確認しやすくなります。

単なる説明だけでなく、どこで入力値が検証され、どこでデータが更新され、どこで例外が処理されるかも見てもらうと実用的です。

処理フローを追うときは、画面やAPIの入口だけでなく、最終的にどのデータが変わるのかまで見ることが重要です。

出力や副作用まで整理しておくと、改修時に守るべき挙動を判断しやすくなります。

条件分岐と例外処理を見落とさない

レガシーコードでは、正常系よりも条件分岐や例外処理に重要な仕様が隠れていることがあります。

権限がない場合、データが存在しない場合、外部APIが失敗した場合、古いデータ形式が残っている場合などを確認します。

Claude Codeには、「正常系だけでなく、条件分岐、例外処理、早期return、エラーログ出力も洗い出してください」と依頼するとよいです。

特殊ケースを見落とすと、改修後に一部の顧客だけで不具合が出ることがあります。

特に、古いシステムでは「なぜこの分岐があるのか分からないが消せない処理」が残っていることがあります。

そのような分岐は、消す前にログ、テスト、過去のチケット、運用担当への確認で利用状況を調べる必要があります。

図解や箇条書きで整理してもらう

処理フローが長い場合は、文章だけでなく箇条書きや簡易フローチャート風に整理してもらうと理解しやすくなります。

たとえば、入力、検証、分岐、DB更新、外部連携、出力の順に並べるだけでも、レビューしやすさが変わります。

チームで共有するなら、Markdown形式で「処理順」「対象ファイル」「注意点」を表にしてもらう方法もあります。

ただし、表にした内容もコードと照合し、漏れや誤解がないか確認する必要があります。

図解や表は、複雑なコードを理解するための補助資料として便利ですが、正しさを保証するものではありません。

共有資料にする場合は、確認済みの箇所と未確認の箇所を明記しておくと、後から修正しやすくなります。

依存関係を洗い出す

レガシーコードを安全に変更するには、対象コードが何に依存していて、どこから使われているかを把握する必要があります。

依存関係を見ないまま変更すると、別機能やバッチ処理、外部連携に予想外の影響が出ることがあります。

依存関係の調査では、コード上の呼び出しだけでなく、設定、DB、外部サービス、実行環境まで含めて見ることが大切です。

Claude Codeには、調査対象を明確にしたうえで、影響しそうな範囲を広めに洗い出してもらうと役立ちます。

呼び出し元と呼び出し先を確認する

まず、対象の関数やクラスがどこから呼ばれているかを確認します。

次に、その関数やクラスが内部でどの処理を呼び出しているかを見ます。

Claude Codeには、「この関数の呼び出し元、呼び出し先、変更時に影響しそうな箇所を整理してください」と依頼します。

呼び出し関係は、静的に追えるものだけでなく、設定や文字列による動的呼び出しがないかも確認が必要です。

たとえば、ルーティング設定、DIコンテナ、イベントリスナー、ジョブ定義、テンプレート内の参照などは、単純な検索だけでは見落としやすいことがあります。

Claude Codeの洗い出し結果をもとに、人間側でも検索や実行確認を行うと、影響範囲の精度が上がります。

外部ライブラリや設定ファイルを見る

コードの動きは、ソースファイルだけで決まるわけではありません。

DB設定、環境変数、設定ファイル、外部API、キュー、ジョブスケジューラ、ライブラリのバージョンも挙動に影響します。

Claude Codeに依頼するときは、「コード以外に動作へ影響している設定や外部依存も挙げてください」と明示すると抜け漏れを減らせます。

特に古いシステムでは、設定値ひとつで処理が大きく変わることがあります。

また、ライブラリのバージョンが古い場合、現在のドキュメントに書かれている挙動と実際の挙動が違うこともあります。

Claude Codeの説明だけで判断せず、プロジェクト内のロックファイルや設定ファイルも確認しましょう。

変更してはいけない境界を見つける

依存関係を洗い出す目的は、変更できる場所と慎重に扱うべき場所を分けることです。

共通関数、認証処理、決済処理、外部連携、データ移行処理などは、影響が大きくなりやすい領域です。

Claude Codeには、「変更リスクが高い箇所と、その理由を分けて説明してください」と聞くと判断しやすくなります。

変更してはいけない境界を知っておくと、リファクタリングの範囲を安全に決められます。

境界を見つけるときは、技術的な共通処理だけでなく、業務上重要な処理も意識します。

売上、請求、権限、通知、監査ログなどに関わる処理は、たとえ小さな関数でも慎重に扱うべきです。

複雑な関数を読み解く

レガシーコードには、長い関数、責務が混ざった関数、条件分岐が深い関数がよくあります。

こうした関数は、いきなり書き換えるのではなく、まず役割を分解して理解することが大切です。

長い関数を見ると、すぐに分割したくなるかもしれませんが、先にその関数が守っている挙動を把握する必要があります。

Claude Codeを使えば、関数の目的、入力、出力、副作用、分岐を整理し、変更前の理解を深められます。

関数の目的を一文で説明してもらう

最初に、その関数が何をするためのものなのかを一文で説明してもらいます。

長い関数を細部から読むと、途中で目的を見失いやすくなります。

「この関数の目的を一文で説明し、その根拠になる処理を挙げてください」と依頼すると、説明とコードの対応を確認しやすくなります。

目的が一文で言えない場合は、複数の責務が混ざっている可能性があります。

ただし、目的が複数に見えるからといって、すぐに分割すればよいわけではありません。

まずは、その関数がなぜ複数の処理をまとめて持っているのか、履歴や呼び出し側の都合も含めて確認する必要があります。

入力、出力、副作用に分けて見る

複雑な関数は、入力、出力、副作用に分けると理解しやすくなります。

入力には引数、リクエスト値、設定値、DBから取得する値があります。

出力には戻り値、レスポンス、画面表示、生成ファイルがあります。

副作用にはDB更新、ログ出力、メール送信、外部API呼び出し、キャッシュ更新があります。

Claude Codeにこの観点で整理してもらうと、変更時に何を壊してはいけないかが見えやすくなります。

特に副作用は、関数名から分かりにくいことがあります。

たとえば、単なる取得処理に見える関数が、最終アクセス日時を更新していたり、通知キューへ登録していたりする場合があります。

分割候補を出してもらう

関数の役割が見えてきたら、次に分割候補を出してもらいます。

ただし、この段階でいきなりコードを書き換えさせる必要はありません。

まずは「バリデーション」「データ取得」「変換」「保存」「通知」のように、責務ごとに分けられるかを確認します。

Claude Codeには、「既存の挙動を変えずに分割できそうな単位を提案してください」と依頼すると安全です。

分割案は、テストを追加してから少しずつ適用するのが基本です。

また、分割候補を出してもらうときは、メリットだけでなくリスクも一緒に出してもらいます。

たとえば、分割によって呼び出し順が変わる可能性、例外処理の位置が変わる可能性、副作用が見えにくくなる可能性を確認しておくと安心です。

仕様書の代わりになるドキュメントを作る

解析した内容は、その場で理解して終わらせず、チームで再利用できるドキュメントにする価値があります。

特にレガシーコードでは、調査した人の頭の中だけに知識を残すと、次の改修で同じ調査を繰り返すことになります。

Claude Codeを使えば、解析結果を機能仕様、技術メモ、調査ログ、未確認事項リストとして整えることができます。

ただし、ドキュメント化するときも、確認済みの事実と推測を混ぜないことが重要です。

機能仕様としてまとめる

機能仕様としてまとめる場合は、利用者視点で何が起きるかを整理します。

入力条件、処理内容、出力結果、エラー時の動き、権限による違いなどをまとめます。

Claude Codeには、「コードから読み取れる範囲で、この機能の仕様を利用者視点で整理してください」と依頼します。

画面やAPIの利用者にとって何が起きるのかを中心に書くと、非エンジニアにも共有しやすくなります。

機能仕様では、内部の関数名よりも、利用者の操作や結果を中心に書くと読みやすくなります。

ただし、確認できていない業務ルールを自然な文章で断定しないように注意します。

技術仕様としてまとめる

技術仕様としてまとめる場合は、開発者が改修時に参照できる情報を残します。

主要ファイル、主要関数、処理順序、依存関係、設定値、DBテーブル、外部連携、注意点を整理します。

Claude Codeには、「開発者向けの技術メモとして、ファイル名と関数名を含めてまとめてください」と依頼すると実用性が上がります。

改修時に見るべき場所がまとまっていると、次回以降の調査時間を減らせます。

技術仕様では、どのファイルを見ればよいか、どの順番で処理が進むか、変更時にどこを確認すべきかが重要です。

後から別の開発者が読むことを考えて、専門用語だけでなく目的や注意点も添えると使いやすくなります。

事実、推測、未確認事項を分ける

Claude Codeで作ったドキュメントでは、事実、推測、未確認事項を必ず分けます。

コードから確認できたことは事実として書けますが、業務上の意図や過去の経緯は推測になることがあります。

「確認できたこと」「推測されること」「追加確認が必要なこと」に分けて出力してもらうと、仕様の誤認を防ぎやすくなります。

未確認事項を残すことは弱点ではなく、将来の調査ポイントを明確にするための重要な作業です。

この分け方をしておくと、レビュー時に「どこまで確認済みか」をすぐ判断できます。

特にAIが作った文章は自然に見えるため、推測まで事実に見えてしまう点に注意が必要です。

リファクタリング前にテストを追加する

レガシーコードを改善する前には、今の挙動を守るためのテストを追加することが重要です。

テストがない状態でリファクタリングすると、見た目はきれいになっても、業務上必要な動作を壊す可能性があります。

Claude Codeは、既存コードからテスト観点を洗い出したり、テストケースの候補を整理したりする場面で役立ちます。

ただし、出されたテストが本当に既存挙動を守れているかは、人間が仕様や実行結果と照合する必要があります。

既存の挙動を保護するテストを考える

まずは、理想の仕様ではなく、現在のコードが実際にしている挙動を保護するテストを考えます。

Claude Codeには、「この処理の既存挙動を保護するために必要なテストケースを挙げてください」と依頼します。

このとき、正常系だけでなく、例外系、空データ、境界値、権限違い、外部API失敗も含めると安全です。

現状の挙動に問題がある場合でも、まずは壊してはいけない部分を明確にすることが大切です。

レガシーコードでは、現在の挙動が理想的ではない場合もあります。

それでも、どの挙動を維持し、どの挙動を後で直すのかを分けないと、リファクタリングと仕様変更が混ざって危険です。

重要な分岐から優先してテストする

レガシーコード全体を一度にテストするのは現実的ではありません。

最初は、改修予定の箇所、障害が起きやすい箇所、条件分岐が多い箇所、売上や認証に関わる箇所から優先します。

Claude Codeには、「リスクが高い順にテスト観点を並べてください」と依頼すると、着手順を決めやすくなります。

テストの目的は、完璧な網羅率をすぐ達成することではなく、安全に変更できる足場を作ることです。

優先度を付けるときは、利用頻度、障害時の影響、金銭や権限への関係、外部連携の有無を基準にすると判断しやすくなります。

Claude Codeに優先度の理由まで出してもらうと、チームで合意しやすくなります。

Claude Codeにテスト観点を出してもらう

Claude Codeは、テストコードそのものだけでなく、テスト観点の洗い出しにも使えます。

入力値のパターン、境界値、異常値、副作用、DB更新、ログ出力、外部連携の失敗などを挙げてもらいます。

「この関数をリファクタリングする前に、守るべき挙動とテスト観点を表で整理してください」と依頼すると、レビューしやすい形になります。

出されたテスト観点は、実際の仕様や過去の障害履歴と照合して取捨選択します。

テスト観点を出してもらうときは、単にケース名だけでなく、入力、期待結果、確認したい理由まで含めると実装に移しやすくなります。

また、テストできない理由がある場合は、その理由もドキュメントとして残しておくと後で役立ちます。

リファクタリング案を出してもらう

解析とテスト準備ができたら、リファクタリング案をClaude Codeに出してもらうことができます。

ただし、レガシーコードでは、すぐに大きく書き換えるよりも、まず方針を比較するほうが安全です。

リファクタリングの目的は、コードを短くすることだけではありません。

今後の変更を安全にし、責務を分かりやすくし、テストしやすい形に近づけることが目的です。

まず方針だけを出してもらう

最初はコード変更ではなく、改善方針だけを出してもらいます。

「責務を分ける案」「重複を減らす案」「条件分岐を整理する案」「命名を改善する案」などを比較します。

Claude Codeには、「挙動を変えない前提で、複数のリファクタリング方針とそれぞれのリスクを出してください」と依頼します。

方針を先に見ることで、チーム内で合意してから実装に進めます。

この段階では、最もきれいな案よりも、最も安全に進められる案を選ぶことが多いです。

特に影響範囲が広いコードでは、理想形へ一気に近づけるより、リスクを抑えながら段階的に改善するほうが現実的です。

小さく分けて変更する

リファクタリングは、小さく分けて進めることが大切です。

一度に大きく書き換えると、どの変更で不具合が入ったのか追いにくくなります。

Claude Codeには、「安全に進めるための小さな変更ステップに分けてください」と依頼します。

たとえば、命名変更、関数抽出、条件分岐整理、テスト追加、重複削除を別々のステップにします。

小さな差分なら、レビューもしやすく、問題が起きたときに戻しやすくなります。

また、小さな変更ごとにテストを実行できれば、どの段階で挙動が変わったかを特定しやすくなります。

Claude Codeには、変更ステップごとに「目的」「影響範囲」「確認すべきテスト」を出してもらうと便利です。

変更前後の差分を確認する

リファクタリング案を適用したら、変更前後の差分を丁寧に確認します。

見た目のコードがきれいになっていても、条件分岐、例外処理、副作用、戻り値が変わっていないかを確認する必要があります。

Claude Codeには、「変更前後で挙動が変わっていないか確認すべきポイントを挙げてください」と依頼できます。

最後はテスト実行とコードレビューで確認し、AIの説明だけで完了にしないことが重要です。

差分確認では、削除された処理、移動された処理、条件式の意味、例外の扱い、ログ出力の有無を重点的に見ます。

リファクタリングのつもりで仕様変更が混ざっていないかを確認することが、レガシーコード改善では特に重要です。

Claude Codeに依頼するときのコツ

Claude Codeの回答の質は、依頼文の具体性で大きく変わります。

レガシーコード解析では、目的、範囲、出力形式、確認してほしい観点を明確にすると、実務で使える回答になりやすいです。

同じコードを読ませても、「説明して」と聞く場合と、「影響範囲を調べたいので、呼び出し元と副作用を整理して」と聞く場合では、得られる回答が変わります。

Claude Codeをうまく使うには、質問を作る段階で自分が何を判断したいのかを言語化することが大切です。

目的、範囲、出力形式を指定する

依頼するときは、まず目的を伝えます。

次に、対象ファイルや対象関数などの範囲を指定します。

最後に、箇条書き、表、手順、技術メモ、仕様書形式など、出力形式を指定します。

たとえば、「このAPIの処理フローを、ファイル名、関数名、注意点の表で整理してください」と依頼すると、後で確認しやすい回答になります。

曖昧に「このコードを説明して」と聞くよりも、確認したい観点を明確にするほうが効果的です。

出力形式を指定しておくと、回答をそのまま調査メモやレビュー資料に転用しやすくなります。

また、「最後に未確認事項をまとめてください」と付け加えると、次の調査に進みやすくなります。

事実と推測を分けてもらう

レガシーコード解析では、Claude Codeに事実と推測を分けてもらうことが重要です。

コードから直接確認できること、コメントから推測できること、外部仕様を確認しないと断定できないことは別物です。

依頼文に「コードから確認できる事実と推測を分けてください」と入れるだけで、レビューしやすさが上がります。

特に仕様書代わりのドキュメントを作る場合は、この分離が欠かせません。

事実と推測が混ざると、後から読んだ人がAIの推測を正式仕様だと誤解する可能性があります。

確認できていないことを未確認として残すほうが、長期的には安全で信頼できるドキュメントになります。

一度に聞きすぎない

大きすぎる依頼は、回答が長くなる一方で、細部が浅くなりやすいです。

最初は全体像、次に対象機能、次に依存関係、最後に関数単位というように分割します。

Claude Codeとのやり取りを調査ログとして残すと、あとでチームメンバーにも共有しやすくなります。

一度の質問で完璧な答えを求めるより、段階的に確認して精度を上げるほうが安全です。

質問を分けると、前回の回答で分かったことを次の質問の前提にできます。

その結果、Claude Codeとのやり取りが単なる一問一答ではなく、調査を進めるための流れになります。

解析結果を鵜呑みにしない

Claude Codeは便利ですが、解析結果をそのまま正解として扱うのは危険です。

レガシーコードでは、古いコメント、例外的な運用、環境依存の挙動、テストに現れていない仕様が残っていることがあります。

AIの回答は、あくまでコードを理解するための補助資料です。

最終的な判断は、実際のコード、実行結果、テスト、ログ、チームの知見を組み合わせて行う必要があります。

コードと実行結果で確認する

Claude Codeの説明が自然でも、実際のコードと合っているかを確認します。

可能であれば、ローカル環境や検証環境で対象機能を実行し、入力に対してどのような出力になるかを確認します。

コードの読み取り結果と実行結果が違う場合は、実行結果を優先して原因を調べます。

AIの説明は理解の助けになりますが、実際に動くシステムの挙動が最終的な判断材料です。

たとえば、コード上は通らなさそうに見える分岐でも、特定のデータや設定で実際には通ることがあります。

逆に、コード上は使われていそうでも、現在の運用では到達しない処理が残っている場合もあります。

テストやログと照らし合わせる

解析結果は、既存テスト、ログ、監視情報、過去の障害記録とも照らし合わせます。

たとえば、Claude Codeが「この分岐は通常使われない」と説明しても、ログを見ると頻繁に通っている可能性があります。

テストがある場合は、そのテストが何を保証しているかも確認します。

ログやテストと照合することで、コードだけでは見えない実運用上の重要性がわかります。

過去の障害記録や問い合わせ履歴がある場合は、それも重要な確認材料になります。

レガシーコードには、過去の不具合を防ぐために残された処理があるため、意味が分からない処理ほど慎重に扱う必要があります。

レビューできる粒度に分ける

解析結果やリファクタリング案は、チームでレビューできる粒度に分けます。

大きなまとめを一度に共有するより、機能単位、ファイル単位、関数単位に分けたほうが確認しやすいです。

Claude Codeに「レビューしやすい単位に分けて要点を整理してください」と依頼すると、共有資料として使いやすくなります。

レビュー可能な粒度にすることで、AIの誤読や人間側の見落としも発見しやすくなります。

また、レビュー対象を小さくすれば、チームメンバーが短時間で確認できます。

レガシーコード改善では、調査結果を一人で抱え込まず、確認できる形にして共有することが品質向上につながります。

実務で使える解析プロンプト集

ここでは、レガシーコード解析でそのまま使いやすい依頼文の例を紹介します。

実際に使うときは、対象のファイル名、関数名、機能名、知りたい観点に合わせて書き換えてください。

プロンプトは長ければよいわけではありません。

目的、対象範囲、出力形式、注意してほしい観点が入っていれば、短い依頼でも十分に実務で使いやすくなります。

全体像を知りたいときのプロンプト

プロジェクト全体を把握したいときは、最初から詳細な実装説明を求めるより、構造の整理を依頼します。

• このプロジェクトのディレクトリ構成をもとに、各フォルダの役割を推測してください。
• 主要な機能、重要そうなファイル、処理の入口になっていそうな箇所を整理してください。
• 確認できる事実と推測を分け、次に調べるべき箇所も挙げてください。

このプロンプトは、引き継ぎ直後や初めて触るコードベースで特に役立ちます。

回答を受け取ったら、挙げられた重要ファイルを順番に確認し、実際の役割と合っているかをチェックします。

処理フローを追いたいときのプロンプト

特定機能の動きを追いたいときは、入口から出力までの順番を指定して依頼します。

• この機能が実行されたときの処理フローを、ファイル名と関数名を含めて順番に説明してください。
• 正常系だけでなく、条件分岐、例外処理、早期return、エラー時の動きも洗い出してください。
• 最後に、改修前に確認すべき注意点をまとめてください。

この依頼では、処理の順番だけでなく、分岐や例外処理まで見てもらうことが重要です。

回答が長くなった場合は、まず正常系だけを確認し、その後に異常系を別質問で深掘りすると整理しやすくなります。

依存関係を調べたいときのプロンプト

影響範囲を知りたいときは、呼び出し関係と外部依存を明示して調べてもらいます。

• この関数の呼び出し元、呼び出し先、参照している設定、更新しているデータを整理してください。
• 変更した場合に影響しそうなファイル、テスト、外部連携を挙げてください。
• 影響が大きい順に、確認すべきポイントを並べてください。

依存関係の調査では、Claude Codeの回答を最終結果にせず、検索やテストで裏取りすることが大切です。

特に動的呼び出しや設定ベースの処理は見落としやすいため、追加で確認する前提にしておきます。

複雑な関数を説明してほしいときのプロンプト

長い関数を読むときは、目的、入力、出力、副作用に分けて説明してもらうと理解しやすくなります。

• この関数の目的を一文で説明してください。
• 入力、出力、副作用、条件分岐、例外処理に分けて整理してください。
• 責務が混ざっている箇所があれば、挙動を変えずに分割できそうな単位を提案してください。

この依頼では、いきなり改善案を求めるのではなく、まず理解のための分解を優先します。

分割案が出た場合も、テストが足りているか、分割しても挙動が変わらないかを確認してから進めます。

テスト観点を出したいときのプロンプト

リファクタリング前には、既存挙動を守るためのテスト観点を出してもらいます。

• この処理をリファクタリングする前に、守るべき既存挙動を洗い出してください。
• 正常系、異常系、境界値、副作用、外部連携失敗の観点でテストケースを提案してください。
• リスクが高い順に優先度を付けてください。

テスト観点のプロンプトでは、優先度を付けてもらうと実務で使いやすくなります。

すべてを一度に実装できない場合でも、リスクが高いところからテストを追加すれば、安全性を少しずつ高められます。

まとめ

Claude Codeは、レガシーコードを短時間で理解しやすくするための強力な補助ツールです。

ただし、AIの説明をそのまま仕様として扱うのではなく、解析、検証、改善の順番を守って使うことが重要です。

特にレガシーコードでは、過去の経緯や業務上の事情がコードに埋もれていることがあります。

Claude Codeを使うことで調査の入口は作れますが、最後の判断は人間が確認しながら進める必要があります。

Claude Codeはレガシーコード理解を助ける道具

Claude Codeは、複雑なコードを整理し、処理フローや依存関係を見える形にするために役立ちます。

仕様書がないコード、担当者がいないシステム、影響範囲がわかりにくい改修でも、調査の入口を作れます。

一方で、業務仕様や本番環境の挙動まで自動で保証するものではありません。

人が理解し、確認し、判断するための道具として使うことが大切です。

Claude Codeを使うほど、コードを読まなくてよくなるわけではありません。

むしろ、どこを読むべきか、何を確認すべきかが明確になり、限られた時間で重要な箇所に集中しやすくなります。

解析、検証、改善の順番を守る

安全に進めるなら、まず全体像を把握し、次に処理フローと依存関係を確認します。

そのうえで、複雑な関数を分解し、ドキュメントを作り、テストで既存挙動を保護します。

リファクタリングは最後に小さく進め、変更前後の差分を必ず確認します。

Claude Codeをうまく使えば、レガシーコードの不安を減らし、改修や引き継ぎを進めやすくできます。

便利だからこそ、過信せず、コード、テスト、ログ、レビューで裏取りすることが大切です。

解析、検証、改善の流れを守れば、Claude Codeはレガシーコード改善の心強い相棒になります。