Claude Codeでレガシーコードをリファクタリングする2026：実際の手順と詰まりポイント

結論：Claude Codeはリファクタリングの「計画立案」が特に得意

先に結論から書きます。

Claude Codeでリファクタリングをやるとき、最も効果が出るのは「コードの書き換え」より「どう変えるか の計画立案」フェーズです。

「このファイルをクリーンにして」と投げると雑な変更が返ってきます。しかし「このコードの問題点を指摘して、変更計画を段階的に提案して」と聞くと、驚くほど的確な分析が返ってきます。

この記事では、実際にPythonのレガシースクリプト（500行超）をClaude Codeでリファクタリングした経験をベースに、手順と詰まりポイントを解説します。

Step 1：現状分析——問題点をClaude Codeに聞く

まずリファクタリング対象のファイルを開いた状態でClaude Codeに問いかけます。

このファイルの問題点を以下の観点で分析してください：
1. 可読性（命名規則・関数の長さ・ネスト深さ）
2. 保守性（重複コード・ハードコードされた値・グローバル変数）
3. テスタビリティ（純粋関数の割合・副作用の隔離）
4. パフォーマンス（明らかなボトルネックがあれば）

優先度（高・中・低）をつけて箇条書きで出力してください。

実際に返ってきた分析例（500行のWordPress自動投稿スクリプト）：

優先度：高
- run() 関数が300行ある（単一責任原則違反）
- API_KEY がハードコードされている（L47, L89, L134）
- エラーハンドリングがなく、API失敗時にサイレントに続行する

優先度：中
- upload_image() と post_article() が密結合している
- ループ内で同じHTTPセッションを毎回作成している（パフォーマンス）
- 関数名が英日混在している（post_kiji(), send_api() 等）

優先度：低
- マジックナンバーが複数箇所に散在（1280, 720, 0.8 等）
- コメントが古く実装と乖離している

Step 2：変更計画——段階的なマイルストーンを作る

分析結果を踏まえて、変更順序を決めます。

上記の分析を踏まえて、リファクタリングの変更計画を作ってください。

条件：
- 1変更ごとに動作確認できるようにする
- 既存のAPIとの互換性を保つ
- 変更ごとにコミット粒度を提案する

マイルストーン形式で出力してください。

Claude Codeが返した変更計画（一部）：

Milestone 1: 定数の外出し（環境変数化）
- API_KEY, WP_URL 等を .env に移動
- config.py を新設して全設定を集約
- テスト: 既存の動作が変わらないことを確認
- コミット: "refactor: extract config to .env and config.py"

Milestone 2: run() 関数の分割
- run() を upload_media(), create_post(), update_queue() の3関数に分割
- 引数・戻り値を明確にする
- テスト: 各関数を単体テストで検証
- コミット: "refactor: split run() into focused functions"

Milestone 3: エラーハンドリングの追加
...

Step 3：テスト先行——変更前にテストを書く

変更前にテストを書くことで、リファクタリング後の動作確認が機械的にできます。

Milestone 1 を実装する前に、現在の動作を保証するテストを書いてください。

対象関数: upload_image(image_path, title)
テストケース:
- 正常系：有効な画像パスで呼ぶとmedia_idが返る
- 異常系：存在しないパスで呼ぶとValueErrorが出る
- 異常系：API呼び出しが失敗したときにNoneが返る

pytestで書いてください。

Step 4：段階的実装——1マイルストーンずつ進める

マイルストーン1から順番に実装します。各マイルストーンの依頼の仕方：

Milestone 1 を実装してください。

制約：
- config.py の作成と .env への移行のみを行う
- 関数のロジックは一切変えない
- 変更したファイルのみを提示する

「変更したファイルのみを提示する」が重要。 これを言わないと全ファイルを出力されて差分がわかりにくくなります。

実際に詰まったポイントと解決策

詰まり1：Claude Codeが元の動作を変えてしまう

リファクタリングのつもりが機能変更になってしまうケースが頻発します。

対策：

このマイルストーンでは動作を変えないでください。
変えていいのは「構造（関数の分割・名前変更・ファイルの移動）」のみです。
実装が変わってしまう場合は、変更前に確認してください。

詰まり2：大きなファイルをClaude Codeが全部読めない

500行を超えるファイルはコンテキスト制限に当たることがあります。

対策： 関数単位で切り出して個別に依頼する。

このファイルの upload_image() 関数（L45-L89）だけをリファクタリングしてください。

詰まり3：変更のたびに前のコンテキストが消える

長いリファクタリング作業をまたいでセッションが変わると、前の変更履歴が消えます。

対策： CLAUDE.md にリファクタリング進捗を記録する。

# リファクタリング進捗

## 対象ファイル
post_from_md.py（523行）

## 完了したマイルストーン
- [x] M1: config.py の作成（2026-05-20）
- [x] M2: run() 関数の分割（2026-05-21）
- [ ] M3: エラーハンドリングの追加

## 現在の状態
M3 を実装中。upload_image() にtry-exceptを追加済み。
post_article() は未着手。

Claude Codeリファクタリングの効果測定

実際に500行スクリプトをリファクタリングした結果：

作業時間：約8時間（Claude Codeなしで同じことをやると推定20〜30時間）

まとめ

リファクタリングはClaude Codeの得意分野の一つです。ただし「一気に全部変えてもらう」のではなく「小さな変更を積み上げる」アプローチが成功の鍵です。