なぜ新しいプロジェクトでClaudeは「迷走」しがちなのか？
Claude CodeやClaude Projectsをリファクタリングによく使う方なら、こんな光景に見覚えがあるはずです。新しいセッションを始めるたびに、AIが「このプロジェクトではどのフレームワークを使っていますか？」や「テストの実行コマンドは何ですか？」といった、当たり前の質問を繰り返します。さらに悪いことに、AIが独自のスタイルでコードを書き始め、チームの共通規約を台無しにしてしまうこともあります。
そんな時は、イライラする代わりに CLAUDE.md を活用しましょう。これは人間向けのドキュメントではなく、AIの思考を方向付けるための設定ファイルです。実際にこのファイルを用意すると、Claudeの理解が格段に早くなり、コーディングスタイルに関する初歩的なミスを最大90%削減できることが分かっています。
README.md と CLAUDE.md の違い
「AIに README.md を読ませればいいのでは？」と思うかもしれません。しかし、その違いは使用目的にあります。
- README.md: 人間向けです。バッジ、華やかな紹介文、環境構築手順などが並んでいます。AIはビルドコマンドを見つけるために、内容の60〜70%を占める不要な情報をフィルタリングしなければならず、トークンの無駄遣いが発生します。
- CLAUDE.md: 技術的な「骨組み」のみを含みます。実行コマンド、ディレクトリ構造、AIが即座に遵守すべき特定のルールに特化しています。
実際の効果の比較
| 項目 | 従来の方法 (README) | モダンな方法 (CLAUDE.md) |
|---|---|---|
| トークン消費量 | 通常 2000トークン以上 | 通常 500トークン未満 |
| 作業開始までのスピード | 理解に2〜3回のやり取りが必要 | 最初のコマンドから即対応 |
| スタイル遵守の精度 | 50/50 (注意が散漫になりやすい) | ほぼ完璧 |
CLAUDE.md を導入する直接的なメリット
小規模から大規模なプロジェクトに適用した結果、2つの重要なポイントが見えてきました。
1つ目はコスト削減です。核となる情報を1つのファイルに集約することで、Claudeがコードベース全体をスキャンする必要がなくなり、入力トークン量を大幅に削減できます。2つ目は振る舞いの制御です。「古いライブラリは絶対に使用しない」「ロジックを修正した後は必ずユニットテストを書く」といったルールをAIに徹底させることができます。
標準的な CLAUDE.md の構成
プロジェクトのルートディレクトリに CLAUDE.md ファイルを作成します。効果的なファイルは、主に以下の3つのセクションで構成されます。
1. 実行コマンド (Build & Development)
デバッグやビルドを依頼した際、Claudeがどのコマンドを実行すべきかを正確に把握できるようにします。
## ビルドと開発
- インストール: `npm install`
- 開発サーバー: `npm run dev`
- ビルド: `npm run build`
- テスト: `npm test`
- リンター: `npm run lint`2. コーディング規約 (Code Style & Patterns)
AIに自由に創造させるのではなく、チームの枠組みに従わせます。例えば、Tailwindを使っている場合は、素のCSSを書くことを禁止します。
## コーディング規約
- すべてのロジックにTypeScriptを使用し、`any`は禁止。
- 関数コンポーネントとHooksを推奨。
- スタイリング: Tailwind CSSのみを使用。インラインスタイルは避ける。
- エラーハンドリング: 非同期処理はtry-catchで囲み、`logger.error()`を使用する。3. 技術スタックと構造
Claudeがストレージ内をかき回すことなく、修正すべきファイルを素早く特定できるようにします。
## 技術スタック
- Next.js 14 (App Router), Prisma, Zustand
## 主要ディレクトリ
- `/src/components/ui`: Shadcnコンポーネント
- `/src/hooks`: カスタムReact Hooks
- `/src/lib`: APIクライアントおよびユーティリティCLAUDE.md を「高級アシスタント」にアップグレードするコツ
このファイルの真の力を引き出すために、以下のテクニックを適用することをお勧めします。
アンチパターンのリストを設定する: 避けてほしいことを明確に記述します。例: 「’any’型の使用を厳禁とする。必要な場合は’unknown’を使用すること」。Claudeは、どんなジュニア開発者よりも真面目にこれに従います。
大きなタスクの後に更新する: ReduxからReact Queryに移行するなど、アーキテクチャを変更した際は、Claudeに「新しい状態管理を反映させるために CLAUDE.md を更新して」と指示してください。これにより、次回のセッションでAIが古い知識に混乱するのを防げます。
Claude Code (CLI) の活用: Anthropicの新しいCLIツールは、起動時にこのファイルを自動的に読み込みます。AIがすでにコンテキストを把握しているため、レスポンス速度が格段に上がるのを実感できるはずです。
以下は、Python/FastAPIプロジェクトの実際の例です：
# FastAPI用 CLAUDE.md
## コマンド
- 開発用: `uvicorn main:app --reload`
- テスト: `pytest`
## 標準規約
- モデルにはPydantic v2を使用。
- すべてのDB操作にAsync/Awaitを使用。
- PEP 8を厳守。まとめ
CLAUDE.md を書くために5分費やすだけで、その後の説明や修正にかかる何時間もの時間を節約できます。これは、優秀なドライバーに地図を渡すようなものです。曲がり角ごとに指示を出す代わりに、座って目的地に到着するのを待つだけで済みます。今のプロジェクトで早速このファイルを作成してみてください。Claudeが驚くほど「賢く」なるのを実感できるはずです！
