Claude Codeでリファクタリングする方法：プロンプトから大規模移行まで完全解説【2026年最新】
室谷最近、.AI（ドットエーアイ）コミュニティで「Claude Codeでリファクタリングってどうやるの？」という質問が増えてるんですよね。特に既存のプロジェクトを持ち込んで「これをモダンにしたい」という相談が多くて・・・
テキトー教師講座でも同じ流れがあります。「新しいアプリを作る」より「今動いてるコードをどう改善するか」という質問の方が、最近は圧倒的に多くなりました。
レガシーコードを抱えてる企業の担当者さんが増えてきた感じですね。
レガシーコードを抱えてる企業の担当者さんが増えてきた感じですね。
室谷そうなんですよ。僕もXで投稿したんですけど、Paint .NETという数百万ユーザーのWindows画像編集ソフトの開発者が、Claudeでクリップボードコピー処理を95%高速化した話があって。
20年以上のコードを、AIが95%速くしたんですよね。
20年以上のコードを、AIが95%速くしたんですよね。
テキトー教師その話、コミュニティのメンバーさんにも紹介したんですけど、みんな最初は信じなかったです（笑）。「ほんとに？」って。
でも実際のコードのビフォー・アフターを見せたら納得してました。
でも実際のコードのビフォー・アフターを見せたら納得してました。
室谷ここに次のフェーズがあると思ってます。世の中のソフトウェア開発コストの60〜80%は実は「新規開発」じゃない。
既存コードの保守・改善・最適化なんですよね。バグ修正、パフォーマンスチューニング、リファクタリング。
地味に見えるけど、ビジネスインパクトは巨大です。
既存コードの保守・改善・最適化なんですよね。バグ修正、パフォーマンスチューニング、リファクタリング。
地味に見えるけど、ビジネスインパクトは巨大です。
テキトー教師その通りで、Claude Codeの強みは「コードを書ける」ことだけじゃないですよ。「既存のコードベースを理解して、ボトルネックを特定して、改善できる」という点が他のツールとの大きな差だと思います。
室谷今回の記事では、Claude Codeを使ったリファクタリングの基本から、実際に使えるプロンプト集、大規模移行の戦略まで全部まとめます。前回のClaude Codeの基本的な使い方の話から一歩進んで、「既存コードをどう扱うか」を深掘りしていきます。
なぜClaude Codeでリファクタリングが注目されているのか
室谷まず前提として、Claude Codeがリファクタリングに向いている理由を整理しましょうか。普通のAIチャットとは何が違うのか、というところから。
テキトー教師そこが大事ですよね。ChatGPTやGeminiに「このコードをリファクタリングして」と貼り付けるやり方は限界があって。
コードの断片だけ渡しても、プロジェクト全体の構造が見えないから、的外れな提案になりやすいです。
コードの断片だけ渡しても、プロジェクト全体の構造が見えないから、的外れな提案になりやすいです。
室谷Claude Codeの場合、プロジェクトのディレクトリ全体を読めるんですよね。
「このファイルからこのモジュールをインポートしてる」という関係性を把握した上でリファクタリングを提案してくれる。
/add-dirで複数のディレクトリを追加できますし、必要なファイルを自分でたどりながら読んでいく。「このファイルからこのモジュールをインポートしてる」という関係性を把握した上でリファクタリングを提案してくれる。
テキトー教師あと、Claude Codeはコードを読むだけじゃなくてコマンドも実行できますよね。リファクタリング後にテストを実行して、失敗したら自分で修正して、また実行して。
このフィードバックループが人間の手を介さずに回せるのが大きいです。
このフィードバックループが人間の手を介さずに回せるのが大きいです。
室谷公式ドキュメントにも書いてあるんですけど、「Claude Code is an agentic coding environment」という表現をAnthropicが使ってます。ただコードを生成するだけじゃなくて、ファイルを読んで、コマンドを実行して、結果を確認して、修正するというサイクルを自律的に回せる。
これがリファクタリングとの相性が特に良いんです。
これがリファクタリングとの相性が特に良いんです。
テキトー教師整理するとこういう構造ですね。
| 比較項目 | 従来のAIチャット | Claude Code |
|---|---|---|
| コード把握の範囲 | 貼り付けた断片のみ | プロジェクト全体 |
| 実行・確認 | できない（コードを返すだけ） | テスト実行・結果確認が可能 |
| 修正ループ | 毎回人間がコピペ必要 | 自律的に修正→確認を繰り返す |
| 依存関係の把握 | 不可 | インポート関係を追跡可能 |
| コンテキスト保持 | 1セッション内のみ | CLAUDE.mdで永続化可能 |
室谷この表のポイントは「実行・確認」のところで。リファクタリングって変更後に動くかどうかが一番大事じゃないですか。
Claude Codeはテストを自分で実行して確認できるから、「とりあえずきれいになったけど動かなかった」という事態を防げる。
Claude Codeはテストを自分で実行して確認できるから、「とりあえずきれいになったけど動かなかった」という事態を防げる。
テキトー教師ここが実際に教えていて受講生さんがハマるポイントです。「リファクタリングしてもらったのに動かなくなった」という話が多くて。
その原因の多くは「テストがない」か「テストを実行させていない」かのどちらかです。
その原因の多くは「テストがない」か「テストを実行させていない」かのどちらかです。
室谷それ、めちゃくちゃ重要な指摘ですね。Anthropicのベストプラクティスにも「Give Claude a way to verify its work（Claude に自分の作業を確認させる手段を与えろ）」が最初に書かれてます。
テストを書いてから渡す、それだけでリファクタリングの成功率が劇的に変わります。
テストを書いてから渡す、それだけでリファクタリングの成功率が劇的に変わります。
リファクタリングが失敗しやすい理由と対処法
テキトー教師ここは少し踏み込んだ話になりますが、Claude Codeをリファクタリングで使う上で知っておくべき「弱点」があります。正直に言うと、「リファクタリングしてください」という一言で動かすと思ったより失敗するケースがあります。
室谷これ、海外でも議論になってますよね。ある調査では、AIによるリファクタリング試行の60%以上で何らかの機能破壊が発生したというデータがあって・・・。
見た目上は「きれい」でも、意味的には壊れているケースが多い。
見た目上は「きれい」でも、意味的には壊れているケースが多い。
テキトー教師その理由が面白くて。AIがリファクタリングを苦手とするのは「リファクタリングという言葉を知らない」からじゃないんですよ。
問題は3つあります。
問題は3つあります。
- 設計意図を長期的に保持できない
- ステップ間の関係性を安定して維持できない
- プロセス全体をメタ的に管理できない
この3つです。「きれいにして」という抽象的な指示では、何をもって「きれい」とするかの判断基準が伝わらないから、期待とずれた変更が起きる。
室谷コンテキストウィンドウの問題もありますよね。大きいファイルをリファクタリングしようとすると、そのファイルを読むだけでコンテキストを大量消費する。
参照箇所の探索・分割計画の立案だけで文脈が圧迫されて、実際の修正に入る頃には最初の指示を「忘れ」始める。
参照箇所の探索・分割計画の立案だけで文脈が圧迫されて、実際の修正に入る頃には最初の指示を「忘れ」始める。
テキトー教師だから「一括でリファクタリングして」は禁句なんですよ（笑）。大きなファイルを一発で変えようとすると、収束しないループに陥りやすい。
正しいアプローチは「小さなステップに分解して、一つひとつ確認しながら進める」です。これはMartin Fowlerが定義したリファクタリングの本来の考え方とも一致してます。
正しいアプローチは「小さなステップに分解して、一つひとつ確認しながら進める」です。これはMartin Fowlerが定義したリファクタリングの本来の考え方とも一致してます。
室谷MYUUUのエンジニアチームでは、1回のClaude Codeセッションで変更するファイル数を3〜5個以内に収めるようにしてます。それ以上になりそうなら、先にPlan Modeで計画を作らせてから実行に移す。
この使い分けが大事です。
この使い分けが大事です。
テキトー教師そのルール、講座でも紹介したら結構反響がありました。「どこまでを1セッションにするか」の判断基準がなかった人が多くて。
「変更ファイル5個以内」というシンプルなルールは覚えやすいですよね。
「変更ファイル5個以内」というシンプルなルールは覚えやすいですよね。
室谷もう一つ大事なのが、「モジュール設計を先に決める」という考え方です。いきなり「このファイルを分割して」と言うのではなく、「どの責務をどの単位で分離するか」を先にClaude Codeと一緒に決めてから実装に移る。
Spec-Driven Development（SDD）の考え方ですね。
Spec-Driven Development（SDD）の考え方ですね。
テキトー教師整理するとこういう「やりがちなNG行動」と「正しいアプローチ」になります。
| NG（失敗しやすい） | OK（正しいアプローチ） |
|---|---|
| 「このファイルをリファクタリングして」（曖昧） | 「state管理をuseReducerに移行して、テストを実行して確認して」（具体的） |
| 1000行のファイルを一発で変えようとする | 100行単位で分割して順番に変える |
| テストなしで実行させる | テストを先に書いてから渡す |
| 大量のファイルを1セッションで変更 | 1セッション3〜5ファイル以内 |
| 「きれいにして」（基準不明） | 「ESLintエラーをゼロにして」（検証可能な基準） |
室谷この表の最後の行がポイントで。「きれいにして」は主観だから検証できない。
でも「ESLintエラーをゼロにして」「テストカバレッジを80%以上にして」という指示は、Claude Code自身が達成できたかどうかを確認できる。
でも「ESLintエラーをゼロにして」「テストカバレッジを80%以上にして」という指示は、Claude Code自身が達成できたかどうかを確認できる。
テキトー教師それが公式ドキュメントで言う「Give Claude a way to verify its work」の実践ですよ。検証可能な完了条件を設定するだけで、リファクタリングの質が全然変わります。
基本ワークフロー：Claude Codeでリファクタリングする手順
室谷じゃあ、実際にどういう手順でリファクタリングを進めるかを説明しましょう。公式ドキュメントで推奨されているフローがあって、「Explore → Plan → Implement → Commit」の4ステップです。
テキトー教師このフローを守るだけで、失敗の確率がかなり下がりますよね。特に「まず調べてから計画を立てる」という順番が大事で。
いきなり実装に入るのが一番危ない。
いきなり実装に入るのが一番危ない。
室谷ステップごとに具体的なプロンプト例を見ていきましょう。
ステップ1: コードベースの探索（Explore）
室谷まずPlan Modeに入って、コードの状況を把握させます。何も変更させずに読むだけのフェーズです。
# Plan Modeで起動
claude --permission-mode plan
# または実行中にShift+Tabでモード切替
Plan Modeで使うプロンプトの例：
src/auth/ディレクトリを読んで、現在の認証処理の構造を教えてください。
特に以下を確認したいです：
1. セッション管理の仕組み
2. JWT/Cookie の取り扱い
3. 依存関係（どのファイルがこのモジュールを使っているか）
4. 技術的負債になりそうな箇所
このフェーズで「調べる視点を絞る」のが大事なんですよ。「全部読んで」と言うと、無駄にコンテキストを消費します。
「何を確認したいか」を明確にして聞く。
「何を確認したいか」を明確にして聞く。
ステップ2: リファクタリング計画の作成（Plan）
室谷探索が終わったら、次はリファクタリング計画を作らせます。まだPlan Mode のまま。
上記の分析をもとに、認証処理をOAuth2に移行するリファクタリング計画を作成してください。
条件：
- 既存の動作は維持する（後方互換性を保つ）
- 変更は段階的に行う（1ステップで触るファイルは5個以内）
- 各ステップで実行すべきテストコマンドを明記する
計画をMIGRATION_PLAN.mdに出力してください。
計画ファイルを作らせるのが重要なポイントで。MIGRATION_PLAN.mdに書き出しておくことで、次のセッションでも計画を引き継げます。
セッションが切れても作業が止まらない。
セッションが切れても作業が止まらない。
室谷Ctrl+Gを押すとその計画をテキストエディタで開いて編集できるんですよね。「ここは人間が確認してから進める」という判断を入れられる。
この人間のチェックポイントがリファクタリングの安全性を大きく上げます。
この人間のチェックポイントがリファクタリングの安全性を大きく上げます。
ステップ3: 実装（Implement）
室谷計画を確認したら、Normal ModeもしくはAuto Modeに切り替えて実装を実行します。
# Shift+TabでNormal Modeに戻る
# または Auto Mode（自動承認）
claude --permission-mode auto -p "MIGRATION_PLAN.mdのフェーズ1を実行してください。完了後にテストを実行して結果を報告してください。"
ここで「フェーズ1だけ」と限定するのが大事です。「全部やって」と言うと、コンテキストが溢れて途中から品質が落ちます。
フェーズごとに区切って、確認してから次に進む。
フェーズごとに区切って、確認してから次に進む。
室谷MYUUUでも大きなリファクタリングをするときはこのパターンです。朝にPlan Modeで計画を作って確認、午後から各フェーズを順番に実行。
1日1〜2フェーズくらいのペースでやると安全に進められます。
1日1〜2フェーズくらいのペースでやると安全に進められます。
ステップ4: コミット（Commit）
テキトー教師リファクタリングの場合、こまめなコミットが特に重要です。テストが通った状態でコミットを残しておくことで、後で「あのバージョンに戻したい」が簡単にできます。
フェーズ1のリファクタリングが完了し、テストが全て通りました。
以下の内容でコミットしてください：
- コミットメッセージ: refactor: migrate session handling to JWT-based auth (Phase 1)
- 変更点のサマリーをコミットメッセージに含めてください
コミットメッセージの形式を指定するの、地味に大事なんですよね。後でgit logを見返したときに「このコミットは何をやったリファクタリングか」が一目でわかるように。
Plan Mode（計画モード）を使った大規模リファクタリング
テキトー教師ここからはもう少し大きなスケールの話をしましょう。数千行〜数万行のレガシーコードをリファクタリングする場合、Plan Modeの使い方がより重要になります。
室谷公式ドキュメントで「Plan Mode for safe code analysis」という項目があって、特にリファクタリングでの活用が推奨されています。3つの状況で使うのが効果的です。
- Multi-step implementation: 多くのファイルに変更が及ぶ場合
- Code exploration: 変更前にコードベースを徹底的に調査したい場合
- Interactive development: Claude Codeと方向性を確認しながら進めたい場合
テキトー教師Plan Modeの起動方法が3つあって、整理すると以下になります。
# 方法1: 最初からPlan Modeで起動
claude --permission-mode plan
# 方法2: セッション中にShift+TabでPlan Modeに切り替え
# Shift+Tab → Auto-Accept Mode → もう一度Shift+Tab → Plan Mode
# 画面下部に「⏸ plan mode on」と表示される
# 方法3: ヘッドレスモードでPlan Modeを実行（非対話型）
claude --permission-mode plan -p "認証システムを分析して改善案を提案してください"
方法3のヘッドレスモードが地味に便利なんですよ。CI/CDパイプラインに組み込んで「コミットのたびにリファクタリング候補を自動分析」みたいな使い方ができる。
テキトー教師実際の大規模リファクタリングのPlan Modeプロンプト例を見てみましょう。認証システムをOAuth2に移行する例です。
claude --permission-mode plan
認証システムをOAuth2に移行したいと考えています。
現状の確認をお願いします：
1. src/auth/配下の全ファイルを読んで現在の構造を把握する
2. auth関連モジュールを使っているファイルを全て特定する
3. 既存のセッション管理・JWTの実装を分析する
4. テストカバレッジの現状を確認する（npm testを実行）
その後、以下の移行計画を作成してください：
- 段階的な移行フェーズ（各フェーズは独立してデプロイ可能）
- 各フェーズで変更するファイル（最大5ファイル/フェーズ）
- 後方互換性を保つ方法
- ロールバックプラン
計画をdocs/OAUTH2_MIGRATION.mdに出力してください。
「ロールバックプラン」を含めるのが実務では大事で。万が一本番で問題が起きたときに「どうやって元に戻すか」をあらかじめ決めておく。
テキトー教師コミュニティのメンバーさんでも、ロールバックプランなしで本番リファクタリングを実施して大変な思いをした事例を聞いたことがあります。「うまくいくと思っていたのに」というパターンです。
室谷フォローアップ質問で計画を精緻化できるのもPlan Modeの強みで。
後方互換性について、既存のAPIクライアントへの影響を詳しく教えてください。
データベースのスキーマ変更はどのフェーズで行いますか？マイグレーションが必要なら詳細を教えてください。
こういう深掘りをしながら計画を詰めていく。
テキトー教師この「対話しながら計画を作る」というプロセス自体が、リファクタリングの設計を整理する上で価値があるんですよ。AIを使ってるつもりが、実は自分の思考整理になっている。
実践例：レガシーコードをモダンなTypeScriptへ移行する
室谷では実際の例を見ていきましょう。よくあるパターンとして、jQueryとバニラJavaScriptで書かれた古いコードをTypeScript + Reactに移行する場合です。
テキトー教師これは講座でも一番多く聞く相談のパターンで。「動いてるんだけど、触るのが怖い古いJavaScriptがあって」という話です（笑）。
室谷このシナリオでは、Strangler Figパターンを使うのが定番です。「古いコードを一気に捨てない、新しいコードで徐々に置き換えていく」アプローチです。
Phase 1: 現状分析と移行計画
テキトー教師まずはClaude Codeに現状を分析させます。
このレガシープロジェクトを分析してください：
1. 使用技術とバージョン（package.jsonを確認）
2. 主要な機能モジュールの一覧
3. 依存関係（どのファイルが何に依存しているか）
4. TypeScript化の優先度が高い箇所（ビジネスロジックを含む部分）
5. リスクが高い変更箇所（多くのファイルから参照されている箇所）
分析結果をdocs/CURRENT_STATE.mdに出力してください。
この「リスクが高い変更箇所」の特定が重要なんですよ。多くのファイルから参照されているモジュールを先に変えると、影響範囲が広くて大変になる。
リスクの低い末端から攻めていくのが鉄則です。
リスクの低い末端から攻めていくのが鉄則です。
Phase 2: TypeScript環境の追加（既存コードを触らない）
テキトー教師ここが肝心で、最初は既存のJavaScriptを一切変えないです。TypeScriptの環境だけ追加して、新しいコードから書き始める。
既存のJavaScriptコードは変更せずに、TypeScript + Reactの開発環境を追加してください。
要件：
- 既存のjQueryコードは動作を維持する
- webpackで既存JSとTypeScriptを共存させる
- tsconfig.jsonは最初は loose に設定（strict: falseでOK）
- 変更するファイル：package.json、webpack.config.js、tsconfig.json
完了後、npm run buildを実行してビルドが通ることを確認してください。
strict: falseから始めるのはポイントで。最初から厳密にしようとすると、型エラーが大量に出て心が折れます（笑）。まず動かすことが優先です。
テキトー教師徐々にstrictを有効にしていくアプローチはよく使いますね。
小さなステップの積み重ねです。
"strict": falseから始めて、"noImplicitAny": trueだけ有効化して、全部直してから次の設定を有効化する。小さなステップの積み重ねです。
Phase 3: 状態管理のリファクタリング
室谷状態管理はリファクタリングの中でも特に難しいので、Claude Codeに丁寧に説明してあげることが大事です。
legacy/cart.jsのグローバル変数によるカート状態を分析して、
Zustandストアに移行してください。
重要な制約：
1. 既存の window.addToCart、window.updateCartDisplay等のグローバル関数は削除しない
2. 新しいZustandストアは既存のグローバル関数から呼び出される互換レイヤーを持つ
3. 移行後も既存のjQueryコードが動くことを確認する
完了後、既存のカート機能のE2Eテストを実行してください。
テストがなければ、まず最低限のテストを作成してから移行を実施してください。
「互換レイヤー」という概念が重要なんですよ。新旧のコードを並存させるための橋渡しです。
Strangler Figパターンの核心がここにあります。
Strangler Figパターンの核心がここにあります。
室谷全部一気に変えずに「新旧が並存する期間」を設けることで、何か問題が起きたときに古いコードにすぐ戻せる。リスクを最小化しながら進められます。
Claude Codeでリファクタリングに使えるプロンプト集
テキトー教師ここは実用的なプロンプト集です。コピペして使えます。
Claude Codeを使い始めた方から「これどう頼めばいい？」という質問が多いので、そのまま使えるパターンをまとめました。
Claude Codeを使い始めた方から「これどう頼めばいい？」という質問が多いので、そのまま使えるパターンをまとめました。
室谷僕も実務でよく使うパターンをまとめます。
コードの分析・理解
# コードの依存関係の可視化
src/utils/ディレクトリを分析して、各ファイルがどのファイルから
インポートされているか、依存関係のグラフをdocs/dependency-map.mdに出力してください。
循環依存があれば特定して報告してください。
# 技術的負債の特定
プロジェクト全体をスキャンして、以下の問題を特定してください：
- any型の使用箇所（TypeScript）
- 未使用のインポート・変数
- コメントアウトされたコード
- TODO/FIXMEコメント
- 100行を超える関数
結果をtechnical-debt.mdに出力してください。
安全なリファクタリング実行
# 命名の統一
src/ディレクトリ全体で、キャメルケースとスネークケースが混在している
関数名・変数名を特定してください。
統一するための変更計画を作成し、確認後に実行します。
（影響範囲が大きいので計画を先に出してください）
# Promiseからasync/awaitへの変換
src/api/client.jsのPromiseチェーン（.then().catch()）を
async/await構文に変換してください。
変換後、既存のAPIテストを実行して動作確認をしてください：npm test -- src/api/
# コンポーネントの分割
src/components/Dashboard.tsxが500行を超えています。
以下の基準で分割してください：
- 1コンポーネント = 1責務
- 100〜150行を目安
- 分割後も既存のprops/stateのインターフェースは維持する
分割計画を先に提示してください。確認後に実行します。
パフォーマンス最適化
# React再レンダリングの最適化
src/components/ProductList.tsxのパフォーマンスを分析してください。
React.memo、useMemo、useCallbackが効果的な箇所を特定して、
最適化を実施してください。
変更前後でReact DevToolsのプロファイル結果を比較できる形でコメントを残してください。
# バンドルサイズの最適化
webpack-bundle-analyzerを使って現在のバンドルサイズを分析してください：
npm run build:analyze
大きいモジュールのdynamic importへの変換が可能な箇所を特定して、
実装してください。
このプロンプト集の特徴として、全部「完了条件が明確」になってるのがわかりますか？「テストを実行して確認」「計画を先に出して」「結果をファイルに出力」という形で、検証手段が常にセットになってます。
室谷これがClaude Codeを使いこなす上で一番重要なマインドセットだと思ってます。「やって」だけで終わらせない。
「やって、確認して、報告して」というセットで指示する。
「やって、確認して、報告して」というセットで指示する。
サブエージェントで並列リファクタリング
室谷大規模なリファクタリングを効率化する上で、サブエージェントを使った並列処理は知っておくべきテクニックです。
テキトー教師これ、最初に聞いた時は「えっ、AIをAIが動かすの？」ってなりましたけど、実際に使うとめちゃくちゃ便利ですよ（笑）。
室谷具体的には、大きなコードベースを複数のパーツに分けて、Claude Codeが複数のサブエージェントを起動して並列処理する仕組みです。公式ドキュメントの「Fan out across files」に詳しく書かれてます。
テキトー教師例えば2,000ファイルのPythonコードをすべてTypeScriptに変換するような場合、1つのセッションで順番に処理すると何日もかかります。でもサブエージェントで並列化すると。
室谷こういうコマンドで実現できます。
# ファイルリストを生成
find src/ -name "*.py" > python-files.txt
# 各ファイルに対してサブエージェントで並列変換
for file in $(cat python-files.txt); do
claude -p "Migrate $file from Python to TypeScript. Maintain the same functionality. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)" &
done
wait
--allowedToolsフラグで「編集」と「Gitコミット」だけを許可して、それ以外の操作はできないように制限してるのがポイントですね。安全に並列実行できる理由がここにあります。室谷最初は2〜3ファイルで試して、プロンプトを調整してから全体に適用するのが鉄則です。最初から全部走らせると、間違ったパターンで全ファイルが変換されてしまうリスクがある。
テキトー教師--output-format jsonを使うと、結果をJSONで受け取って次の処理につなげられます。失敗したファイルだけ再実行、みたいな自動化もできます。# 結果をJSONで受け取る例
claude -p "Analyze $file for refactoring opportunities" \
--output-format json | python3 process_results.py
よくある失敗パターンと回避策
室谷実際に使っていて見えてきた「やりがちな失敗」をまとめます。これ、海外のClaude Codeコミュニティでも議論になってたポイントで。
テキトー教師「公式ドキュメントにも「Avoid common failure patterns」というセクションがありますよね。それに加えて、リファクタリング特有の失敗パターンもあります。
失敗1: Kitchen Sink Session（なんでも1セッションに詰め込む）
室谷「認証をリファクタリングして、あとついでにDBの接続方法も変えて、あとパフォーマンスも見て」みたいな指示、やりがちなんですよね。
テキトー教師コンテキストが関係ない情報で埋まって、後半になるほど指示を「忘れ」始めます。公式の対処法は
/clearコマンドで関係ない作業の間にコンテキストをリセットすること。失敗2: 修正のループ
室谷Claude Codeが何か間違えて、修正して、まだ間違えて、また修正して、という無限ループ。コンテキストが失敗した試みで埋まっていって、どんどん悪化する。
テキトー教師公式ドキュメントにも「2回連続で修正に失敗したら
/clearして、最初から学んだことを活かした良いプロンプトを書き直す」とあります。粘るより書き直した方が速いです。失敗3: テストなしで実行する
室谷リファクタリングで最も危険なパターンです。テストがない状態で大きな変更をすると、動作が変わっていても気づけない。
テキトー教師だから私は「リファクタリングの前にまずテストを書かせる」を徹底してます。
このコードをリファクタリングする前に、
現在の動作を記録するテストを書いてください。
テストが全てパスすることを確認してから、リファクタリングを開始してください。
このプロンプトの「現在の動作を記録する」という表現がポイントで。テストは「あるべき動作」じゃなくて「今の動作」を記録するものです。
リファクタリング後も同じテストが通れば、挙動が変わっていないことが確認できる。
リファクタリング後も同じテストが通れば、挙動が変わっていないことが確認できる。
失敗4: 過度な探索（Infinite Exploration）
テキトー教師「このプロジェクト全体を分析して」と言うと、Claude Codeが何百ファイルも読んでコンテキストを埋めてしまう。
室谷スコープを絞るか、サブエージェントで探索させてメインのコンテキストを温存するか。「全体を把握したい気持ちはわかるけど、まず触る箇所だけ調べよう」というマインドセットが大事です。
よくある質問（FAQ）
テキトー教師ここからはよくある質問に答えていきます。.AI（ドットエーアイ）コミュニティで実際に聞かれた質問です。
室谷毎回同じ質問が来るので、まとめておきます（笑）。
Q. 本番稼働中のコードをClaude Codeでリファクタリングしても大丈夫ですか？
テキトー教師大丈夫ですが、条件があります。テストがあること、変更をフィーチャーブランチで行うこと、ステージング環境でまず確認すること。
この3点が守られていれば、本番コードのリファクタリングにも使えます。
この3点が守られていれば、本番コードのリファクタリングにも使えます。
室谷逆に「テストがない・ブランチを切っていない・すぐ本番に適用する」という状態でやると、どんなにClaude Codeが優秀でも危険です。これはAIを使うかどうか以前の、ソフトウェア開発の基本の話ですよね。
Q. どのくらいのサイズのファイルまでリファクタリングできますか？
室谷一般論として、1,000行を超えるファイルを1回のセッションで全部リファクタリングしようとすると厳しくなってきます。コンテキストウィンドウの問題があるので。
テキトー教師1ファイルでも大きければ、「この関数だけリファクタリングして」という形でスコープを絞った方が結果の質が上がります。ファイルサイズより「変更のスコープを小さくする」が正しい考え方です。
Q. リファクタリング前後で動作が同じかどうかをどう確認しますか？
テキトー教師一番確実なのはテストです。リファクタリング前にテストを書いて（または既存のテストを確認して）、後でそれを実行して全部通ることを確認する。
室谷テストがない場合でも、「変更前の動作をスクリーンショットで記録させる」「APIのレスポンスをファイルに保存させておく」など、Claude Code自身に証拠を残させる方法があります。
Q. Claude Codeでリファクタリングするのに向いていない場合はありますか？
室谷設計の根本から変えるような「アーキテクチャ変更」は、Claude Codeにすべて任せるのではなく、人間がアーキテクチャを設計した上でClaude Codeに実装させる分担が適切だと思います。
テキトー教師「何をどう変えるか」の判断は人間、「その変更を安全に実装する」のはClaude Codeという役割分担ですね。AIが設計判断まで担うのは、今の段階では過信になることがあります。
まとめ
室谷今回はClaude Codeを使ったリファクタリングについて、基本的な考え方から実践的な手順まで解説しました。まとめると、こういうポイントがあります。
テキトー教師今回の要点を整理します。
- テストを先に書く: リファクタリング前に現在の動作を記録するテストを作成する。これが品質を担保する一番の方法
- スコープを小さく保つ: 1回のセッションで変更するファイルは3〜5個以内。大きなリファクタリングはフェーズに分ける
- Plan Mode → Implement の順番を守る: まず計画を立てて、人間が確認してから実装に移る
- 検証可能な完了条件を設定する: 「きれいにして」ではなく「ESLintエラーをゼロにして」という検証できる条件で指示する
- サブエージェントで並列化: 大規模なマイグレーションは
-pフラグとループで並列処理する
室谷一番伝えたいのは、「リファクタリングは怖くない」ということですよ。テストとPlan Modeを使いこなせば、Claude Codeはレガシーコードを安全にモダン化する最高のパートナーになります。
テキトー教師.AI（ドットエーアイ）コミュニティでも、Claude Codeを使ったリファクタリングの事例が増えてきました。「10年触れなかったコードに初めて手を入れられた」という声も聞きます。
ぜひ小さいところから始めてみてください。
ぜひ小さいところから始めてみてください。
室谷Plan Modeを使いこなすことで、リファクタリングのハードルが大きく下がります。まずは手元の小さなユーティリティ関数から試してみるのをおすすめします。
