CLAUDE.md 完全ガイド — 書き方・配置・親子関係のすべてを解説

CLAUDE.mdって何？

Claude Codeをインストールしてすぐに使い始められるのは嬉しいことですが、何も設定しないままだと、Claudeはあなたのプロジェクトのことを何も知りません。コーディング規約も、テストの走らせ方も、デプロイ手順も、毎回チャットで説明し直す必要があります。

そこで登場するのがCLAUDE.mdです。CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込むMarkdownファイルです。ここにプロジェクトのルールや手順を書いておけば、Claudeは最初からあなたのプロジェクトを理解した状態で作業を始められます。

この記事では、CLAUDE.mdの配置場所、親フォルダ・子フォルダでの動作、書くべき内容、個人設定の分離方法、高度なテクニックまで、CLAUDE.mdに関するすべてを徹底解説します。

配置場所 — どこに置く？

CLAUDE.mdは1つの場所にだけ置けるわけではありません。用途に応じて複数の場所に配置でき、すべてが読み込まれます。

4つの配置レベル

1. プロジェクトルート（最も一般的）

プロジェクトのルートディレクトリに直接 CLAUDE.md を置く方法です。最もシンプルで、ほとんどのプロジェクトではこれだけで十分です。ファイルが見えやすいので、チームメンバーもすぐに気づけます。

2. プロジェクト .claude 内

.claude/CLAUDE.md に置くと、プロジェクトルートのファイルツリーがスッキリします。他の設定ファイル（settings.json など）と一緒に .claude/ フォルダにまとめたい場合に便利です。

3. ユーザー全体

~/.claude/CLAUDE.md に置くと、すべてのプロジェクトで自動的に読み込まれます。「日本語でコミュニケーションする」「コミットメッセージは日本語で」など、個人の共通ルールを書くのに最適です。

4. 親ディレクトリ

Claude Codeは現在のディレクトリから親ディレクトリに向かってCLAUDE.mdを探索します。モノレポの親フォルダに全体ルールを置き、各パッケージに個別ルールを置く、という使い方ができます。

親子CLAUDE.md — 複数ファイルの関係

CLAUDE.mdの最も重要な特徴の1つが、複数のCLAUDE.mdが「上書き」ではなく「結合」されることです。これを理解しているかどうかで、モノレポや大規模プロジェクトでの活用の幅が大きく変わります。

ツリー走査の仕組み

Claude Codeは起動時に、現在の作業ディレクトリ（cwd）から親ディレクトリに向かってCLAUDE.mdを探索します。ルートディレクトリまたはgitリポジトリのルートに到達するまで探索を続け、見つかったすべてのCLAUDE.mdを結合してコンテキストに読み込みます。

モノレポでの実用例

この仕組みが最も輝くのが、モノレポ（1つのリポジトリに複数パッケージがある構成）です。

monorepo/
├── CLAUDE.md              ← 全チーム共通ルール
│                           （コーディング規約、セキュリティ方針）
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md      ← フロントエンド固有ルール
│   │                       （React規約、テスト手順）
│   └── backend/
│       └── CLAUDE.md      ← バックエンド固有ルール
│                           （API設計、DB操作ルール）

packages/frontend/ で Claude Code を起動すると、monorepo/CLAUDE.md（全体ルール）と packages/frontend/CLAUDE.md（フロントエンドルール）の両方が読み込まれます。バックエンドのCLAUDE.mdは読み込まれません。

何を書く？ — CLAUDE.mdの中身

CLAUDE.mdの存在意義を理解したところで、最も重要な問題に入りましょう。「具体的に何を書けばいいのか」です。

書くべき内容

最も効果的なアプローチは、「新しいメンバーがチームに入ったとき、口頭で伝えること」を書くことです。具体的には以下のカテゴリがあります。

1. プロジェクト概要 — 技術スタック、アーキテクチャの概要。「このプロジェクトはNext.js 15 + Prisma + PostgreSQLで構築されている」のような情報です。

2. コーディング規約 — インデント幅、命名規則、ファイル構成。具体的に書くのがポイントです。「きれいなコードを書いて」ではなく「2スペースインデント、関数名はcamelCase、コンポーネントはPascalCase」と書きます。

3. ワークフロー — テスト実行方法（npm test）、ビルド手順（npm run build）、デプロイ手順。Claudeがテストを走らせたいときに参照できます。

4. セキュリティルール — 「APIキーをハードコードしない」「.envファイルをcommitしない」等の禁止事項。最も重要なカテゴリの1つです。

5. よく使うコマンド — npm run dev、pytest -v、docker compose up など、プロジェクトで頻繁に使うコマンド。

6. プロジェクト固有の注意事項 — 既知のバグ、回避策、「このファイルは触らないで」等の地雷情報。

書くべきでない内容

CLAUDE.mdは毎セッション読み込まれるため、長くなるほどコンテキストを圧迫します。推奨は100〜200行以内です。以下の内容はCLAUDE.mdに書くべきではありません。

• 長大なAPIリファレンス → スキル（SKILL.md）に分離する
• 環境変数の値そのもの → .envファイルで管理する
• 一時的なタスク指示 → チャットで直接伝える
• 全ソースコードの説明 → コード自体が自己文書化すべき

良い書き方の例

# プロジェクト概要
Next.js 15 + Prisma + PostgreSQL で構築されたECサイト。
monorepo構成（pnpm workspace）。

## コーディング規約
- インデント: 2スペース（JS/TS/CSS）
- 命名: 関数はcamelCase、コンポーネントはPascalCase
- import順: 外部 → 内部 → 型（空行で分離）

## テスト
- ユニットテスト: pnpm test
- E2Eテスト: pnpm test:e2e（Playwright）
- テスト実行前に pnpm db:reset でDBリセット

## セキュリティ
- APIキーをハードコードしない（必ず環境変数を使用）
- .envファイルをgit commitしない
- ユーザー入力は必ずバリデーションする

## よく使うコマンド
- pnpm dev: 開発サーバー起動
- pnpm build: プロダクションビルド
- pnpm db:migrate: DBマイグレーション実行

CLAUDE.local.md — チーム開発と個人設定

チーム開発をしていると、「自分だけのルール」を書きたくなる場面があります。ローカルの開発ポートが他のメンバーと違う、日本語でコメントを書いてほしい、デバッグ用の一時的な指示を出したい…。こういった個人設定を共有のCLAUDE.mdに書いてしまうと、チームメンバーに影響が出てしまいます。

そこで使うのがCLAUDE.local.mdです。

CLAUDE.local.md とは

CLAUDE.local.mdは、.gitignoreに入れる個人用のCLAUDE.mdです。CLAUDE.mdと同じように自動読み込みされますが、git管理外なので他のメンバーには影響しません。

配置場所はCLAUDE.mdと同様に3つのレベルがあります。

• ./CLAUDE.local.md — プロジェクトルート
• ./.claude/CLAUDE.local.md — プロジェクト .claude 内
• ~/.claude/CLAUDE.local.md — ユーザー全体

ユースケース

• ローカル環境の情報 — ポート番号、DB接続先、テスト用のAPIエンドポイント
• 個人的な開発スタイル — 「日本語でコメントを書いて」「変更前にgit diffを見せて」
• 一時的なデバッグ指示 — 「このバグの原因を調査中。ログを多めに出して」

.gitignore への追加を忘れずに

# .gitignore
CLAUDE.local.md

.claude/rules/ — パス別ルール

プロジェクトが大きくなると、CLAUDE.mdに書くルールも増えていきます。フロントエンドの規約、バックエンドのAPI設計ルール、テストの書き方…。これらをすべてCLAUDE.mdに書くと、100〜200行の推奨行数を簡単に超えてしまいます。

そこで活用したいのが.claude/rules/ディレクトリです。

仕組み

.claude/rules/ に置いたMarkdownファイルは、YAMLフロントマターの paths フィールドで指定したファイルパターンにマッチするファイルを操作する時だけ自動で読み込まれます。

# .claude/rules/frontend.md
---
paths:
  - "src/components/**"
  - "src/pages/**"
  - "src/hooks/**"
---

# フロントエンド開発ルール
- React 19 の Server Components を使用
- CSS は CSS Modules（*.module.css）で記述
- コンポーネントは PascalCase、hooksは use プレフィックス
- テストは React Testing Library を使用

# .claude/rules/api.md
---
paths:
  - "src/api/**"
  - "src/middleware/**"
---

# API開発ルール
- RESTful 設計に従う
- エラーレスポンスは統一フォーマット: { error: string, code: number }
- 全エンドポイントに認証ミドルウェアを適用
- リクエストボディは Zod でバリデーション

フロントエンドのコンポーネントを編集している時は「フロントエンド開発ルール」だけが読み込まれ、APIファイルを編集している時は「API開発ルール」だけが読み込まれます。コンテキストを無駄に使わない、賢い仕組みです。

@インポートと高度なテクニック

CLAUDE.mdの基本をマスターしたら、さらに便利な高度なテクニックを見ていきましょう。

@インポート — 外部ファイルの取り込み

CLAUDE.md内で @path/to/file と書くと、そのファイルの内容がCLAUDE.mdに取り込まれます。本体を短く保ちつつ、詳細なドキュメントを参照できる強力な機能です。

# CLAUDE.md

## プロジェクト概要
ECサイト（Next.js 15 + Prisma）

## 詳細仕様
@docs/architecture.md
@docs/api-spec.md

## コーディング規約
@docs/coding-standards.md

インポートはネスト可能です（最大5ホップまで）。つまり、取り込んだファイルの中にさらに @path があれば、そちらも読み込まれます。ただし、深くネストしすぎるとコンテキストが膨大になるので注意が必要です。

/init コマンド — CLAUDE.mdの自動生成

「何を書けばいいかわからない」なら、Claude Codeの /init コマンドが助けてくれます。プロジェクトの構造、パッケージ構成、コードスタイルを自動で分析し、初期CLAUDE.mdを生成します。

# ターミナルで実行
claude /init

既にCLAUDE.mdがある場合は改善提案をしてくれます。完璧なCLAUDE.mdを0から書く必要はありません。まずは /init で生成して、そこから編集していくのが最も効率的なアプローチです。

自動メモリ機能

Claude Codeにはセッション横断型の自動メモリ機能もあります。~/.claude/projects/<hash>/memory/MEMORY.md に、Claude Codeが学習したパターンや好みが自動保存されます。これはCLAUDE.mdとは別の仕組みで、明示的に管理する必要はありません。

信頼モデル

セキュリティの観点で重要なポイントがあります。プロジェクトのCLAUDE.mdは、そのプロジェクトを初めて開いたときユーザーの承認が必要です。これは、悪意のあるCLAUDE.mdが勝手に危険なコマンドを実行するのを防ぐための仕組みです。一方、ユーザーの ~/.claude/CLAUDE.md は自分で作成したものなので無条件に信頼されます。

実践テンプレート集

理論はわかったけど、いざ書くとなると手が止まる…。そんな方のために、すぐに使えるテンプレートを用意しました。プロジェクトの種類に合わせて選び、カスタマイズしてください。

テンプレート1: 個人プロジェクト（ミニマル）

最小限の構成。まずはここから始めるのがおすすめです。

# プロジェクト名

## 概要
静的サイト（HTML/CSS/JS）。

## コーディング規約
- インデント: 2スペース
- ファイル末尾に改行を入れる

## コマンド
- 開発サーバー: python -m http.server 8080
- デプロイ: git push origin main

## 注意事項
- .env ファイルを commit しない
- assets/images/ の画像は WebP を使用

テンプレート2: Webフロントエンド（React/Next.js）

# MyApp - Webフロントエンド

## 概要
Next.js 15 App Router + TypeScript + Tailwind CSS。
pnpm をパッケージマネージャーとして使用。

## コーディング規約
- TypeScript strict mode を使用
- コンポーネント: PascalCase（例: UserProfile.tsx）
- hooks: use プレフィックス（例: useAuth.ts）
- CSS: Tailwind のユーティリティクラスを使用
- import順: 外部ライブラリ → 内部モジュール → 型定義（空行で分離）

## テスト
- ユニットテスト: pnpm test（Vitest）
- E2Eテスト: pnpm test:e2e（Playwright）
- コンポーネントテストは React Testing Library を使用

## コマンド
- pnpm dev: 開発サーバー（localhost:3000）
- pnpm build: プロダクションビルド
- pnpm lint: ESLint 実行
- pnpm type-check: TypeScript型チェック

## セキュリティ
- APIキーはサーバーサイドのみで使用（NEXT_PUBLIC_ を付けない）
- ユーザー入力は Zod でバリデーション
- dangerouslySetInnerHTML は使用禁止

## ディレクトリ構成
- src/app/ — App Router のページ
- src/components/ — 共有コンポーネント
- src/hooks/ — カスタムフック
- src/lib/ — ユーティリティ・API クライアント

テンプレート3: バックエンドAPI（Python/FastAPI）

# MyAPI - バックエンド

## 概要
FastAPI + SQLAlchemy + PostgreSQL。
Python 3.12、仮想環境は venv を使用。

## コーディング規約
- インデント: 4スペース
- 型ヒント必須（関数の引数・戻り値）
- docstring: Google スタイル
- 命名: snake_case（変数・関数）、PascalCase（クラス）

## テスト
- pytest -v で全テスト実行
- テストDBは SQLite（テスト時のみ自動作成）
- fixtures は conftest.py に定義

## コマンド
- source venv/bin/activate: 仮想環境有効化
- uvicorn main:app --reload: 開発サーバー
- alembic upgrade head: DBマイグレーション
- alembic revision --autogenerate -m "message": マイグレーション生成

## セキュリティ
- SQLAlchemy の ORM を使用（生SQLは禁止）
- パスワードは bcrypt でハッシュ化
- JWT トークンの秘密鍵は環境変数から取得
- CORS は許可オリジンを明示的に指定

テンプレート4: モノレポ（親子構成）

親CLAUDE.md（リポジトリルート）:

# MyProject - モノレポ

## 概要
pnpm workspace によるモノレポ構成。
フロントエンド（Next.js）+ バックエンド（Express）+ 共有ライブラリ。

## 共通ルール
- TypeScript strict mode
- コミットメッセージ: Conventional Commits
- PR作成前に全テスト通過を確認
- mainブランチに直接pushしない

## セキュリティ
- .env ファイルは commit しない
- APIキーは環境変数で管理
- 依存関係の脆弱性: pnpm audit で定期確認

子CLAUDE.md（packages/frontend/）:

# フロントエンドパッケージ

## 固有ルール
- React 19 Server Components を優先使用
- CSS は Tailwind CSS のみ（styled-components 禁止）
- 画像は next/image を使用（imgタグ直接使用禁止）

## テスト
- pnpm --filter frontend test
- Storybook でUIコンポーネントの動作確認

まとめ

この記事では、CLAUDE.mdのすべてを解説しました。最後に、全体を振り返りましょう。

• CLAUDE.mdとは — Claude Codeが毎セッション自動読み込みする自然言語の指示書
• 配置場所 — プロジェクトルート、.claude/内、ユーザー全体（~/.claude/）、親ディレクトリの4レベル
• 親子関係 — 複数のCLAUDE.mdは「上書き」ではなく「結合」される
• 書くべき内容 — プロジェクト概要、コーディング規約、テスト手順、セキュリティルール（推奨100〜200行）
• CLAUDE.local.md — チーム開発での個人設定は .gitignore で分離
• .claude/rules/ — ファイルパスに応じて自動適用されるパス別ルール
• @インポート — 外部ファイルを取り込んでCLAUDE.mdを軽量に保つ
• /init — CLAUDE.mdの自動生成。まずはここから始めるのがおすすめ

CLAUDE.mdは「生きたドキュメント」です。最初から完璧である必要はありません。/init で自動生成して、プロジェクトと一緒に育てていきましょう。