📚 この記事は「Claude Code 完全攻略シリーズ」の Episode 12 です。
Claude Codeを使い始めたとき、「毎回同じ指示を繰り返すのが面倒」「プロジェクト固有のルールをAIが理解してくれない」と感じたことはありませんか？
その悩みを解決するのがCLAUDE.mdです。プロジェクトのルート（または各ディレクトリ）に配置するだけで、Claude Codeが自動的に読み込み、プロジェクト固有のコンテキストとして活用します。
本記事では、CLAUDE.mdの基本から実践的な書き方パターン、SES現場での活用テクニックまで、すぐに使えるノウハウを解説します。
- CLAUDE.mdの役割と配置場所の使い分け
- 効果的なCLAUDE.mdの構成と記述パターン
- SES現場で即使えるCLAUDE.mdテンプレート
- チーム開発でCLAUDE.mdを運用するベストプラクティス
CLAUDE.mdとは？Claude Codeの「プロジェクト記憶」
CLAUDE.mdの基本的な役割
CLAUDE.mdは、Claude Codeにプロジェクト固有の情報を伝えるためのMarkdownファイルです。Claude Codeはセッション開始時にこのファイルを自動的に読み込み、すべての応答でその情報を考慮します。
具体的には、以下のような情報を記述します。
- プロジェクトの技術スタック・アーキテクチャ
- コーディング規約・命名規則
- ビルド・テストの実行コマンド
- ディレクトリ構成の説明
- よくあるパターンや禁止事項
これは人間の開発者に渡す「プロジェクトのオンボーディングドキュメント」に近い役割を果たします。
なぜCLAUDE.mdが重要なのか
CLAUDE.mdがない場合、Claude Codeはプロジェクトの情報をコードから推測するしかありません。これにより以下の問題が起きます。
| 状況 | CLAUDE.mdなし | CLAUDE.mdあり |
|---|---|---|
| 命名規則 | ファイルごとにバラバラな提案 | 一貫したスタイルで生成 |
| テスト実行 | 「テストコマンドは？」と毎回質問 | 自動的に正しいコマンドを使用 |
| アーキテクチャ | 既存パターンと異なるコードを生成 | プロジェクトの規約に準拠 |
| 禁止事項 | 知らずに使ってはいけないライブラリを提案 | 制約を守った提案のみ |
SES現場では特に、参画直後のプロジェクト理解にCLAUDE.mdが効きます。既存メンバーが書いたCLAUDE.mdがあれば、Claude Codeが即座にプロジェクトの文脈を把握し、的確なコード生成が可能になります。
CLAUDE.mdの配置場所と読み込み優先順位
CLAUDE.mdは複数の場所に配置でき、それぞれ適用範囲が異なります。
3つの配置レベル
~/.claude/CLAUDE.md ← ユーザーレベル（全プロジェクト共通）
./CLAUDE.md ← プロジェクトレベル（リポジトリルート）
./src/CLAUDE.md ← ディレクトリレベル（特定ディレクトリ）
./src/components/CLAUDE.md ← さらに深い階層も可能読み込み順序と適用ルール：
- ユーザーレベル (
~/.claude/CLAUDE.md) — 個人の好みや全プロジェクト共通の設定 - プロジェクトレベル (
./CLAUDE.md) — リポジトリ固有のルール（Git管理推奨） - ディレクトリレベル (
./[path]/CLAUDE.md) — 特定ディレクトリのみに適用
すべてのレベルのCLAUDE.mdがマージされて適用されます。矛盾がある場合は、より深い階層の指示が優先されます。
配置場所の使い分け（実践例）
# ~/.claude/CLAUDE.md（ユーザーレベル）
- 日本語で回答すること
- コミットメッセージはConventional Commits形式
- TypeScriptを優先
# ./CLAUDE.md（プロジェクトレベル）
- Next.js 14 + App Router構成
- テスト: pnpm test
- lint: pnpm lint
# ./src/components/CLAUDE.md（ディレクトリレベル）
- コンポーネントはfunction宣言で作成
- Storybookファイルを必ず併設.claude/CLAUDE.md（ローカル設定）
.claude/CLAUDE.md（ドットディレクトリ内）はGitで管理されない個人設定用です。.gitignoreに含まれるため、チームに影響を与えずに個人の好みを設定できます。
# .claude/CLAUDE.md
- デバッグ時はconsole.logではなくdebuggerを使う
- PRの説明文は日本語で書く
- 自分のSlack IDは @yuya効果的なCLAUDE.mdの書き方
基本構成テンプレート
# プロジェクト概要
[プロジェクト名]は[目的]のための[技術スタック]アプリケーション。
# 技術スタック
- フロントエンド: React 18 + TypeScript
- バックエンド: Node.js + Express
- DB: PostgreSQL + Prisma
- テスト: Vitest + Playwright
# コマンド
- `pnpm dev` — 開発サーバー起動
- `pnpm test` — テスト実行
- `pnpm test:unit -- path/to/file` — 単体テスト
- `pnpm lint` — lint実行
- `pnpm build` — ビルド
# コーディング規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- named exportを標準とする
- ファイル名はkebab-caseで統一
# ディレクトリ構成
src/
├── app/ # Next.js App Router
├── components/ # UIコンポーネント
├── lib/ # ユーティリティ
├── hooks/ # カスタムHooks
└── types/ # 型定義
# 重要な注意事項
- envファイルを絶対にコミットしない
- DBマイグレーションは必ずPRで確認を得てから実行効果を最大化する5つのポイント
1. 具体的なコマンドを書く
# ❌ 曖昧
テストを実行してからコミットしてください。
# ✅ 具体的
単体テスト: pnpm vitest run
E2Eテスト: pnpm playwright test
lint: pnpm eslint . --fix
型チェック: pnpm tsc --noEmit2. 「なぜ」を添える
# ❌ ルールだけ
dayjs禁止。date-fnsを使うこと。
# ✅ 理由付き
dayjs禁止（バンドルサイズの問題で排除済み）。date-fnsを使うこと。理由が書いてあると、Claude Codeは例外的なケースでも適切に判断できます。
3. パターンと例を示す
# APIルートの命名規則
/api/v1/[resource] の形式を使用。
例:
- GET /api/v1/users — ユーザー一覧
- POST /api/v1/users — ユーザー作成
- GET /api/v1/users/:id — ユーザー詳細4. 禁止事項を明記する
# 禁止事項
- `any`型の使用禁止（unknownを使う）
- `console.log`をプロダクションコードに残さない
- `import *`は使わない
- jQuery系ライブラリの新規追加禁止5. 短く保つ
CLAUDE.mdは毎回のセッションで読み込まれるため、長すぎるとトークンを消費します。目安として500行以内に収めましょう。詳細な仕様はコード内のコメントやREADME.mdに任せ、CLAUDE.mdには「Claude Codeが判断に困るポイント」だけを書くのがベストです。
SES現場で使えるCLAUDE.mdテンプレート集
Webアプリケーション開発プロジェクト
# プロジェクト: [クライアント名]予約管理システム
React + TypeScript + Supabaseの予約管理SaaS。
# 開発環境
- Node.js 20 / pnpm
- `pnpm dev` で起動 (localhost:3000)
- Supabaseローカル: `supabase start`
# アーキテクチャ
- src/features/ 配下にドメインごとのモジュール
- 各featureは components/, hooks/, api/, types/ を持つ
- 共通UIは src/components/ui/ (shadcn/ui準拠)
# テスト方針
- ビジネスロジック: Vitest (カバレッジ80%以上)
- UI: Storybook + interaction tests
- E2E: Playwright (主要フローのみ)
- テスト実行: `pnpm test`
# DB操作ルール
- マイグレーションは supabase migration new [name]
- RLSポリシーは必ず設定する
- 直接SQLではなくSupabase clientを使う
# セキュリティ
- 認証: Supabase Auth (JWTベース)
- 環境変数は .env.local に配置 (.gitignore済み)
- APIキーをフロントエンドに露出させないSESインフラ運用プロジェクト
# プロジェクト: [クライアント名]インフラ管理
Terraform + AWS構成のインフラコード。
# 構成
environments/
├── dev/ # 開発環境
├── stg/ # ステージング
└── prod/ # 本番（変更は必ずPR経由）
modules/ # 再利用可能なTerraformモジュール
# コマンド
- `terraform plan` — 変更確認（必ず実行）
- `terraform apply` — 適用（prod以外）
- prod環境: GitHub Actionsからのみapply可能
# ルール
- prod環境のリソースは直接変更しない
- セキュリティグループの0.0.0.0/0は禁止
- タグ付け必須: Environment, Project, Owner
- コスト見積もりをPRに記載するレガシーシステム改修プロジェクト
# プロジェクト: [システム名] モダナイゼーション
Java 8 + Spring Boot 1.x → Spring Boot 3.x移行中。
# 現状
- Java 8のコードが大半（移行率: 約40%）
- 移行済みモジュール: user, auth, notification
- 未移行: order, payment, inventory
# 移行ルール
- 新規コードはJava 17+の構文を使用
- 移行時は必ずテストを追加（既存テストなし多数）
- 段階的に移行。一度に大きな変更をしない
- 移行前後でAPIの互換性を維持する
# ビルド
- `./gradlew build` — 全体ビルド
- `./gradlew :module-name:test` — モジュール単体テストチーム開発でのCLAUDE.md運用
Git管理のベストプラクティス
CLAUDE.mdはプロジェクトの重要なドキュメントです。必ずGitで管理しましょう。
# リポジトリルートのCLAUDE.mdはGit管理
git add CLAUDE.md
git commit -m "docs: CLAUDE.mdを追加"
# 個人設定は.claude/配下に
echo ".claude/" >> .gitignoreチームでCLAUDE.mdを更新する際のルール例：
- CLAUDE.mdの変更はPRで行う
- レビューで「この記述は本当に必要か」を確認
- 四半期ごとに棚卸しして不要な記述を削除
/initコマンドで自動生成
CLAUDE.mdをゼロから書くのが面倒なら、Claude Codeの/initコマンドを使いましょう。
> /initプロジェクトのコードを分析し、技術スタック・ディレクトリ構成・ビルドコマンドを自動的にCLAUDE.mdとして生成してくれます。生成後に手動で調整すれば、効率的にセットアップできます。
CLAUDE.mdのアンチパターン
避けるべき記述パターンも押さえておきましょう。
❌ 長すぎるCLAUDE.md
# NG: 500行を超えるドキュメント
（API仕様、DB設計、全テーブル定義をすべて記載...）→ トークンを大量消費し、重要な情報が埋もれます。詳細はREADME.mdや専用ドキュメントに分離しましょう。
❌ 曖昧な指示
# NG
コードは綺麗に書いてください。
パフォーマンスに気をつけてください。→ 具体的なルールに落とし込みましょう。「関数は50行以内」「N+1クエリを避ける」など。
❌ 矛盾する指示
# NG
- named exportを使うこと
- default exportを使うこと（コンポーネント）→ 条件を明確に分けましょう。「コンポーネントはdefault export、それ以外はnamed export」。
CLAUDE.mdと他の設定ファイルの関係
Claude Codeには複数の設定メカニズムがあります。使い分けを理解しましょう。
| 設定方法 | 用途 | 確実性 | 柔軟性 |
|---|---|---|---|
| CLAUDE.md | プロジェクトルール・コンテキスト | 中（AIが解釈） | 高 |
| Hooks | 確実に実行すべき自動化 | 高（決定論的） | 低 |
.claude/settings.json | Claude Code自体の設定 | 高 | 低 |
| プロンプト | その場限りの指示 | 低 | 最高 |
使い分けの基準：
- 毎回守るべきルール → CLAUDE.md
- 100%確実に実行すべき処理 → Hooks
- 一時的な指示 → プロンプト
詳しいHooksの活用法は「Claude Code Hooks活用ガイド」をご覧ください。
まとめ：CLAUDE.mdで開発体験を変える
CLAUDE.mdは、Claude Codeの「プロジェクト記憶」として機能する強力な仕組みです。
すぐに始められる3ステップ：
- プロジェクトルートで
/initを実行して雛形を生成 - コーディング規約・禁止事項・よく使うコマンドを追加
- Gitにコミットしてチームで共有
適切なCLAUDE.mdがあるだけで、Claude Codeの出力品質は劇的に向上します。SES現場では、新しいプロジェクトに参画した初日にCLAUDE.mdを確認（または作成）する習慣をつけることで、キャッチアップ速度と開発効率の両方を高められます。
関連記事
- Claude Code使い方入門 — Claude Codeの基本操作を学ぶ
- Claude Code実践テクニック10選 — CLAUDE.mdと組み合わせて使えるテクニック集
- Claude Code プロンプト設計術 — より効果的なプロンプトの書き方
- Claude Code Hooks活用ガイド — CLAUDE.mdと併用する自動化の仕組み
- Claude Code × チーム開発 — チームでの導入・運用パターン
出典・参考:
