はじめに
「このコード、直したいんだけど怖くて触れない」
この感覚の正体は、変更の影響範囲が見えない恐怖だ。テストのないレガシーコードを変更すると何が壊れるかわからない。「今動いているものを触るな」という文化が醸成され、技術的負債が積み上がる。
技術的負債の発見・可視化・経営層への説明は「Claude Code × 技術的負債」記事で扱った。本記事はその次のステップ——実際に安全にコードを直す手法の体系化——に特化する。先にテストを生成し、影響範囲を分析し、段階的な変更計画を立てた上で実行する。「怖いから触れない」をなくすためのアプローチだ。
リファクタリングの「コンテキスト爆発」問題
DEV Communityの記事「Refactoring Agent Skills: From Context Explosion to a Fast, Reliable Workflow」では、Claude Codeでリファクタリングを行う際の根本的な問題が指摘されている。
大規模なリファクタリングを1つのセッションで行うと、ファイル読み込み・変更履歴・エラーメッセージがコンテキストを埋め尽くす。コンテキストが肥大化すると推論精度が低下し、「どこを直したか」を見失い、最終的にセッションが破綻して中途半端な状態で終わる。
解決策は分割・並列・隔離だ。
大きなリファクタリング
↓
独立した単位に分解
↓
サブエージェント × Git Worktreeで並列実行
↓
各ワークツリーでテスト実行 → PR作成
/batch skill（mcpmarket.com）はこのフローを自動化する。コードベースを調査し5〜30個の独立した変更単位に分解、並列ワークツリーで各エージェントが実装・テスト・PR作成まで完結させる。
安全なリファクタリングの5ステップ
ステップ1：特徴化テストで現在の動作を固定する
テストのないレガシーコードをリファクタリングする際の最初の安全策は「現在の動作を固定するテストを先に書く」ことだ。
このUserServiceクラスの現在の動作を網羅する
characterization tests（特徴化テスト）を作成してください。
実装の正しさは問わず、現在の動作がそのまま記録されるテストを書いてください。
変更前・変更後で同じテストが通れば、動作が保持されていることを保証できます。
注意点として、現在の動作にバグが含まれている場合そのバグも「仕様」として固定されてしまう。意図した動作かどうかの確認は別途必要だ。
ステップ2：Plan Modeで段階的計画を立てる
「いきなり全部直す」で何度か痛い目を見てから、小さく積み重ねる計画を先に立てるようになった。
このOrderProcessingモジュールをリファクタリングしたい。
Plan Modeで以下を含む計画書を作成してください：
- 主な問題点（重複コード・長すぎる関数・依存性の問題）と優先度
- 変更による影響範囲
- フェーズ別の実行計画（フェーズ1は最小変更、フェーズ2以降は段階的に大きく）
- 各フェーズで確認すべきテストポイント
ステップ3：Checkpointを活用したロールバック体制
Claude Codeの/rewind機能（Escキー2回）で、ファイル変更をコミットレベルではなくタスクレベルで巻き戻せる。大胆なリファクタリングを試みて失敗しても数秒で元の状態に戻せる安全網があることで、試行錯誤が容易になる。
ステップ4：継続的型チェックで早期エラー検出
Claude Code公式ドキュメントが推奨する実装パターンをリファクタリングにも適用する。
リファクタリングを実施してください。
各フェーズ完了後に型チェック（tsc --noEmit / mypy）を実行して、
型エラーが増えていないことを確認してから次のフェーズに進んでください。
any型や未知の型を使わないでください。
「最後にまとめて確認」ではなく、変更のたびに型チェックを走らせることで問題が小さいうちに検出できる。
ステップ5：別セッションでClaude自身にレビューさせる
このリファクタリングの変更差分について厳しく批判してください。
- 元の実装の意図を変えてしまっていないか
- エッジケースが見落とされていないか
- 新たに技術的負債が生まれていないか
テストが全部通っていても、レビュアーとして問題を指摘してください。
Strangler Figパターン：モノリスを段階的に分解する
Strangler Figパターンとは、レガシーなモノリスを一度に書き直すのではなく機能単位で少しずつモダンな実装に置き換えながら旧実装を「絞め殺す」手法だ（植物のStrangler Figがホスト植物を包み込んでいく様子から名付けられた）。
claudelab.netの実践ガイドでは、Claude CodeでStrangler Figを実装する具体的な手順が紹介されている。
まずClaude Codeに「このモノリスをマイクロサービスに分解する場合、どの境界で切るのが最適か。依存関係を分析して提案して」と依頼する。次にAPIゲートウェイを導入して旧システムへのトラフィックをまず全てゲートウェイ経由にし、決済処理→通知サービス→レポーティングの順にフィーチャー単位で新実装に切り替える。すべての機能が移行したら旧コードを削除する。
Claude Codeは各ステップで影響範囲チェック・移行計画の更新・テスト生成を担当し、人間は「どこを次に移行するか」という判断を行う。
overnight リファクタリング：自律改善ループ
Claude Codeコミュニティで広く知られている「Ralphパターン」（GitHub: frankbria/ralph-claude-code、12,000スター超）を使うと、Claude Codeを完了まで自律的に繰り返し動かすループを実現できる。
リファクタリングに特化させた場合は、QA→バグ修正→リファクタリングの3フェーズを1ラウンドとして繰り返す構成が有効だ。就業後にループを開始して翌朝確認するという運用が可能で、インテリジェントな終了検知・レート制限・サーキットブレーカーを備えている。
ただしレビューなしでの本番マージは禁止。生成された変更を人間が確認してからマージする前提で使う。自律改善ループはステージング環境のコードベースで実行し、レビュー後に本番にマージする。
CLAUDE.mdへの失敗パターン蓄積
リファクタリング中に発生した問題は、都度CLAUDE.mdに記録することで次回の失敗を防ぐ。
「最初からこのリファクタリングがうまくいくにはどんな制約が必要だった？
CLAUDE.mdに追記してください」
「このモジュールは直接変更しない」「この関数はpublic APIなので引数を変えてはいけない」というプロジェクト固有のルールを自動的に学習させていくことで、リファクタリングの失敗率が低下していく。
まとめ
どこから始めるか迷ったら、この順番が取り組みやすい。
ステップ1（1時間）：「過去3ヶ月間で最も頻繁に変更されたファイルのうち、テストカバレッジが低い箇所はどこか。リファクタリング優先度の高い候補を5つリストアップして」とClaude Codeに依頼する。まず対象を特定することから始める。
ステップ2（2〜3時間/モジュール）：特徴化テストを先に生成し、動作が保持されることを確認する安全網を作ってからリファクタリングに入る。この順序を習慣にする。
ステップ3（週次）：/batch skillを使い、CI通過を確認しながら独立した単位のリファクタリングを並列実行する。翌月曜にPRをレビューしてマージする週次サイクルを作る。
「何を直すか」はエンジニアが決める。「安全に実行する」はClaude Codeが担う。この分担が明確になってから、リファクタリングへの心理的ハードルがかなり下がった実感がある。
コメント