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

Claude Codeを使うと、古いシステムや複雑化した既存コードの構造、処理の流れ、依存関係、改善ポイントを効率よく把握できます。この記事では、Claude Codeでレガシーコードを解析する基本手順から、実務で使いやすいプロンプト例、リファクタリング前の注意点までをまとめます。

Claude Codeとは

Claude Codeは、Anthropicが提供するAIコーディング支援ツールです。ターミナル上からプロジェクトのコードを読み取り、コードの説明、修正案の作成、テスト追加、リファクタリング、バグ調査などを支援できます。

特にレガシーコードの解析では、ファイル数が多い、設計書が古い、担当者が不在、処理の意図が不明といった問題を整理するのに役立ちます。

Claude Codeは単なるコード補完ツールではなく、プロジェクト全体の文脈を踏まえて質問できる点が特徴です。既存コードを一つずつ読む前に、全体像を把握する用途に向いています。

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

Claude Codeは、次のような場面で効果を発揮します。

古いシステムの処理内容を把握したい場合、Claude Codeに主要なエントリーポイントや重要なファイルを探してもらうことで、調査の入口を見つけやすくなります。

仕様書が存在しない場合でも、コードから処理フローを読み取り、現在の実装ベースで仕様を整理できます。

巨大なクラスや複雑な関数がある場合は、責務の分割、依存関係、危険な変更箇所などを洗い出せます。

また、テストが少ないレガシーコードでは、既存の挙動を壊さないために、どこからテストを追加すべきかを相談できます。

Claude Codeを使う前の準備

Claude Codeでレガシーコードを解析する前に、まず対象プロジェクトをローカル環境に用意します。

Gitで管理されている場合は、必ず作業用ブランチを作成してから解析や修正を進めます。

git checkout -b analyze-legacy-code

次に、依存関係をインストールし、可能であればアプリケーションが起動する状態にしておきます。

Node.jsのプロジェクトであれば、次のように実行します。

npm install
npm run dev

PHPやLaravelの場合は、次のような準備が一般的です。

composer install
cp .env.example .env
php artisan key:generate
php artisan serve

既存のテストがある場合は、解析前に一度実行しておきます。

npm test

またはPHPUnitを使っている場合は、次のように実行します。

vendor/bin/phpunit

この時点のテスト結果を記録しておくと、Claude Codeで修正した後に差分の影響を確認しやすくなります。

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

最初に行うべきことは、コードの細部ではなく全体像の把握です。いきなり個別ファイルを読むよりも、Claude Codeにプロジェクト構成を要約させると効率的です。

Claude Codeを起動したら、次のように依頼します。

このプロジェクト全体の構成を解析してください。
主要なディレクトリ、エントリーポイント、重要な設定ファイル、処理の流れを初心者にも分かるように整理してください。

この依頼により、Claude Codeはディレクトリ構成やフレームワーク、設定ファイル、ルーティング、主要なモジュールを確認し、全体像を整理します。

さらに詳しく調べたい場合は、次のように依頼します。

このプロジェクトで最初に読むべきファイルを優先順位付きで教えてください。
それぞれのファイルが重要な理由も説明してください。

レガシーコードでは、どこから読めばよいか分からないことが多いため、この質問は非常に有効です。

処理フローを解析する

全体構成を把握したら、次に重要な処理フローを調べます。たとえばログイン処理、注文処理、決済処理、データ取り込み処理など、業務上重要な機能から確認します。

次のように依頼すると、Claude Codeが関連ファイルを探しながら流れを整理できます。

ログイン処理の流れを解析してください。
ルーティング、コントローラー、サービス、モデル、データベースアクセスの順に、どのファイルで何が行われているか整理してください。

ECサイトの注文処理であれば、次のように依頼します。

注文作成処理の流れを解析してください。
入力値の受け取り、バリデーション、在庫確認、決済処理、注文保存、メール送信までの流れをコード上から確認してください。

処理フローを調べるときは、Claude Codeの回答をそのまま信じるのではなく、実際のファイル名や関数名を確認しながら進めることが重要です。

レガシーコードでは、使われていない古い処理や、似た名前の関数が複数存在することがあります。Claude Codeには、実際に呼び出されている処理かどうかも確認させると精度が上がります。

この処理で実際に呼び出されている関数だけを対象にしてください。
未使用の古いコードが含まれる場合は、その可能性も指摘してください。

依存関係を洗い出す

レガシーコードの改修で怖いのは、1か所の変更が思わぬ場所に影響することです。そのため、対象機能の依存関係を事前に確認することが大切です。

Claude Codeには次のように依頼します。

このクラスに依存しているファイルを洗い出してください。
直接呼び出している箇所と、間接的に影響を受けそうな箇所を分けて整理してください。

特定の関数を調べる場合は、次のように依頼します。

calculatePrice関数がどこから呼び出されているか調べてください。
呼び出し元ごとに、どのような目的で使われているか整理してください。

このように依存関係を確認することで、修正時の影響範囲を把握できます。

また、削除してよいコードか判断したい場合は、次のように依頼します。

このファイルは現在のアプリケーションで使われていますか。
参照元、ルーティング、テスト、設定ファイルから確認し、削除リスクを評価してください。

不要に見えるコードでも、バッチ処理や外部連携で使われている可能性があります。削除前には必ずGit検索やテスト実行も併用する必要があります。

複雑な関数を読み解く

レガシーコードには、数百行に及ぶ関数や、条件分岐が深くネストした処理がよくあります。このようなコードは、Claude Codeに段階的に分解させると理解しやすくなります。

次のように依頼します。

この関数の処理内容を、上から順番にブロック単位で整理してください。
各ブロックの目的、入力、出力、副作用を説明してください。

さらに、条件分岐を整理したい場合は次のように依頼します。

この関数の条件分岐を表形式で整理してください。
どの条件のときに、どの処理が実行されるかをまとめてください。

副作用を確認する場合は、次の質問が有効です。

この関数が変更している外部状態を洗い出してください。
データベース更新、ファイル出力、メール送信、API通信、グローバル変数の変更を確認してください。

レガシーコードでは、関数名から想像できない副作用が含まれていることがあります。たとえば、価格計算の関数にデータベース更新が含まれていたり、バリデーション処理でログ出力や通知が行われていたりします。

このような副作用を事前に見つけることで、安全にリファクタリングしやすくなります。

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

Claude Codeは、コードから現状仕様をまとめる用途にも使えます。古い仕様書が信頼できない場合は、現在のコードを正としてドキュメント化するのが効果的です。

次のように依頼します。

現在のコードをもとに、この機能の仕様書を作成してください。
入力項目、バリデーション、正常系の処理、異常系の処理、データベース更新内容を整理してください。

API仕様を整理したい場合は、次のように依頼します。

このAPIの仕様をコードから整理してください。
HTTPメソッド、URL、リクエストパラメータ、レスポンス、エラー時の挙動をまとめてください。

バッチ処理であれば、次のように依頼します。

このバッチ処理の仕様を整理してください。
実行タイミング、入力データ、処理内容、出力結果、失敗時の挙動をまとめてください。

作成したドキュメントは、READMEやdocsディレクトリに保存しておくと、次回以降の保守が楽になります。

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

レガシーコードを安全に改善するには、いきなり修正するのではなく、先にテストを追加することが重要です。

Claude Codeには、既存の挙動を確認するテストを作らせることができます。

この関数の現在の挙動を保護するためのテストを作成してください。
正常系、異常系、境界値を含めてください。
ただし、既存の挙動を変えないでください。

テストが書きにくいコードの場合は、次のように相談します。

このコードをテストしやすくするには、どこを最小限変更すればよいですか。
挙動を変えずに依存関係を分離する方法を提案してください。

外部APIやデータベースに強く依存しているコードでは、モック化や依存注入が必要になる場合があります。

ただし、レガシーコードでは一度に大きく設計変更すると危険です。最初は小さなテストを追加し、既存の挙動を固定してから改善するのが安全です。

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

コードの構造や依存関係を理解した後で、Claude Codeにリファクタリング案を出してもらいます。

最初は実装変更ではなく、方針だけを確認するのがおすすめです。

このコードのリファクタリング方針を提案してください。
可読性、責務分離、テスト容易性、影響範囲の観点で整理してください。
まだコードは変更しないでください。

小さく安全に変更したい場合は、次のように依頼します。

既存の挙動を変えずに、この関数を小さな関数へ分割してください。
変更範囲を最小限にし、各変更の理由を説明してください。

大規模な変更を避けたい場合は、次の条件を付けると安全です。

外部仕様は変更しないでください。
関数名と公開メソッドの引数は維持してください。
既存テストが通る範囲で、可読性だけを改善してください。

リファクタリング後は必ずテストを実行します。

npm test

または、対象機能だけを確認できるコマンドがある場合は、それを実行します。

vendor/bin/phpunit tests/Feature/OrderTest.php

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

Claude Codeを使うときは、曖昧な依頼よりも、目的と制約を明確にした依頼のほうが良い結果になりやすいです。

悪い例は次のような依頼です。

このコードをいい感じに直して

この依頼では、何を優先すべきか分かりません。レガシーコードでは、意図しない変更が入る可能性があります。

良い例は次のような依頼です。

既存の挙動を変えずに、可読性を上げる目的でリファクタリングしてください。
変更範囲はこのファイル内に限定してください。
公開メソッドの名前、引数、戻り値は変更しないでください。
変更後に確認すべきテストも教えてください。

解析だけをしたい場合は、変更しないことを明示します。

コードは変更せず、解析だけ行ってください。
この処理の目的、依存関係、リスク、改善候補を整理してください。

バグ調査の場合は、再現条件を含めると精度が上がります。

この画面で特定条件のときだけ合計金額がずれます。
関連しそうな処理を調査し、原因候補を優先順位付きで整理してください。
まだ修正はしないでください。

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

Claude Codeは便利ですが、解析結果が常に正しいとは限りません。特にレガシーコードでは、未使用コード、動的呼び出し、設定ファイル経由の処理、外部システム連携などを見落とす可能性があります。

そのため、Claude Codeの回答は確認の出発点として使うのが安全です。

重要な判断をする前には、次の点を確認します。

実際に該当コードが呼び出されているか。

テストやログで挙動を確認できるか。

本番環境だけで使われる設定がないか。

バッチ、cron、外部API、管理画面などから呼び出されていないか。

Gitの履歴に重要な変更理由が残っていないか。

Claude Codeには、Git履歴を確認する観点も依頼できます。

このファイルの変更履歴を確認し、過去にどのような理由で変更されてきたか整理してください。
重要そうなコミットがあれば教えてください。

ただし、最終的な判断はテスト、ログ、実行確認、レビューを組み合わせて行う必要があります。

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

Claude Codeでレガシーコードを解析するときに使いやすいプロンプトをまとめます。

プロジェクト全体を把握したい場合。

このプロジェクトの全体像を解析してください。
使用技術、主要ディレクトリ、エントリーポイント、重要な処理フローを整理してください。

特定機能を調べたい場合。

ユーザー登録機能の処理フローを解析してください。
ルーティングからデータ保存まで、関連ファイルを順番に整理してください。

影響範囲を調べたい場合。

この関数を変更した場合の影響範囲を調べてください。
呼び出し元、関連テスト、注意すべき副作用を整理してください。

不要コードを調べたい場合。

このファイルが現在使われているか確認してください。
参照元がない場合でも、動的呼び出しや設定ファイル経由の利用可能性を考慮してください。

テストを追加したい場合。

この処理の既存挙動を保護するテストを作成してください。
正常系、異常系、境界値を含めてください。

リファクタリングしたい場合。

既存の挙動を変えずに、このコードの可読性を改善してください。
変更範囲を最小限にし、変更理由を説明してください。

ドキュメント化したい場合。

この機能の仕様をコードからドキュメント化してください。
入力、処理内容、出力、エラー処理、データ更新内容を整理してください。

まとめ

Claude Codeは、レガシーコードの解析に非常に役立つツールです。プロジェクト全体の把握、処理フローの整理、依存関係の洗い出し、複雑な関数の分解、テスト追加、リファクタリング方針の検討まで幅広く活用できます。

ただし、レガシーコードは実装の背景が複雑なことが多く、AIの解析結果だけで判断するのは危険です。Claude Codeで調査の効率を上げつつ、テスト、ログ、Git履歴、実行確認を組み合わせることが重要です。

安全に進める基本は、まず解析だけを行い、影響範囲を確認し、テストを追加してから小さく改善することです。この流れを守ることで、古いコードでも安定性を保ちながら理解と改善を進められます。