CLAUDE.md Deep Dive
初心者向けHow to write the perfect project config file
CLAUDE.md って何?（超基本）
たとえ話で理解する
📝 「引き継ぎメモ」を渡しますよね?
• 「うちではこのツールを使います」
• 「このフォルダにファイルを置いてね」
• 「報告書はこのフォーマットで」
CLAUDE.md はまさにこの「引き継ぎメモ」です。Claude Code は毎回セッション開始時にこのファイルを読んで、あなたのプロジェクトのルールを理解します。
技術的にはどういうもの?
- プロジェクトのルートフォルダ（一番上の階層）に置く テキストファイル（拡張子は .md = Markdown形式。見出しや箇条書きが使える書き方）
- Claude Code が 毎回自動的に読む（手動で指定する必要なし）
- 中身はプロジェクトのルール、コマンド、構成などを書く
/initコマンドで自動生成できる
なぜ重要なの?
❌ CLAUDE.md がない場合
あなた: テストを実行して Claude: pytest? jest? それとも...? (テストの方法がわからない)
✅ CLAUDE.md がある場合
あなた: テストを実行して Claude: npm test を実行します。 ✅ 全テスト通過！
作り方
方法1: 自動生成（おすすめ）
> /initClaude がプロジェクトを分析して適切な CLAUDE.md を自動生成します。
方法2: 手動で作る
プロジェクトのルートフォルダに CLAUDE.md というファイルを作り、以下のテンプレートを参考に書きます。
初心者向けテンプレート
# プロジェクト概要 [このプロジェクトが何をするものか、1〜2行で] # 技術スタック - 言語: [Python / JavaScript / TypeScript 等] - フレームワーク: [React / FastAPI / Django 等] - データベース: [PostgreSQL / SQLite 等] # よく使うコマンド - 起動: [npm start / python main.py 等] - テスト: [npm test / pytest 等] - ビルド: [npm run build 等] # コーディングルール - [ルール1] - [ルール2] - [ルール3] # ディレクトリ構成 src/ # ソースコード tests/ # テストファイル docs/ # ドキュメント
実践的な例: EC サイトのバックエンド
# プロジェクト概要 ECサイトのバックエンドAPI。 # 技術スタック - Python 3.12 + FastAPI - PostgreSQL 16 + SQLAlchemy # コマンド - 起動: uvicorn app.main:app --reload - テスト: pytest tests/ -v - リント: ruff check app/ # コーディングルール - 型ヒントを必ず付ける - APIレスポンスは snake_case - テストカバレッジ 80% 以上 # ディレクトリ構成 app/ api/ # エンドポイント models/ # DB モデル services/ # ビジネスロジック
やるべきこと・やってはいけないこと
| ✅ やるべき | ❌ やらない |
|---|---|
| 100〜200行に収める | 500行以上の長大なファイル |
| /init で雛形を作ってから編集 | ゼロから手書きで完璧を目指す |
| よく使うコマンドを書く | コードの詳細な解説を書く |
| チームのコーディング規約を書く | リンターのルールを書く（ESLint等のツールに任せる） |
| 詳細は別ファイルに分離 | すべてを1つに詰め込む |
| チームで Git 管理して共有する | 個人メモや TODO リストを書く |
なぜ短くすべき?
• Claude は約 150〜200個の指示を確実に守れる
• Claude Code のシステムプロンプト自体が約50命令を使用している
• 残り約100〜150命令分が CLAUDE.md の実質的な上限
• Cherny 氏自身の CLAUDE.md は約100行
指示が多すぎると、重要なルールが無視される可能性があります。
my-project/
CLAUDE.md ← プロジェクト全体のルール
frontend/
CLAUDE.md ← フロントエンド固有
backend/
CLAUDE.md ← バックエンド固有
docs/
architecture.md ← 詳細は別ファイルに分離Claude Code は現在の作業ディレクトリから親ディレクトリに向かって、すべての CLAUDE.md を自動的に読み込みます。
別ファイルへの参照方法
# CLAUDE.md の中で: アーキテクチャの詳細は docs/architecture.md を参照してください。 APIの設計方針は docs/api-guidelines.md に記載しています。
これにより、CLAUDE.md 本体を短く保ちながら、必要な情報を全て参照させることができます。
CLAUDE.md にコーディング規約を組み込む
CLAUDE.md にコーディング規約（コードの書き方のルール）を書くことで、Claude が生成するコードの品質と一貫性を高められます。ただし、何でもCLAUDE.mdに書けばいいわけではありません。リンター（コードのルール違反を自動検出するツール）に任せられるルールと、CLAUDE.md に書くべきルールの使い分けが重要です。
たとえると
リンターに任せるべきルール vs CLAUDE.md に書くべきルール
| リンター（Biome等）に任せる | CLAUDE.md に書く |
|---|---|
| インデント（字下げ）のスペース数 | 「関数の引数が2個以上なら、オブジェクト形式にする」という設計方針 |
| セミコロンの有無 | 「エラーハンドリングは必ずカスタムエラークラスを使う」 |
| import文の並び順 | 「データベースアクセスは必ずリポジトリパターンで実装する」 |
| 未使用変数の検出 | 「APIレスポンスは統一されたフォーマットで返す」 |
なぜリンターに任せるべきなのか
CLAUDE.md に書いたルールは、コンテキスト（Claudeの短期記憶）が圧縮されると無視されることがあります。一方、リンター（Biome、ESLint等のツール）はコンテキストに関係なく、必ずルールを強制します。
Hooks でリンターを自動実行する
Claude Code のHooks（フック＝特定のタイミングで自動実行するスクリプト）機能を使えば、Claude がコードを書いた直後に自動的にリンターを実行できます。Claude が書いたコードが自動的にフォーマット（整形）され、ルール違反が即座に修正されます。
CLAUDE.md に書くべき内容の具体例
# 設計方針（リンターでは表現できないルール） # アーキテクチャ - データベースアクセスはリポジトリパターンで実装する - ビジネスロジックはサービス層に集約する - コントローラーにビジネスロジックを書かない # エラーハンドリング - 外部API呼び出しは必ずリトライ（再試行）処理を入れる - ユーザー向けエラーメッセージと開発者向けログを分離する # テスト方針 - 新しい機能には必ずテストを書く - テストカバレッジ80%以上を維持する
マルチエージェント開発での活用
複数のClaude Codeインスタンス（同時に動く複数のClaude）を使う場合、CLAUDE.md でエージェントごとの役割を分けることができます。たとえば、フロントエンド（画面側）担当のClaude と バックエンド（サーバー側）担当のClaude にそれぞれ異なるCLAUDE.md を設定し、専門分野に特化した指示を出せます。ディレクトリ（フォルダ）ごとにCLAUDE.md を配置できる階層構造を活用します。