はじめに
「技術的負債が積み上がっていて、どこから手をつければいいかわからない」
「リファクタリングをしたいけど、既存機能を壊すのが怖い」
「レガシーコードの意図がわからないので触れない」
リファクタリングは必要だと分かっていても、リスクへの恐れから後回しにされがちです。Claude Codeを使えば、コード全体を把握した上で安全な手順でリファクタリングを進められます。
目次
- Claude Codeによるリファクタリングの進め方
- リファクタリング前の安全確認
- コードの問題点を診断させる
- 段階的なリファクタリングの指示パターン
- 関数・クラスのリファクタリング
- アーキテクチャレベルのリファクタリング
- 非推奨・古い記法の一括置き換え
- まとめ
1. Claude Codeによるリファクタリングの進め方
基本原則：小さく・安全に・確認しながら
Claude Codeに一度に大規模なリファクタリングを依頼することは可能ですが、安全性を重視するなら小さな単位に分けて進めることを推奨します。
【推奨しない進め方】
> プロジェクト全体をリファクタリングして
【推奨する進め方】
> まずsrc/utils/以下のファイルの問題点を診断して、
優先度の高い改善から順に一つずつ進めましょうリファクタリングの黄金ルール
リファクタリングの原則は「外から見た動作を変えずに内部構造を改善する」ことです。Claude Codeへの指示にも必ず「既存の動作は維持すること」を含めましょう。
2. リファクタリング前の安全確認
テストカバレッジの確認
> リファクタリングを始める前に、対象ファイルのテストカバレッジを確認してください。
カバレッジが低い場合は、先にテストを追加してからリファクタリングを進める計画を立ててください。Gitでバックアップを取る
git checkout -b refactor/cleanup-utils
git add -A
git commit -m "backup: before refactoring utils"影響範囲の事前調査
> src/utils/dateHelper.jsをリファクタリングする前に、
このファイルをimportしているファイルをすべて列挙してください。
変更の影響範囲を把握したいです。3. コードの問題点を診断させる
全体的な診断
> src/以下のコードを分析して、リファクタリングが必要な箇所を優先度順に
リストアップしてください。
チェック観点：
- 重複コード（DRY原則違反）
- 長すぎる関数（20行超）
- 深すぎるネスト（3段階超）
- 意味不明な変数名・関数名
- デッドコード（使われていないコード）
- 循環的複雑度が高い関数特定ファイルの詳細診断
> src/services/orderService.jsのコード品質を以下の指標で評価してください：
1. 循環的複雑度（10以下が望ましい）
2. 関数の行数（20行以下が望ましい）
3. 引数の数（4つ以下が望ましい）
4. コードの重複率
5. コメントの適切さ
各指標のスコアと改善の優先順位を教えてください。4. 段階的なリファクタリングの指示パターン
ステップ1：命名の改善
> src/utils/helper.jsの変数名・関数名を改善してください。
条件：
- 省略形は使わず意味が伝わる名前にする（例：d → date、fn → callback）
- 動詞で始まる関数名にする（例：userData → getUserData）
- ブール値の変数はis/has/canで始める
- 変更後も既存の機能は完全に維持することステップ2：重複コードの排除
> このコードベースで重複しているロジックを見つけて、
共通の関数・モジュールに切り出してください。
変更後：
- 重複コードをゼロにする
- 切り出した関数には適切なテストを追加する
- 元の動作は完全に維持することステップ3：長い関数の分割
> src/controllers/userController.jsのcreateUser関数が100行あります。
単一責任原則に従って複数の小さな関数に分割してください。
分割の方針：
- 各関数は一つのことだけを行う
- 関数名で何をするかわかるようにする
- 20行以内に収める
- テストは分割後の関数単位で書けるようにするステップ4：ネストの解消
> 以下の関数は3段階以上のネストがあって読みにくいです。
早期リターンパターンを使ってネストを解消してください。
[対象のコードを貼り付け]5. 関数・クラスのリファクタリング
関数の分割
> processOrder()関数が複数の責任を持っています。
注文の検証・在庫確認・決済処理・通知送信を
それぞれ独立した関数に分割してください。クラスの設計改善
> UserManagerクラスが肥大化しています。
Single Responsibility Principleに従って分割してください。
現在の責任：
- ユーザー認証
- プロファイル管理
- 権限管理
- 通知送信
これらを適切に分離した設計を提案してください。条件分岐の整理
> この関数に多数のif-else文があって可読性が低いです。
Strategy パターンまたはポリモーフィズムを使って整理してください。
[対象コードを貼り付け]6. アーキテクチャレベルのリファクタリング
依存関係の整理
> このプロジェクトの依存関係を分析して、循環依存が発生している箇所を
特定してください。解消するためのリファクタリング計画を立ててください。モジュール構造の改善
> 現在のディレクトリ構造を分析して、
より保守しやすい構造を提案してください。
ファイルの移動計画とimportの修正手順も含めてください。APIインターフェースの整理
> 既存のREST APIエンドポイントを分析して、
命名の不統一・不要な冗長性・設計上の問題点を指摘してください。
後方互換性を維持しながら改善するための段階的な計画を立ててください。7. 非推奨・古い記法の一括置き換え
JavaScript ES5→ES6+への移行
> src/以下のJavaScriptファイルをES6+の記法に一括更新してください。
更新内容：
- var → const/let
- function → アロー関数（適切な箇所のみ）
- .then().catch() → async/await
- require() → import文
- 文字列結合 → テンプレートリテラル
各変更後にテストを実行して動作を確認してください。非推奨APIの置き換え
> プロジェクト全体で非推奨（deprecated）となっているAPIの使用箇所を
すべて見つけて、推奨される代替APIに置き換えてください。
変更ごとにテストを実行して動作を確認してください。TypeScript移行
> src/utils/以下のJavaScriptファイルをTypeScriptに移行してください。
方針：
- まず.jsから.tsにリネームする
- 型定義を追加する（anyは使わない）
- tsconfig.jsonに合わせた設定にする
- 型エラーがゼロになるまで修正する
一度にすべてではなく、ファイルごとに順番に進めて
各ステップでビルドが通ることを確認してください。8. まとめ
安全なリファクタリングの原則：
- 必ずGitでバックアップしてから開始する
- テストカバレッジを確認してから進める
- 小さな単位で進めて都度動作確認する
- 「既存の動作は維持すること」を必ず指示に含める
優先順位の高いリファクタリング：
- 重複コードの排除（バグが複数箇所に影響するリスクを減らす）
- 長い関数の分割（可読性と保守性の向上）
- 命名の改善（チーム全体の理解度向上）
- ネストの解消（バグの混入リスクを減らす）
Claude Codeへの効果的な指示：
- 対象の範囲を明確にする
- 改善の観点を具体的に指定する
- 動作確認の手順も含めて依頼する
次回の第16回：ドキュメントを自動生成する方法では、READMEからAPIリファレンスまで、ドキュメントをClaude Codeで自動生成する方法を解説します。
よくある質問（FAQ）
Q. リファクタリング中に既存機能が壊れないか心配です。
A. Claude Codeに「リファクタリング後に既存のテストをすべて実行して、失敗するテストがないか確認してください」と依頼することで、自律的に動作確認を行います。テストカバレッジが低いプロジェクトでは、先にテストを追加することを強く推奨します。
Q. 大規模なリファクタリングはどのくらい時間がかかりますか？
A. プロジェクトの規模や複雑さによりますが、Claude Codeは人間より圧倒的に速く処理します。ただし、安全性のために段階的に進めることで、人間による確認時間が必要になります。
この記事はClaude Code入門シリーズ（第2部）の第15回です。← 第14回：GitHub Actions ｜ 第16回：ドキュメント自動生成 →
ご質問はお問い合わせページからお気軽にどうぞ。
