Claude Codeで既存コードを改善する｜リファクタリング・レビュー

まず「読ませる」──引き継いだコードを理解する

他人が書いたコード、あるいは半年前の自分が書いたコードに向き合う時、最初にやるべきはリファクタリングではなく理解です。この工程こそAIに任せる価値があります。

• 「このプロジェクトの構成を説明して。どこが入口で、どういう流れで動く？」
• 「この機能はどのファイルのどこで実装されている？」
• 「この関数は何のためにある？　どこから呼ばれている？」
• 「この処理を消したら、何が壊れる？」

4つ目が特に効きます。影響範囲の調査は、人間には退屈で見落としやすく、AIには単純な作業です。「たぶん大丈夫」で進めて壊すのが、既存コード修正で最も多い事故なので、ここを機械的に潰せるだけで安全性が変わります。

理解した内容は、その場で/initやCLAUDE.mdに書かせておくと、次回以降の会話が最初から賢くなります。

大規模プロジェクト・モノレポの扱い方

コードベースが大きいと、AIが全部を一度に把握するのは現実的ではありません。利用枠の消費も跳ね上がります。対策は「絞る」ことに尽きます。

1. 対象を明示する──「このリポジトリを直して」ではなく「このディレクトリの、この機能に関わる部分を」と範囲を渡す
2. 調査と実装を分ける──まず「関係するファイルを一覧して」と調べさせ、範囲を確認してから作業に入る
3. サブエージェントに調査を任せる──大きな調査を本体の会話でやると、本題を見失うほど文脈が膨らみます。調査専用のエージェントに投げると会話が汚れません（サブエージェントの解説）
4. モノレポならパッケージ単位で──全体を横断する変更でも、パッケージごとに区切って進める方が結果的に速く、レビューもしやすくなります

安全にリファクタリングする手順

リファクタリングは「動作を変えずに構造を良くする」作業です。つまり「変わっていないこと」を確認できる状態が前提になります。順番が重要です。

1. 先にテストを用意する──テストがないコードのリファクタリングは、壊れたことに気づけません。テストがなければ、リファクタリングより先にテストを書かせてください（次の節）
2. コミットしてから始める──戻れる地点を作ります。gitがあれば、どんな大胆な変更も試せます（Git連携）
3. 1回の変更を1つの目的に絞る──「名前を整理しつつ処理も改善して」と混ぜると、レビューが不可能になります
4. プランモードで計画を確認する──10ファイルを超えそうな変更では、Shift+Tabで計画を先に出させます。ここで範囲の取り違えに気づけます
5. 変更後にテストを走らせる──「テストを実行して、通らなければ直して」まで含めて頼めます

この手順を踏むと、AIに任せられる変更の規模が一段上がります。逆に、この足場がないまま大きく触らせると、「動くように見えるが実は壊れている」という最悪の結果になり得ます。

テストを後から足す

テストのない既存コードにテストを書くのは、面倒な上に頭も使う作業です。AIとの相性は非常に良い領域です。

• まず現状の動作を固定する──「この関数の現在の動作をそのままテストにして」。良い設計かどうかは一旦置いて、いま動いている挙動を記録するのが目的です。これがあればリファクタリングに進めます
• 境界値を出させる──「この処理で問題になりそうな入力を挙げて、それぞれテストにして」。人間が思いつかない条件を拾ってくれます
• カバレッジの薄い場所から──「テストがない、または薄いファイルを一覧して」で優先順位が見えます

注意点を1つ。AIが書いたテストが「通ること」を目的にしてはいけません。実装に合わせただけのテストは、バグごと固定してしまいます。テストの内容が仕様として妥当かは、人が見る必要があります。

コードレビューに使う

レビューには2つの方向があります。

1つ目は、自分の変更を出す前に見てもらう使い方。Claude Code内の /review や「この変更をレビューして」で、公開前に問題を潰せます。人のレビュアーの時間を、機械的に見つかる指摘で消費しないで済むのが大きな利点です。

2つ目は、チームのプルリクエストに自動レビューを組む使い方。GitHub連携を設定すると、PRが開かれるたびに自動でレビューが走り、@メンションで追加の対応も頼めます。設定手順はGitHub連携ページにあります。

ただし現実的な期待値として、AIレビューが強いのは「規約違反・見落とし・境界条件」であって、「この設計はこのチームに合っているか」といった文脈依存の判断ではありません。人のレビューを置き換えるのではなく、人が本質的な議論に集中できるようにする道具です。

レガシーコードとの向き合い方

古い言語、資料のないシステム、書いた人がもういないコード──ここでのAIの価値は、実は「直すこと」より「読めるようにすること」にあります。

• 解説させる──古い書き方や馴染みのない言語でも、何をしているかを日本語で説明させられます。読める人がいないという状態自体が解消します
• ドキュメントを起こさせる──コードから仕様書やコメントを起こさせる。以後の保守コストが変わります
• 移植の下調べに使う──「この処理を別の言語で書くとどうなるか」を出させて、移行の見積もりに使う。ただし一括自動変換に期待しすぎないでください。移植は仕様の再確認とセットの作業です
• 小さく始める──レガシーコードほど、大きく触ると壊れます。テストで固定できる範囲から少しずつ、が結局は最短です