📚 この記事は「Claude Code 完全攻略シリーズ」の Episode 17 です。
SES（システムエンジニアリングサービス）の現場で最も頻繁に直面する課題の一つが、レガシーコードの保守と改善です。10年以上前に書かれたコード、ドキュメントが存在しないシステム、テストのないビジネスロジック——こうした技術的負債に日々向き合うエンジニアにとって、Claude Codeは強力な武器になります。
本記事では、Claude Codeを活用してレガシーコードを安全に理解・改善・モダナイズする実践手法を、SES現場で即使えるプロンプト例とともに解説します。
レガシーコードが抱える3つの根本課題
SES現場でレガシーコードに取り組む際、以下の3つが最も大きな障壁となります。
1. コードの理解が困難
ドキュメントが古い、あるいは存在しないケースが大半です。変数名が tmp1、data2 のような命名で、処理の意図を読み取るのに膨大な時間がかかります。
2. テストが存在しない
レガシーコードの多くはテストなしで運用されています。変更を加えたくても「既存の動作を壊さないか」という不安が常につきまといます。
3. 依存関係が複雑に絡み合っている
長年の改修で依存関係がスパゲッティ化し、一箇所の変更が予想外の場所に影響を及ぼすリスクがあります。
Claude Codeは、これら3つの課題すべてに対して実践的な解決策を提供します。
Claude Codeでレガシーコードを読み解く
プロジェクト全体の構造を把握する
レガシーコードに最初に取り組む際、Claude Codeにプロジェクト全体の構造分析を依頼するのが効果的です。
このプロジェクトのディレクトリ構造を分析して、以下を教えてください：
1. 主要なモジュールとその役割
2. エントリポイント（main関数やルーティング定義）
3. データベースアクセス層の場所
4. 設定ファイルの一覧と用途
5. 使われていない可能性のあるファイルClaude Codeはファイルシステムを直接走査するため、IDEで手動で探索するよりも高速に全体像を把握できます。
関数の意図を解読する
命名規則が統一されていない関数の意図を理解するプロンプト例です。
src/core/proc_handler.java の processData() メソッドを分析してください。
- この関数が何をしているか、ビジネスロジックの観点で説明
- 入力と出力の型・制約
- 副作用（DB書き込み、ファイル出力、外部API呼び出しなど）
- 潜在的なバグやエッジケース特にSES現場では、前任者が退場済みで質問相手がいないケースが多いため、Claude Codeが「コードを読める同僚」として機能します。
暗黙の仕様を発見する
レガシーコードには、コードでしか表現されていない暗黙の仕様が多数存在します。
このリポジトリのビジネスロジック層を分析して、
ドキュメント化されていない暗黙のルールを洗い出してください。
特に：
- マジックナンバーの意味
- 条件分岐に隠れた業務ルール
- エラーハンドリングのパターンと例外ケースレガシーコードに安全にテストを追加する
レガシーコードの改善で最も重要なステップは、変更前にテストを追加することです。Michael Feathersの名著『レガシーコード改善ガイド（Working Effectively with Legacy Code）』でも、まずテストで動作を保護してからリファクタリングする手法が推奨されています。
特性テスト（Characterization Test）の自動生成
特性テストとは、「コードが現在どう振る舞うか」を記録するテストです。正しい挙動かどうかは問わず、現状の動作を保護します。
src/billing/calc_fee.py の calc_monthly_fee() について、
特性テスト（Characterization Test）を生成してください。
- 現在の動作をそのまま記録するテスト
- 境界値（0、負数、最大値）のケース
- null/None が渡された場合のケース
- 実際の入出力例をテストケースとして固定Claude Codeはコードの実行パスを分析し、代表的な入力パターンに対するテストケースを網羅的に生成できます。
モック戦略の設計
レガシーコードは外部依存が密結合していることが多く、テストにはモック設計が不可欠です。
src/order/order_service.java のテストを書くために、
外部依存のモック戦略を設計してください。
- DB接続、外部API、ファイルI/Oの依存を特定
- 各依存に対するモック/スタブの実装方針
- テストしやすくするための最小限のリファクタリング提案段階的モダナイゼーション戦略
Strangler Figパターンの適用
レガシーシステムの全面書き換えはリスクが高く、SES現場では現実的ではありません。代わりに、Strangler Figパターンで段階的に新コードへ置き換えていく戦略が有効です。
現在のユーザー認証モジュール（src/auth/）をStrangler Figパターンで
段階的にモダナイズする計画を立ててください。
- Phase 1: 新しいインターフェースの定義
- Phase 2: 新実装の並行稼働
- Phase 3: トラフィック切り替え
- Phase 4: レガシーコードの削除
各フェーズで必要なコード変更とテスト戦略を含めてください。依存関係の分離
Claude Codeの強みは、プロジェクト全体の依存グラフを把握できる点です。
src/core/ 配下のモジュール間の依存関係を分析して、
循環依存を特定してください。
さらに、依存性注入（DI）パターンを使って
結合度を下げるリファクタリング計画を提案してください。型の段階的導入（JavaScript → TypeScript）
SES現場で多い「素のJavaScript」プロジェクトを段階的にTypeScriptへ移行する場合もClaude Codeが活躍します。
src/utils/ ディレクトリのJSファイルをTypeScriptに移行してください。
- まず各関数の引数と戻り値の型を推論して .d.ts を生成
- 次に .js → .ts へのリネームと型注釈の追加
- any の使用は最小限に、具体的な型を可能な限り使用
- 既存のテストが通ることを確認しながら進めてくださいSES現場で使えるレガシーコード改善プロンプト集
コードの棚卸し
このリポジトリのデッドコード（使われていない関数、変数、import）を
洗い出してください。削除しても安全なものと、
動的に参照されている可能性があるものを分けて報告してください。設定ファイルの整理
設定ファイル（.properties, .yaml, .env）を分析して、
以下を特定してください：
- 環境間で異なるべき設定値
- ハードコードされた秘密情報（APIキー、パスワード）
- 未使用の設定項目
- 設定のベストプラクティスからの逸脱ログ改善
このプロジェクトのログ出力を分析して改善してください：
- System.out.println → ロガーへの置き換え
- ログレベルの適切な設定（ERROR/WARN/INFO/DEBUG）
- 構造化ログへの移行提案
- 本番環境で役立つコンテキスト情報の追加エラーハンドリングの統一
プロジェクト全体のエラーハンドリングパターンを分析して、
統一的なエラー処理戦略を提案してください：
- catch(Exception e) の箇所を特定
- 握りつぶされている例外の洗い出し
- カスタム例外クラスの設計
- グローバルエラーハンドラの実装提案CLAUDE.mdでレガシーコード改善ルールを定義する
プロジェクトルートに CLAUDE.md を配置することで、Claude Codeにレガシーコード改善のルールを常に意識させることができます。
# CLAUDE.md - レガシーコード改善ルール
## 原則
- 既存のテストが通る状態を常に維持する
- 変更前に必ず特性テストを追加する
- 一度に変更する範囲を最小限に保つ
- マジックナンバーには定数名とコメントを付与する
## 命名規則
- 新規コードは camelCase を使用
- 既存コードの命名は段階的に修正（同一ファイル内で統一）
## 禁止事項
- テストなしでのビジネスロジック変更
- 複数の責務を持つ関数の追加
- グローバル変数の新規追加CLAUDE.mdの詳しい設定方法については「Claude Code使い方入門」を参照してください。
レガシーコード改善の実践ワークフロー
実際のSES現場での改善ワークフローをまとめます。
Step 1: 現状分析（1-2日）
Claude Codeにプロジェクト全体を分析させ、技術的負債の一覧を作成します。
プロジェクト全体のコード品質レポートを作成してください：
- コード行数とファイル数
- テストカバレッジの概算
- 重複コードの検出
- 複雑度が高い関数のランキング
- セキュリティリスクのある箇所Step 2: 優先順位の決定
ビジネスインパクトとリスクのバランスで改善箇所の優先順位を決めます。変更頻度の高いファイルから着手するのがセオリーです。
Step 3: テスト追加 → リファクタリング → 検証
# 1. 特性テストの追加
src/payment/payment_processor.py の特性テストを書いてください
# 2. リファクタリング（テストが通ることを確認しながら）
payment_processor.py のextract methodリファクタリングを実施してください。
テストを実行して既存の動作が変わっていないことを確認してください。
# 3. 検証
リファクタリング前後でテスト結果が同一であることを確認してくださいStep 4: ドキュメント更新
改善した内容は必ずドキュメント化します。Claude Codeのドキュメント生成機能（詳しくは「Claude Codeでドキュメント自動生成を極める」参照）を活用しましょう。
レガシーコード改善で避けるべきアンチパターン
❌ ビッグバンリライト
全面書き換えは失敗率が極めて高いです。段階的な改善を心がけましょう。
❌ テストなしのリファクタリング
「簡単な変更だから大丈夫」という判断が最も危険です。Claude Codeなら数分でテストを生成できるので、省略する理由がありません。
❌ 過度な抽象化
レガシーコードの改善で陥りがちなのが、過度にDRYにしたり抽象化しすぎることです。「読みやすさ」を最優先にしましょう。
❌ 完璧主義
すべてを一度にきれいにしようとせず、「ボーイスカウトルール」（来た時よりもきれいにして帰る）で少しずつ改善していくのが現実的です。
まとめ：Claude Codeでレガシーコードと向き合う
Claude Codeは、レガシーコードとの戦いにおいて以下の点で特に威力を発揮します。
- コードの理解: プロジェクト全体を俯瞰し、暗黙の仕様を言語化
- テスト生成: 特性テストを高速に自動生成し、安全網を構築
- 段階的改善: Strangler Figパターンなど、リスクを抑えた改善計画の策定
- ドキュメント化: 改善内容の記録とナレッジの蓄積
SES現場でレガシーコードに苦しむエンジニアにとって、Claude Codeは「コードベースを知り尽くした頼れる同僚」です。まずは小さな改善から始めて、技術的負債を着実に減らしていきましょう。
Claude Code 完全攻略シリーズの他の記事もチェック！
- Claude Code使い方入門 — インストールから基本操作まで
- Claude Codeでデバッグを効率化する方法 — エラー解析の実践テクニック
- Claude Codeでの実践的なリファクタリング術 — リファクタリングの基本パターン
- Claude Codeで単体テストを自動生成 — テスト作成の効率化
- Claude Codeでセキュリティ対策を強化する方法 — 脆弱性検出の実践
- Claude Codeでドキュメント自動生成を極める — 仕様書作成の自動化
出典・参考文献
- Anthropic公式 - Claude Code ドキュメント
- Michael C. Feathers『Working Effectively with Legacy Code』（Prentice Hall, 2004）
- Martin Fowler『Refactoring: Improving the Design of Existing Code』（Addison-Wesley, 2018）
- Martin Fowler - StranglerFigApplication
