CLAUDE.mdを使ってコードを10倍速く安全にリファクタリングする

Claude Codeで大規模なコードベースをリファクタリングするのは、Claudeが何も知らない状態でセッションに入ると失敗する。UserServiceが内部的にAuthServiceを呼び出していること、あなたのデータベースがsnake_caseを期待していること、6か月前にReduxからZustandへ移行したことなどを、Claudeは知らない。このコンテキストがなければ、Claudeは新しい抽象化を発明し、あなたが一度も見せていない3つのファイルを静かに壊してしまう。解決策はCLAUDE.md--一度書けば、あらゆるリファクタリングセッションで参照するコンテキストのアンカー文書である。

プロジェクトのルートにCLAUDE.mdというファイルを作成し、次のことを記述しよう：システムの目的を平易な英語で、重要なアーキテクチャ上の決定（どのパターンを使い、なぜそうするのか）、既知の壊れやすい領域や文書化されていない依存関係、コードベースの命名規則、そして制約（例：「UserServiceの名前を変えるな--15のマイクロサービスからインポートされている」）。これがあなたのリファクタリング憲法となる。ClaudeにUserDashboardのリファクタリングを依頼するとき、まずCLAUDE.mdを読み、次にsrc/components/UserDashboard.tsxとそのすべてのインポートを読むよう指示する。たちまちClaudeは、自分が何に触れ、何が壊れうるのかを理解する。

実践的なワークフロー：すべてのセッションを、変更ではなく質問から始めよう。「CLAUDE.mdを読み、次にsrc/services/PaymentProcessor.tsとそれをインポートするすべてのファイルを分析して。これは何をするのか？そのインターフェースを変えたら何が壊れるか？」と伝える。Claudeは完全に情報を得た立場から答える。そして初めて、コードを書く前にリファクタリングの手順を提案するよう依頼する。この「まず読み、次に計画し、一度だけコードを書く」パターンは、デバッグのループを40〜50回からわずか2〜3回の反復に削減する。

開発者たちは、Claudeが600行のReactコンポーネントを、すべてのテストをグリーンに保ちながら10分未満でリファクタリングできると報告している--ただし、正しいコンテキスト構造がある場合に限る。CLAUDE.mdファイルは、1回のリファクタリングセッションでそのコストを回収できる。特に複数のリポジトリを保守するチームにとってはなおさらだ。