コードリファクタリングを安全に進める手順

このワークフローが有効な場面

肥大化したファイルを分割したいとき
重複コードを共通化したいとき
古いAPIを新しいものに移行したいとき
命名を統一したいとき
パフォーマンスを改善したいとき

※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

リファクタリングの鉄則

リファクタリングとは「外部から見た動作を変えずに、内部の構造を改善すること」です。これをClaudeに依頼するときは、この定義をしっかり伝えることが重要です。

※リファクタリング: 外部から見た動作を変えずに、コードの内部構造を整理・改善すること。

ステップバイステップの手順

ステップ1: リファクタリング前にテストを確保する

テストのないコードを変更するのは危険です。まずテストを書きます。

プロンプト例:

「src/services/payment.ts をリファクタリングしたいですが、
まずテストを書いてください（コードは変更しない）。

現在の動作をそのままテストとして記録します。
正しい動作かどうかは関係なく、「現在こう動いている」という事実を記録してください。」

ステップ2: リファクタリング計画を作らせる

いきなり変更させず、計画を立てさせます。

プロンプト例:

「src/services/payment.ts のリファクタリング計画を作ってください。

現状の問題点:
- 1ファイルに500行ある
- 決済処理・メール送信・ログ記録が混在している
- 同じバリデーションロジックが3箇所に重複している

ゴール:
- 単一責任の原則に従って分割
- 重複コードを排除
- テストしやすい設計

【重要】コードはまだ書かないでください。計画だけを出力してください。
変更するファイルの一覧と、各変更の意図を教えてください。」

Claudeの出力例:

リファクタリング計画:

1. src/services/payment/
   ├── index.ts（外部インターフェース、既存コードの互換性維持）
   ├── charge.ts（決済処理のみ）
   ├── notification.ts（メール・通知）
   └── validator.ts（バリデーション共通化）

変更の順序:
1. validator.ts を作成（既存コードから切り出し）
2. テストが通ることを確認
3. charge.ts を作成
4. notification.ts を作成
5. index.ts で統合
6. 既存の payment.ts を削除（互換性を維持しながら）

各ステップで既存のテストが通ることを確認します。

ステップ3: 計画を確認・承認する

計画を人間がレビューして、方向性が正しいか確認します。

「計画を確認しました。以下の点を修正してください:
- payment.ts を直接削除するのではなく、3ヶ月は互換のために残す
- notification.ts のメール送信は src/lib/email.ts に既存のユーティリティがあるので、そちらを使う

修正した計画で、ステップ1（validator.ts の切り出し）から始めてください。」

ステップ4: 段階的に実施する

一度に全部変更させず、1ステップずつ確認しながら進めます。

各ステップ後の確認:

「validator.ts の切り出しが完了しました。
テストを実行して、全て通ることを確認してください。
問題なければ次のステップ（charge.ts）に進んでください。」

# テスト実行
npm run test

# 変更確認
git diff

ステップ5: コミット戦略を決める

リファクタリングのコミットは細かく、意図が伝わるメッセージで。

「各ステップが完了するたびにコミットしてください。
コミットメッセージの例:
- refactor(payment): バリデーションロジックをvalidator.tsに切り出し
- refactor(payment): 決済処理をcharge.tsに分割
- refactor(payment): 通知処理をnotification.tsに分離

コミットは小さく、一つのコミットで一つの変更を原則にしてください。」

※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。※コミット: Gitでファイルの変更を履歴として記録する操作。※npm: Node.jsのパッケージ管理ツール。`npm install` でライブラリをインストールする。

よくあるリファクタリングパターン

パターン1: 大きなファイルを分割する

「src/utils.ts が1000行を超えています。
機能ごとに分割してください。

分割の基準:
- 日付操作: src/utils/date.ts
- 文字列操作: src/utils/string.ts
- バリデーション: src/utils/validation.ts
- API関連: src/utils/api.ts

既存のインポートを全て更新することも含めてください。」

パターン2: 重複コードを共通化する

「以下の3つのファイルに似たようなバリデーションが書かれています:
- src/api/users.ts の validateUserInput
- src/api/profile.ts の validateProfileData
- src/api/settings.ts の validateSettingsInput

共通の src/utils/validation/user-input.ts として切り出してください。
各ファイルはその共通関数を使うように変更してください。」

パターン3: 古いAPI・ライブラリを移行する

「axios を fetch API に移行したいです。

方針:
- 全ての axios.get/post/put/delete を fetch に変換
- エラーハンドリングのパターンも更新
- axiosの型定義も削除
- まず1ファイル（src/api/users.ts）で試して、問題なければ他のファイルも移行

1ファイルの移行から始めてください。」

注意点・よくある失敗

失敗1: 「全部一気にリファクタリングして」

大きすぎる変更はレビューが難しく、バグが混入しても気づきにくくなります。常に小さな単位で進めましょう。

失敗2: テストなしで変更する

「動いているからテストは不要」は危険です。リファクタリング前に必ずテストを書きましょう。

失敗3: リファクタリング中に機能変更を混ぜる

「ついでにここも直したい」は別のPRにしてください。リファクタリングPRはコードレビューが「動作の変化がないこと」を確認するためのものです。機能変更が混ざると確認が難しくなります。