CLAUDE.mdとは何か
CLAUDE.mdって、ただのREADMEみたいなもの？
全然違うよ。CLAUDE.mdはClaude Codeへの「指示書」なんだ。ここに書いたルールをClaude Codeが自動的に読み込んで、すべての操作に反映してくれるよ。
CLAUDE.mdは、Claude Codeがセッション開始時に自動的に読み込む設定ファイル。プロジェクトのルール、制約、コーディング規約などを記述しておくと、Claude Codeがそれに従って動作する。
このファイルの有無で、Claude Codeの出力精度は大きく変わる。適切に設計されたCLAUDE.mdがあれば、毎回同じ指示を繰り返す必要がなくなり、プロジェクトに一貫した品質のコードを生成できるようになる。
Claude Codeの基本的な使い方については入門記事を、その他の上級機能については上級者ガイドを参照してほしい。
配置場所と適用範囲
CLAUDE.mdってどこに置けばいいの？
置く場所によって適用範囲が変わるんだ。プロジェクト用、ディレクトリ用、全プロジェクト共通の3パターンがあるよ。
| 配置場所 | 適用範囲 | 主な用途 |
|---|---|---|
| プロジェクトルート/CLAUDE.md | そのプロジェクト全体 | プロジェクト固有のルール |
| サブディレクトリ/CLAUDE.md | そのディレクトリ以下 | フロントエンド/バックエンドで異なるルール |
| ~/.claude/CLAUDE.md | 全プロジェクト共通 | 個人の共通設定 |
使い分けの具体例
たとえばフルスタックプロジェクトの場合、以下のように分けると効果的だ。
- プロジェクトルート/CLAUDE.md → 全体のアーキテクチャ方針、ブランチ戦略
- frontend/CLAUDE.md → React/TypeScriptのコーディング規約
- backend/CLAUDE.md → Python/FastAPIのコーディング規約
- ~/.claude/CLAUDE.md → 自分の言語設定（日本語で応答するなど）
Claude Codeは作業ディレクトリから上位に向かってCLAUDE.mdを探索し、見つかったものをすべてマージして適用する。
書くべき内容
何を書けば効果的なの？
ポイントは「Claude Codeが自力では分からないこと」を書くこと。コードを見れば分かることは書かなくていいよ。
1. ビルド・テストコマンド
プロジェクト固有のコマンドはClaude Codeが推測できないため、明記する価値が高い。
## コマンド
- ビルド: npm run build
- テスト全体: npm run test
- 単体テスト: npm run test -- --grep "テスト名"
- リント: npm run lint
- 型チェック: npx tsc --noEmit
2. コーディング規約
曖昧な表現を避け、具体的に記述する。
## コーディング規約
- インデント: 2スペース（タブ不可）
- 文字列: シングルクォートを使用
- 関数名: camelCase
- コンポーネント名: PascalCase
- ファイル名: kebab-case
- any型の使用は禁止
- console.logはコミットに含めない
曖昧な指示よりも具体的に書くほうが効果的。「コードを適切にフォーマットする」ではなく「2スペースインデントを使用する」のように記述しよう。
3. 禁止事項・制約
例外なく守るべきルールには「NEVER」「ALWAYS」を使うと効果的。
## 禁止事項
- NEVER: mainブランチに直接プッシュしない
- NEVER: .envファイルをコミットに含めない
- NEVER: 既存のテストを削除しない
- ALWAYS: 新しい関数にはテストを追加する
- ALWAYS: PRにはdescriptionを含める
4. アーキテクチャ上の判断理由
「何をするか」だけでなく「なぜそうするか」を書くと、Claude Codeが適切な判断を下しやすくなる。
## アーキテクチャ
- データベースアクセスはRepository層を経由する（直接SQLは禁止）
理由: テスタビリティとDB変更時の影響範囲を限定するため
- APIレスポンスは必ずDTO経由で返す（Entityを直接返さない）
理由: 内部構造の漏洩を防ぐため
書かないほうがいい内容
逆に、書かないほうがいいことってあるの？
CLAUDE.mdは毎回読み込まれるから、不要な情報を入れるとトークンの無駄遣いになるんだ。
避けるべき内容
- ディレクトリ構造の説明 → Claude Codeがファイルシステムを読めるため不要
- コードの動作説明 → コードを読めば分かる
- Git履歴の情報 → git logで取得できる
- READMEの内容の繰り返し → 既にREADMEを読める
- DBスキーマの全量 → 必要なときだけファイルを読ませればよい
サイズの目安
CLAUDE.mdは300行以内、3000トークン以内に収めるのが目安とされている。長すぎるとClaude Codeが重要な情報を見落とす原因になる。
各行について「これを削除するとClaude Codeが間違いを犯すか？」と自問し、答えがNoなら削除を検討しよう。
実践テンプレート
実際のプロジェクトで使えるテンプレートを紹介するね。
Webアプリケーション向けテンプレート
# プロジェクト: MyApp
## 技術スタック
- Frontend: React 19 + TypeScript 5.7
- Backend: FastAPI + Python 3.12
- DB: PostgreSQL 16
- ORM: SQLAlchemy 2.x
## コマンド
- フロントビルド: cd frontend && npm run build
- バックエンド起動: cd backend && uvicorn main:app --reload
- テスト: cd backend && pytest -x -v
- 単体テスト: cd backend && pytest -x -v -k "テスト名"
- マイグレーション: cd backend && alembic upgrade head
## コーディング規約
- Python: Black + isort（設定はpyproject.toml参照）
- TypeScript: ESLint + Prettier（設定は.eslintrc参照）
- any型は禁止、unknown + 型ガードを使う
- コンポーネントはfunction宣言で書く（アロー関数不可）
## アーキテクチャ
- API → Service → Repository の3層構造
- Repositoryのみがデータベースにアクセスする
- APIレスポンスは必ずPydanticスキーマ経由
## 禁止事項
- NEVER: SQLを直接書かない（SQLAlchemy経由のみ）
- NEVER: envファイルをコミットしない
- NEVER: 既存テストを削除しない
- ALWAYS: 新規エンドポイントにはテストを書く
## Git
- ブランチ: feature/TICKET-123-description
- コミット: 日本語で簡潔に（例: 「ユーザー認証APIを追加」）
運用のコツ
段階的に育てる
CLAUDE.mdは最初から完璧にする必要はない。Claude Codeを使っていて「また同じ間違いをした」と感じたら、そのルールを追記していくのが実践的だ。
定期的に見直す
プロジェクトの進行に伴い、不要になったルールは削除する。CLAUDE.mdが肥大化するとコンテキストを圧迫し、逆効果になる。
チームで共有する
プロジェクトルートのCLAUDE.mdはGitにコミットしてチーム全体で共有できる。チームメンバー全員が同じルールでClaude Codeを使えるため、コードの一貫性が保たれる。
個人的な設定はどうするの？
~/.claude/CLAUDE.mdに書けば、Gitにはコミットされないから安心だよ。「日本語で応答して」みたいな個人設定はここに書くのがおすすめかな。
まとめ
CLAUDE.mdは、Claude Codeの精度を大きく左右する重要な設定ファイル。効果的に活用するためのポイントは以下の通り。
- Claude Codeが「自力で分からないこと」を書く
- 具体的で曖昧さのない記述を心がける
- 300行以内に収め、不要な情報は排除する
- プロジェクトの成長に合わせて段階的に育てる
- チーム共有の設定と個人設定を配置場所で使い分ける
最初はビルドコマンドとコーディング規約から始めて、必要に応じてルールを追加していくのが良いだろう。
コメント