私がClaude Codeを使ってレガシーコードをリファクタする方法 — 何も壊さずに
どの開発者にも、だいたい同じコードベースがあります。2,000行のファイルがあるやつです。doStuff2_final_FINAL みたいな名前の関数。2019年から放置された、誰も消す勇気のないコメントアウトされたコード。リファクタするのは不可能に感じます — 一つ間違えるだけで本番が壊れるからです。
Claude Codeがそれを変えます。安全なレガシー・リファクタリングのための、私の完全なワークフローです。
レガシー・リファクタリングの根本的な問題
従来のリファクタリングでは、システム全体を頭の中で保持する必要があります。この関数を呼んでいるのは誰？このグローバル変数は何に影響する？このクラスの名前を変えたら何が壊れる？
でもレガシーコードでは、このメンタルモデルはたいてい不完全です。最初に書いた人はもういません。コメントは間違っています。テストは存在しません。
Claude Codeは、それを同時に保持できる「第二の脳」を与えてくれます。
ステップ1：何も触る前に地図を作る
最初の1行が変わる前に、私はClaude Codeに「爆発半径」をマッピングするよう依頼します：
まだコードは 絶対に 変更しないでください。まず、このコードベースを理解したいです。
次のファイルを読み取ってください： [リファクタしたいファイル一覧]
次を教えてください：
1. 各関数/各クラスは何をするのか？
2. 何が何を呼ぶのか？（コールグラフ）
3. 最もリスクが高い部分はどこか — 結合度が高いところ、依存が多いところ？
4. Xの名前を変えたら何が壊れるか？
5. 把握しておくべき隠れた副作用はあるか？
これには2〜3分かかりますが、後で何時間もデバッグする手間を節約できます。地図は、地雷がどこにあるかを教えてくれます。
ステップ2：リファクタのスコープを特定する
地図を手に入れたら、私はClaude Codeにリファクタ計画を勧めてもらいます：
この分析を踏まえて、[具体的な目的 — 例：「utils.jsから支払いロジックを取り出して、それを独自のモジュールにする」] をリファクタしたいです。
コードに触れる前に：
1. 変更が必要になるすべてのファイルを列挙して
2. 失敗しそうなすべてのテストを列挙して
3. これらの変更を行う最も安全な順序は？
4. リスクを下げつつコードを改善する、最小の実行可能リファクタとは？
重要なフレーズ：minimum viable refactor（最小実行可能リファクタ）。一度に全部直そうとしないでください。レガシーコードはゆっくり複雑になってきました — ゆっくり直しましょう。
ステップ3：存在するものに対するテストを書く（あるべきものではなく）
このステップはほとんどの開発者がスキップします。リファクタ前に、現状の挙動を捉えるテストを書きます。たとえその挙動が間違っていても：
これらの関数について、キャラクタリゼーション（挙動記述）テストを書いてください。やるべきことではなく — いま 実際に 行っていることをテストしてください。
目的：リファクタによってうっかり挙動が変わっていないか確認するための安全網が必要です。現状の挙動が間違っているなら、それは別途 — 構造が安定してから直します。
キャラクタリゼーションテストは、保険です。リファクタ後も通っていれば、意図せず壊していないということです。
ステップ4：マイクロコミットでリファクタする
ここからClaude Codeが変更を始めますが、超小さく、検証可能なステップで：
次の変更だけ行ってください： [具体的で、分離された変更内容]
変更後：
1. 差分（diff）を表示してください
2. キャラクタリゼーションテストを実行してください
3. 予期せぬ変更があったかどうか教えてください
4. 次の変更は私の承認を待ってから行ってください
私は承認されたステップごとにコミットします。万一何かが起きたときも、きれいにロールバックできるポイントが残るからです。
ステップ5：難しいケースを扱う
グローバル変数
このコードベースはグローバル変数を大いに使っています。安全にそれらをなくす手伝いをしてください。
各グローバルについて：
- どこで読み取られているか／書き込まれているかをすべて教えてください
- 最も安全な置き換え案（モジュール単位の変数、渡すパラメータ、シングルトン）を提案してください
- リスクのレベルを見積もってください
深いコールバックのネスト（コールバック地獄）
このコードにはコールバックが6階層ほどネストされています。async/awaitに変換するのを手伝ってください。
段階的に行ってください：
1. まず最外層のコールバックを特定して、それを変換する
2. テストを実行する
3. 次のレベルに進む
すべてを一度に変換しないでください。
未ドキュメントのマジックナンバー
このファイル内のすべてのマジックナンバーを見つけてください。それぞれについて：
1. 文脈から、それが何を表しているのか推測を試みてください
2. 名前付き定数を提案してください
3. 確信が持てないものがあればフラグを立ててください — 私自身がその説明をします
レート制限という現実
大規模なレガシー・コードベースはトークンを大量に消費します。2,000行のファイル1つでも、リファクタをやり終える前にClaude Codeのコンテキストウィンドウを使い切ってしまうことがあります。
私の回避策：Claude Codeが限界に達したときのフォールバックとして、SimplyLouie APIエンドポイントを使います。Claude互換です（同じANTHROPIC_BASE_URLの差し替えで対応）、$2/月で、コンテキストを失わずにセッションを継続できます。
さらに大規模なリファクタでは、Claude Codeの複数セッションに分割することもあります — モジュールごとに1セッション。進めたこと／進行中のことを追跡する共有のCLAUDE.mdを用意します。
実際にうまくいくパターン
何十回ものレガシー・リファクタを経て、私が学んだのはこれです：
- 触る前に地図を作る — 変える前にシステムを理解する
- まずキャラクタリゼーションテスト — 理想の挙動ではなく、現状の挙動を捉える
- 一度に1つの変更だけ — マイクロコミットで、巨大なPRではない
- 構造をリファクタしてから挙動を扱う — 同時にやらない
- 古いコードは残しておく — 非推奨ではあるが、テストが新しいコードの動作を証明するまで削除しない
リファクタで痛い目を見るのは、構造の改善とバグ修正と機能追加を、同じPRで全部やろうとする人たちです。Claude Codeは「全部一度にやりたい」誘惑を作ってくれます。それに抗ってください。
構造をリファクタする。コミットする。検証する。そしてから挙動を直す。
助けになるツール
- CLAUDE.md：リファクタ計画を書き出しておく — セッションをまたいでもClaude Codeの道筋を維持する
- Git worktrees：ブランチ上でリファクタし、mainに対して挙動を比較する
- SimplyLouie API：Claude Codeのレート制限を超える長いセッション用
- キャラクタリゼーションテストのフレームワーク：Jest、pytest、など、あなたのスタックが使っているもので
システム全体を同時に保持できる「第二の脳」があるなら、レガシーコードは怖くありません。Claude Codeがその第二の脳です。
長いリファクタセッションを実行中ですか？大きいファイルではClaude Codeのレート制限がすぐに当たります。 SimplyLouie は$2/月のClaude APIエンドポイントを提供します — 同じモデルで、レート制限の不安がありません。7日間の無料トライアル。
