CLAUDE.mdの書き方 - プロジェクトルールでAIを制御する
Claude Codeにおけるプロジェクト固有のルール・コンテキストを定義するファイル「CLAUDE.md」の仕様と書き方をまとめたリファレンス。
CLAUDE.mdとは
CLAUDE.mdは、Claude Code（AnthropicのAIコーディングツール）が会話開始時に自動的に読み込むMarkdownファイル。プロジェクトの技術スタック、コーディング規約、ディレクトリ構成、ワークフローなどを記述することで、Claudeの応答をプロジェクトに合わせて制御できる。
主な役割:
- プロジェクト固有のコンテキストをClaudeに伝える
- コーディング規約やルールを強制する
- チームで共有する開発ガイドラインを一元管理する
- 繰り返しの説明を省略し、効率的にAIを活用する
ファイルの階層構造
CLAUDE.mdは複数の場所に配置でき、それぞれスコープが異なる。より具体的な場所に置かれたファイルが優先される。
配置場所一覧
| 配置場所 | スコープ | 用途 | バージョン管理 |
|---|---|---|---|
| 管理ポリシー（後述） | 組織全体 | IT/DevOps管理の全社ルール | OS管理 |
~/.claude/CLAUDE.md | ユーザー全体 | 個人の共通設定・好み | 対象外 |
./CLAUDE.md | プロジェクト | チーム共有のプロジェクトルール | Git管理 |
./.claude/CLAUDE.md | プロジェクト | 同上（.claude/ディレクトリに格納する場合） | Git管理 |
./子ディレクトリ/CLAUDE.md | サブディレクトリ | 特定ディレクトリ固有のルール | Git管理 |
管理ポリシーの配置場所（OS別）
組織全体で共有するルールを配置できる場所はOSごとに異なる。
| OS | パス |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/CLAUDE.md |
| Linux / WSL | /etc/claude-code/CLAUDE.md |
| Windows | C:\Program Files\ClaudeCode\CLAUDE.md |
読み込みの仕組み
管理ポリシー（組織全体）
↓
~/.claude/CLAUDE.md（ユーザー全体）
↓
プロジェクトルートの CLAUDE.md（チーム共有）
↓
作業ディレクトリまでの各階層の CLAUDE.md
↓
サブディレクトリの CLAUDE.md（オンデマンド読み込み）- プロジェクトルートより上のディレクトリにあるCLAUDE.mdは起動時に自動読み込みされる
- サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリのファイルを操作する際にオンデマンドで読み込みされる
- より具体的（深い階層）のファイルが、より広いスコープのファイルを上書きする
書くべき内容
CLAUDE.mdに記述すると効果的な内容は以下のとおり。
1. プロジェクト概要
## 概要
ECサイトのバックエンドAPI。Go + Gin フレームワーク。
PostgreSQLをデータストアとして使用。プロジェクトが何であるかを1〜3行で簡潔に示す。Claudeがコードの意図を理解する助けになる。
2. 技術スタック
## 技術スタック
- **言語**: TypeScript 5.x
- **フレームワーク**: Next.js 15 (App Router)
- **UI**: Tailwind CSS v4 + shadcn/ui
- **DB**: PostgreSQL 16 + Drizzle ORM
- **テスト**: Vitest + Playwright
- **CI/CD**: GitHub Actions使用しているライブラリやフレームワークとそのバージョンを明記する。Claudeが古いAPIを使ったコードを生成するのを防げる。
3. コーディング規約
## コーディング規約
- インデント: スペース2つ
- 文字列: シングルクォート
- セミコロン: なし
- 命名規則: camelCase（変数・関数）、PascalCase（型・クラス）
- インポート順序: 外部モジュール → 内部モジュール → 相対パス
- コミットメッセージ: Conventional Commits形式（日本語）Prettierやlinterの設定だけでなく、自動整形されないルール（命名規則、コミットメッセージ形式など）を明記する。
4. ディレクトリ構成
## ディレクトリ構成src/ ├── app/ # Next.js App Routerのルーティング ├── components/ # UIコンポーネント │ ├── ui/ # 基本UIパーツ（Button, Input等） │ └── features/ # 機能別コンポーネント ├── lib/ # ユーティリティ・共通ロジック ├── hooks/ # カスタムフック ├── types/ # 型定義 └── styles/ # グローバルスタイル
ディレクトリの役割を示すことで、Claudeが新しいファイルを適切な場所に配置できるようになる。
5. ビルド・テスト・デプロイコマンド
## コマンド
- `npm run dev` - 開発サーバー起動
- `npm run build` - 本番ビルド
- `npm run test` - テスト実行
- `npm run test:e2e` - E2Eテスト実行
- `npm run lint` - リント実行
- `npm run db:migrate` - DBマイグレーション実行Claudeがテストの実行やビルドの検証を行う際に参照する。
6. プロジェクト固有のルール・注意事項
## ルール
- **Gitコミットはユーザーから依頼があった時のみ実行する**
- APIキーやシークレットをコードに直接書かない
- 新しいページを追加したら sitemap.xml も更新する
- エラーメッセージは日本語で記述する
- `console.log` をコミットしない（デバッグ用は `debug` パッケージを使用）これらのルールはClaude Codeの振る舞いに直接影響する。明確かつ具体的に書くほど、Claudeの遵守率が高くなる。
7. 新規追加の手順
## 新しいAPIエンドポイント追加手順
1. `src/routes/` にルートファイルを作成
2. `src/controllers/` にコントローラーを作成
3. `src/services/` にビジネスロジックを作成
4. `src/validators/` にバリデーションスキーマを作成
5. `src/routes/index.ts` にルートを登録
6. テストを作成・実行定型的な作業手順を記述しておくと、Claudeが手順どおりに作業を進められる。
書くべきでない内容
| 避けるべき内容 | 理由 |
|---|---|
| コードを読めばわかること | Claudeはコードベースを直接読めるため冗長 |
| 一時的な情報（「今はバグ修正中」等） | すぐに古くなり混乱の原因になる |
| 長大なAPIドキュメント | CLAUDE.mdが長すぎるとコンテキストを圧迫する |
| 機密情報（APIキー、パスワード等） | Git管理されるため漏洩リスクがある |
| 汎用的なプログラミング知識 | Claudeが既に持っている知識を繰り返す必要はない |
| 他ファイルのコピー＆ペースト | @インポート構文で参照する方が保守しやすい |
@インポート構文
CLAUDE.mdでは @ 構文を使って他のファイルの内容を取り込める。ファイルの重複を避け、モジュール化された管理が可能になる。
# プロジェクトルール
- Gitワークフロー @docs/git-instructions.md
- プロジェクト概要は @README を参照
- 利用可能なnpmコマンドは @package.json を参照
# 個人設定
- @~/.claude/my-project-instructions.md- パスはCLAUDE.mdからの相対パスまたは絶対パスで指定する
~はホームディレクトリに展開される- ネストは最大5階層まで可能
- ファイル名のみ（
@README）の場合は同一ディレクトリ内を検索する
CLAUDE.local.md
CLAUDE.local.md はCLAUDE.mdのローカル版で、Gitにコミットしない個人設定を記述するためのファイル。
CLAUDE.md と CLAUDE.local.md の使い分け
| 項目 | CLAUDE.md | CLAUDE.local.md |
|---|---|---|
| 用途 | チーム共有のルール | 個人の好み・環境設定 |
| Git管理 | する | しない（.gitignoreに追加） |
| 配置場所 | プロジェクトルート | プロジェクトルート |
| 読み込み | 自動 | 自動 |
.gitignore への追加
CLAUDE.local.mdCLAUDE.local.md の記述例
# 個人設定
## コミュニケーション
- 日本語で会話する
- 丁寧語（です・ます調）を使用する
## 環境
- WSL2上のUbuntu 24.04で開発している
- エディタはVSCode
- ターミナルはWindows Terminal
## 個人の好み
- 変更を加えたらこまめにgit diffで確認してから次に進む
- テストは変更のたびに実行する自動メモリ（Auto Memory）
Claude Codeには、CLAUDE.mdとは別に自動メモリという仕組みがある。
| 項目 | CLAUDE.md | 自動メモリ |
|---|---|---|
| 書き手 | ユーザー | Claude自身 |
| 内容 | ルール・指示 | 学習したパターン・修正内容 |
| スコープ | プロジェクト / ユーザー / 組織 | ワーキングツリー単位 |
| 読み込み | 全文 | 先頭200行 |
自動メモリはClaudeがユーザーからの修正や指摘を学習して自動的に記録するもので、手動で管理する必要はない。CLAUDE.mdは明示的なルール定義、自動メモリは暗黙的な学習記録、という位置づけで使い分ける。
実例パターン
パターン1: フロントエンドプロジェクト（React + TypeScript）
# MyApp フロントエンド
## 概要
社内向けダッシュボードアプリケーション。React + TypeScript + Vite。
## 技術スタック
- **フレームワーク**: React 19 + TypeScript 5.7
- **ビルドツール**: Vite 6
- **UIライブラリ**: MUI v6
- **状態管理**: Zustand
- **データ取得**: TanStack Query v5
- **テスト**: Vitest + React Testing Library
## コーディング規約
- Prettier設定: セミコロンなし、シングルクォート、インデント2スペース
- コンポーネントは関数コンポーネント + アロー関数で記述
- 型定義は `interface` を優先（`type` はユニオン型のみ）
- カスタムフックは `hooks/` ディレクトリに配置
- コミットメッセージ: Conventional Commits（英語）
## ディレクトリ構成
src/
├── components/ # UIコンポーネント
├── hooks/ # カスタムフック
├── pages/ # ページコンポーネント
├── stores/ # Zustandストア
├── types/ # 型定義
├── utils/ # ユーティリティ関数
└── App.tsx # ルーティング
## コマンド
- `npm run dev` - 開発サーバー（port 5173）
- `npm run build` - ビルド
- `npm run test` - テスト実行
- `npm run lint` - ESLint実行パターン2: バックエンドAPI（Python + FastAPI）
# OrderAPI
## 概要
注文管理REST API。FastAPI + SQLAlchemy + PostgreSQL。
## 技術スタック
- **言語**: Python 3.12
- **フレームワーク**: FastAPI 0.115
- **ORM**: SQLAlchemy 2.0 + Alembic（マイグレーション）
- **バリデーション**: Pydantic v2
- **テスト**: pytest + httpx
- **コンテナ**: Docker + docker-compose
## コーディング規約
- フォーマッター: Ruff（line-length = 120）
- 型ヒント必須（すべての関数に引数・戻り値の型を明記）
- docstringはGoogle Style
- テストファイルは `tests/` に対応するモジュール構造で配置
## ディレクトリ構成
app/
├── api/
│ └── v1/
│ ├── endpoints/ # エンドポイント定義
│ └── deps.py # 依存性注入
├── models/ # SQLAlchemyモデル
├── schemas/ # Pydanticスキーマ
├── services/ # ビジネスロジック
├── repositories/ # データアクセス層
└── core/
├── config.py # 設定
└── database.py # DB接続
## コマンド
- `docker-compose up -d` - 開発環境起動
- `pytest` - テスト実行
- `alembic upgrade head` - マイグレーション実行
- `alembic revision --autogenerate -m "説明"` - マイグレーション作成
## ルール
- エンドポイントにビジネスロジックを直接書かない（serviceレイヤーに委譲）
- 新しいエンドポイント追加時はテストも必ず作成する
- 環境変数は `core/config.py` の Settings クラスで管理するパターン3: インフラ・IaC（Terraform）
# AWS Infrastructure
## 概要
本番環境のAWSインフラ定義。Terraform + AWS。
## 技術スタック
- **IaC**: Terraform 1.9
- **プロバイダ**: AWS (ap-northeast-1)
- **状態管理**: S3 + DynamoDB（リモートステート）
- **CI/CD**: GitHub Actions（plan → approve → apply）
## ディレクトリ構成
terraform/
├── environments/
│ ├── dev/ # 開発環境
│ ├── staging/ # ステージング
│ └── prod/ # 本番環境
├── modules/ # 再利用可能なモジュール
│ ├── vpc/
│ ├── ecs/
│ ├── rds/
│ └── cloudfront/
└── global/ # 全環境共通リソース
## ルール
- **`terraform apply` は絶対に実行しない**（CI/CDからのみ適用）
- `terraform plan` で変更内容を確認するのみ
- モジュールを変更したら全環境への影響を確認する
- セキュリティグループのルールは最小権限の原則に従う
- シークレットはAWS Secrets Managerで管理する（tfvarsに書かない）
## 命名規則
- リソース名: `{project}-{env}-{resource}`（例: `myapp-prod-ecs-cluster`）
- タグ: `Project`, `Environment`, `ManagedBy=terraform` を必須とするパターン4: モノレポ（フロント + バック）
モノレポでは、ルートのCLAUDE.mdに共通ルールを書き、各パッケージのディレクトリにサブCLAUDE.mdを配置する。
ルートの CLAUDE.md:
# MyProject モノレポ
## 概要
フロントエンド（Next.js）とバックエンド（NestJS）のモノレポ。
## パッケージ構成
- `packages/web` - フロントエンド（Next.js 15）
- `packages/api` - バックエンドAPI（NestJS 11）
- `packages/shared` - 共有型定義・ユーティリティ
## 共通ルール
- パッケージマネージャー: pnpm
- Node.js: v22
- コミットメッセージ: `feat(web):`, `fix(api):` のようにスコープを付ける
- `packages/shared` を変更したら web と api 両方への影響を確認するpackages/web/CLAUDE.md:
# フロントエンド固有ルール
- App Router使用（Pages Routerは使わない）
- サーバーコンポーネントをデフォルトとし、必要な場合のみ `'use client'` を付ける
- API呼び出しは `lib/api-client.ts` のラッパーを使用するpackages/api/CLAUDE.md:
# バックエンドAPI固有ルール
- すべてのエンドポイントにSwaggerデコレータを付ける
- DTOはclass-validatorでバリデーションする
- ガード（認証）は `@UseGuards(JwtAuthGuard)` を使用するベストプラクティス
簡潔に書く
CLAUDE.mdの内容はすべてコンテキストウィンドウを消費する。不必要に長い説明は避け、箇条書きやテーブルで端的に記述する。
# ❌ 冗長な記述
このプロジェクトではTypeScriptを使用しています。TypeScriptはJavaScriptに
静的型付けを追加した言語で、Microsoftによって開発されました。型安全性を
確保することで、実行時エラーを減らすことができます。
# ✅ 簡潔な記述
## 技術スタック
- TypeScript 5.7 + React 19命令形で書く
Claudeへの指示は曖昧な表現より明確な命令形の方が遵守率が高い。
# ❌ 曖昧
- テストを書いてくれると嬉しいです
- できればESLintを通してください
# ✅ 明確
- 新しい関数には必ずユニットテストを作成する
- コミット前にESLintエラーがないことを確認する定期的に更新する
技術スタックのバージョンアップ、ディレクトリ構成の変更、新しいルールの追加があった場合はCLAUDE.mdも更新する。古い情報が残っているとClaudeが誤った判断をする原因になる。
プロジェクトルールで分割する
大規模プロジェクトでは、CLAUDE.mdが肥大化しやすい。.claude/ ディレクトリ内にルールファイルを分割して管理し、@インポートで参照する方法が有効。
.claude/
├── CLAUDE.md # メインのルール
├── coding-standards.md # コーディング規約
├── api-guidelines.md # API設計ガイドライン
└── deployment.md # デプロイ手順# CLAUDE.md
@.claude/coding-standards.md
@.claude/api-guidelines.md
@.claude/deployment.md効果を検証する
CLAUDE.mdのルールが意図どおりに機能しているか、実際の会話で確認する。ルールが守られない場合は、記述をより具体的・明確にする。
設定ファイル一覧
Claude Codeに関連する設定ファイルの全体像を示す。
| ファイル | 場所 | 用途 | Git管理 |
|---|---|---|---|
CLAUDE.md | プロジェクトルート | プロジェクトルール（チーム共有） | する |
.claude/CLAUDE.md | .claude/ ディレクトリ | 同上（ディレクトリにまとめる場合） | する |
CLAUDE.local.md | プロジェクトルート | 個人設定（ローカル限定） | しない |
~/.claude/CLAUDE.md | ホームディレクトリ | ユーザー全体の共通設定 | しない |
~/.claude/settings.json | ホームディレクトリ | Claude Codeの動作設定 | しない |
.claude/settings.json | プロジェクト | プロジェクト固有の動作設定 | する |
.claude/settings.local.json | プロジェクト | 個人の動作設定 | しない |
参考リンク
- Claude Code 公式ドキュメント - Memory - CLAUDE.mdの配置場所、読み込みの仕組み、自動メモリの解説
- Claude Code 公式ドキュメント - Configuration - settings.jsonなどの設定ファイルの解説
- Claude Code GitHub リポジトリ - ソースコードおよびドキュメント
- Anthropic 公式サイト - Claude全般の情報