Claude でリファクタリング｜コードを 50% 削減した実践例と手順
コードリファクタリングは「あとで直す」と後回しにしがちな作業ですが、後から手を付けるほど複雑度が積み重なり工数がかさむのが実態です。Claude を使うと、210 行・循環複雑度 16 の Python 関数を 30 行以下・複雑度 3〜6 まで削減しながら、従来作業の約 50% の工数で完了できることが実証されています。本記事では、その具体的な手順・プロンプト設計・失敗パターンを整理します。
Claude でのリファクタリングは 「ドキュメント生成→テスト先行→簡潔化→レビュー」の流れ が基本です。210 行のコードを 30 行未満へ削減した実例では、循環複雑度 16 が 3〜6 まで落ち、工数は推定 210 分から 110 分へ短縮されました。コード目的の理解と検証が時間的ボトルネックになるため、セキュリティ評価と単体テストを先に整備しておくことが最短ルートです。
Claude Code の専用セットアップとして、リファクタリング専用の CLAUDE.md に「一度に 1 つの変更のみ行う」「テストが通過してから次のステップへ」などの制約を記述しておくと、過剰な変更を防ぎ退行リスクを最小化できます。
目次 (13)
- Claude でリファクタリングができる — 実証された数値から始める
- Claude がコードリファクタリングに向いている理由
- 実証事例: Python 210 行→30 行の削減プロセス
- Claude Code でリファクタリングを進める 5 ステップ手順
- ステップ 1: 対象コードの構造把握
- ステップ 2: 既存挙動を凍結するテストを作成
- ステップ 3: 簡潔化の方針を複数案で確認する
- ステップ 4: 段階的に変更を実施する
- ステップ 5: 最終レビューを依頼する
- ケース別プロンプト設計
- Claude Code リファクタリング専用セットアップ
- よくある失敗パターンと対処法
- まとめ — Claude リファクタリングのコスト対効果
Claude でリファクタリングができる — 実証された数値から始める
「Claude はコードを生成するものであって、既存コードを整理するのは苦手」という思い込みがあります。しかし実際の事例では、単一の Python 関数に対して Claude を活用したリファクタリングで以下の結果が得られています(Refactoring with Claude — Medium)。
| 指標 | リファクタリング前 | リファクタリング後 |
|---|---|---|
| コード行数 | 210 行 | 30 行未満 |
| 循環複雑度 | 16 | 3〜6 |
| 所要時間 | 推定 210 分 | 実測 110 分 |
| 削減率 | — | 約 50% |
循環複雑度とは、コード内の独立した実行パスの数を示す指標で、値が高いほどテストが困難でバグが潜みやすい状態です。16 は「高複雑度」の分類に入り、3〜6 への削減はコードを保守可能な状態に整えるうえで大きな改善にあたります。
新規コードを書くより既存コードの読解と整理に多くの時間が取られる作業ほど、Claude の活用効果は大きく出ます。
Claude がコードリファクタリングに向いている理由
Claude がリファクタリングを得意とする背景には、次の 3 つの能力があります。
コードの意図を把握する読解力
Claude はコンテキストウィンドウに大きなコードベースを読み込ませると、変数の命名・処理の流れ・依存関係を解析し、「このコードが何をしているか」を自然言語で説明できます。人間が長時間かけて行う構造把握を短時間で実行できるのは、リファクタリングの初期フェーズで大きなアドバンテージです。
複数の簡潔化案を同時に提示できる
「このコードを短く書き直すオプションを 3 案出してください」と指示すると、アプローチが異なる複数の候補を並べて返します。開発者はトレードオフを比較したうえで採用案を選べるため、最適解への到達が早まります。
単体テストの自動生成
リファクタリング前に現行の挙動をカバーするテストを生成させることで、変更後の退行を機械的に検出できます。「テストを先に書く→変更する→テストを通す」のサイクルを Claude が補助することで、品質を担保しながら高速に進められます。
実証事例: Python 210 行→30 行の削減プロセス
Medium に掲載された事例(Refactoring with Claude)では、210 行・循環複雑度 16 の Python 関数を Claude に渡し、14 段階のプロセスでリファクタリングが完了しています。
- セキュリティ評価 — コードに脆弱性が含まれていないか確認する
- ドキュメント生成 — 関数の仕様と目的を Claude に自然言語で出力させる
- ドキュメント検証・修正 — 出力された説明を開発者が確認し補正する
- 単体テスト生成 — 現行の挙動を凍結するテストを作成する
- テスト修正 — 自動生成テストのエラーをデバッグする
- 簡潔化案の提示 — 「短く書き直すオプションを複数案出してほしい」と依頼する
- テスト実行 — 提示された案にテストを適用する
- デバッグ — テストが通らない箇所を修正する
- テストカバレッジ向上 — カバレッジが不十分な部分を追加でカバーする
- コード再修正 — テスト実行後に残った問題を解消する
- コードレビュー — Claude に最終的なコードレビューを依頼する
- 結果確認 — 行数・複雑度・テスト通過を確認する
- クリーンアップ — 不要なコメントや中間変数を整理する
- 完了 — 本番コードへの反映
著者は「コード目的の理解とコード検証が時間的ボトルネック」と分析しており、この 2 点に人間が時間をかけることで Claude の出力品質が安定します。完全自動化ではなく、人間が方向を決め Claude が実行するハイブリッドモデルが実際の推奨動作です。
Claude Code でリファクタリングを進める 5 ステップ手順
Claude Code を使う場合は、以下の順で進めると退行リスクを抑えられます。
ステップ 1: 対象コードの構造把握
まず Claude Code に対象ファイルを読み込ませ、機能の一覧と依存関係を出力させます。
このファイルの主要な関数をリストアップし、各関数の役割と
呼び出し関係を説明してください。
ステップ 2: 既存挙動を凍結するテストを作成
変更前に現行挙動をカバーするテストを生成させます。テストが通過する状態を「変更前のベースライン」として記録します。
このコードの現在の挙動を網羅する単体テストを書いてください。
既存の動作を変えずに保護することを目的としています。
ステップ 3: 簡潔化の方針を複数案で確認する
Claude に「どう改善できるか」を複数案で出させ、方針を決定します。
以下の観点でこのコードを改善するオプションを 3 案出してください:
- 行数の削減
- 循環複雑度の低下
- 可読性の向上
ステップ 4: 段階的に変更を実施する
承認した案を 1 コミット 1 変更で実装します。大きな変更を一度に行わず、テストを通してから次の変更へ進みます。
ステップ 5: 最終レビューを依頼する
すべての変更が完了したら、Claude にコードレビューを依頼して残課題がないか確認します。
リファクタリング後のコードを確認し、改善点や潜在的な問題があれば
指摘してください。
ケース別プロンプト設計
リファクタリングの目的によって、Claude への指示の書き方を変えると出力の精度が上がります。
行数削減を最優先にする場合
このコードを機能を変えずに最も短く書き直してください。
Python の組み込み関数・内包表記・ライブラリを積極的に使用してください。
可読性向上を最優先にする場合
このコードを読みやすく書き直してください。
変数名・関数名の改善、コメントの追加、処理の分割を行ってください。
行数が増えても構いません。
複雑度の低下を最優先にする場合
このコードの循環複雑度を下げてください。
ネストを減らし、早期リターンやガード節を使い、条件分岐を簡略化してください。
複数の目標を同時に指定すると折衷案が返ってくる傾向があるため、1 回の指示では 1 つの目標に絞る方が出力の質が安定します。
Claude Code リファクタリング専用セットアップ
Claude Directory が 2026 年 5 月に公開した「リファクタリング用途の Claude Code ベスト設定」(Best Claude Code setups for refactoring — Claude Directory)では、プロジェクトの CLAUDE.md に制約を明記しておくことが推奨されています。
# リファクタリング規則
- 一度に 1 つの論理的変更のみ行う
- すべてのテストが通過してから次の変更に進む
- 関数の外部インターフェース(引数・返却値・例外)は変えない
- 変更の意図を各コミットメッセージに明記する
- 不明な点は変更せず、コメントで問いを残す
また、GitHub の awesome-claude-code-subagents リポジトリ(refactoring-specialist.md)には、リファクタリング専門の設定定義が公開されており、開発者体験を自動化するためのプロンプト設定が収録されています。これを参考に自分のプロジェクト用の CLAUDE.md を構成すると、Claude Code のリファクタリング出力が一貫したスタイルに揃います。
よくある失敗パターンと対処法
Claude でリファクタリングを進める際に発生しやすい問題を整理します。
テストなしで大きな変更を一括依頼する
Claude に「このファイル全体をリファクタリングして」と依頼すると、大量の変更が一度に返ってきて退行の特定が困難になります。対処としては、まず対象範囲を 1 関数・1 クラスに絞り、テストを作成してから変更を依頼します。
出力コードをレビューせずにそのまま使う
Claude の出力は構文的に正しくても、ビジネスロジックの細部が変わることがあります。特に条件分岐の順序変更・例外処理の簡略化には注意が必要で、変更前後の差分を必ず人間がレビューします。
目的を指定せずに依頼する
「きれいにして」「改善して」のような抽象的な指示は、どの方向に最適化すべきか判断しにくくなります。「行数削減」「複雑度低下」「可読性向上」のいずれを優先するかを明示すると出力が安定します。
1 回の指示で複数の目標を指定する
行数削減と可読性向上を同時に求めると、トレードオフの折衷案が出がちです。目的を 1 つずつ順番に指示し、各段階でテストを通すサイクルを維持します。
まとめ — Claude リファクタリングのコスト対効果
Claude でのリファクタリングは「完全自動化」ではなく、人間が方向を決め Claude が実行する役割分担が効果を最大化します。実証された数値として、210 行・複雑度 16 のコードが 30 行未満・複雑度 3〜6 まで削減され、工数は約 50% 短縮されました(Refactoring with Claude — Medium)。
コスト対効果が最大になるのは、「読解に多くの時間が取られる既存コード」に対してです。新規コードの生成より、複雑に絡み合った既存コードの整理こそが Claude の真価を発揮する場面です。
まずは 1 つの関数から試し、テストを先に作ってから変更するサイクルを身につけることが、Claude リファクタリングの最短ルートです。
