Claude Code をはじめとするコーディング AI は、局所的な実装生成において高い能力を示す一方で、「リファクタリング」という作業になると途端に扱いづらくなる。
これは単なる精度の問題ではなく、ソフトウェア設計思想・プロセス理解・コンテキスト制約が複合的に絡み合った構造的な問題である。
1. Claude Code でコードを書く前に必ず確認すべきこと
Claude Code に実装を依頼する前に、必ず確認すべき点がある。
それは プログラムのモジュール設計が事前に定義されているか という点である。
モジュール設計とは、
- どの責務を
- どの単位で
- どの境界に分離するか
を事前に決めることであり、単に「ファイルを分ける」ことではない。
しかし、この前提を置かずに Claude Code に実装を任せると、次のような事態が起きやすい。
- 単一ファイルに処理が集中する
- 状態管理・副作用・I/O が混在する
- 意図しない密結合が発生する
結果として、巨大で修正困難なファイルが生成される。
問題は、ここからである。
2. 「あとからリファクタリングすればよい」が通用しない理由
巨大化したファイルを前にして、人間であれば次のように考える。
長すぎるので、責務ごとに分割しよう
共通処理を切り出そう
状態管理を整理しよう
しかし Claude Code に対して、
このファイルを適切な粒度に分割してほしい
と指示した場合、期待通りには進まないことが多い。
- 分割対象ファイル自体がコンテキストを大量消費する
- 参照箇所の探索・分割計画立案だけで、すでに文脈が圧迫される
- 状態管理が絡む Web アプリでは、影響範囲の把握が難しい
- 修正後の動作確認・修正で、さらにコンテキストが消費される
その結果、
- 計画と異なる修正
- 動作不整合
- 会話継続によるコンテキスト圧縮（コンパクティング）
が重なり、収束しないループに陥る。
最初に「長大なファイルを生成する」という判断を誤った時点で、そのコードは 動かない岩として技術的負債化しやすい。
これは主観ではない：AI リファクタリング失敗の定量的証拠
この「リファクタリングが破綻しやすい」という感覚は、個人の体験談では終わらない。
実際に、AI による自動リファクタリングの失敗率を定量的に示した調査が存在する。
CodeSceneの示す現実
Refactoring vs Refuctoring では、
複数の LLM によるリファクタリング結果を評価した結果として、次の事実が示されている。
- AI によるリファクタリング試行の 約 60% 以上で機能破壊が発生
- 外部仕様を保ったまま内部構造を改善できたケースは少数
- 見た目上は「きれい」でも、意味的には壊れている例が多い
ここで重要なのは、AI がリファクタリングというタスクを「構造保存付き変換」として安定して扱えていないという点である。
つまり、
Claude Code にリファクタリングさせると、元どおりに動かないことが多い
という現象は、経験則ではなく、再現性のある問題である。
学術的にも「完全自動リファクタリングは困難」と言われている
LLM-Driven Code Refactoring: Opportunities and Limitations では、LLM を用いたリファクタリングについて、次のように整理している。
- 単純な構文変換や局所改善は一定程度可能
- しかし、状態管理、文脈依存ロジック、アーキテクチャ上の意図を含むリファクタリングでは誤変更が頻発
- 結果として、人間による検証なしの完全自動化は現実的でない
ここで注目すべきなのは、「LLM はコードは読めるが、設計意図を保持し続けられない」 という点である。
3. リファクタリングとは、本来どのような行為か
リファクタリングは、場当たり的な「整理」ではない。
古典的には Refactoring において、次のような前提が共有されている。
- 外部仕様を変えずに内部構造を改善する
- 小さなステップを積み重ねる
- 常に動作確認（テスト）を挟む
実務的には、以下のようなプロセスになる。
- 既存コードが正しく動くテストを用意する
- 共通処理・状態管理を切り出す
- テストを実行し、挙動を確認する
- 複雑な処理を小さなメソッドに分解する
- テストを実行する
- 適切な粒度でファイルを分割する
- 再度テストを実行する
これは 段階的・反復的な設計作業であり、一括変換ではない。
4. LLM がリファクタリングを苦手とする本質的理由
Claude Code がリファクタリングを苦手とするのは、「リファクタリングという言葉を知らない」からではない。
問題は、次の点にある。
- 設計意図を長期的に保持できない
- ステップ間の関係性を安定して維持できない
- プロセス全体をメタ的に管理できない
つまり、思想としてのリファクタリングはあっても、実行可能なアクションプランに落とせない。
さらに、途中でテストが失敗した場合、
- 修正対応でコンテキストを消費する
- 本来の次ステップを忘却する
という事態も起こりやすい。
この構造を理解せずに、
リファクタして
きれいにして
といった抽象指示を与えても、安定した結果にはなりにくい。
5. 解決策は「事前設計」と「SDD」にある
以上を踏まえると、現実的な対応策は明確である。
実装を始める前に、モジュール設計を明示的に書かせること
そして、それを人間が確認した上で実装に進むことである。
これは、Spec-Driven Development（SDD） の考え方と一致する。
- 先に仕様・責務・境界を書く
- 実装は仕様の具体化として行う
- 後から構造を直す前提を置かない
Next.js を例に取れば、
- 状態管理の責務はどこに置くか
- Server / Client Component の境界
- API ルートとドメインロジックの分離
- UI とビジネスロジックの分割単位
といった点を 実装前に言語化させることが重要になる。
6. 「リファクタリングをさせる」のではなく「させない設計」をする
結論として、Claude Code を用いた開発においては、
- 後からリファクタリングさせる
- 巨大なファイルを分割させる
という発想自体を抑制した方がよい。
代わりに、
- 最初から壊れにくい構造を定義する
- 実装はその仕様に従わせる
- リファクタリングを必要としない初期設計を行う
この姿勢が、現実的な開発戦略である。