結論：Claude Code の出力品質を最も左右するのはプロンプトでもモデルでもなく、CLAUDE.md の書き方だった。
Claude Code を導入したチームの中で「期待通りのコードが出る」チームと「毎回手直しが必要」なチームの差を調べると、CLAUDE.md の設計品質に行き着きます。
この記事では、プロジェクト規模別に使い分ける 7つの CLAUDE.md テンプレート を紹介します。個人スクリプトから大規模モノレポまで、コピーしてすぐ使える実践的なパターン集です。
環境・前提条件
- Claude Code CLI が導入済みであること
- シェル環境は macOS / Linux / WSL を想定
- 記事中のテンプレートは Markdown 形式で記述
1. CLAUDE.md とは何か──役割・読み込み順・スコープの仕組み
役割
CLAUDE.md は、Claude Code がコードを生成・編集する際に自動で読み込まれるプロジェクト指示書です。プロンプトに毎回書く必要がない「暗黙のコンテキスト」を一元管理できます。
主に以下を定義します。
- プロジェクトの技術スタック・アーキテクチャ方針
- コーディング規約・命名規則
- やってはいけない操作（アンチパターン）
- テスト・ビルド・デプロイに関するコマンドや制約
読み込み順とスコープの階層構造
CLAUDE.md は 3つのスコープ で配置でき、下位ほど優先度が高くマージされます。
| スコープ | パス例 | 用途 | 共有範囲 |
|---|---|---|---|
| ユーザーグローバル | ~/.claude/CLAUDE.md |
個人の好み（言語・スタイル） | 自分だけ |
| プロジェクトルート | ./CLAUDE.md |
技術スタック・規約 | チーム全体（Git管理） |
| サブディレクトリ | ./packages/api/CLAUDE.md |
パッケージ固有の制約 | チーム全体（Git管理） |
ポイント: サブディレクトリの CLAUDE.md は、Claude Code がそのディレクトリ内のファイルを操作するときに追加で読み込まれます。ルートの内容を上書きするのではなく、補足する設計にするのがベストです。
2. 個人スクリプト向け：ミニマル型テンプレート
想定規模: 1人 / ファイル数 1〜10 / 使い捨て〜小規模ツール
「書きすぎない」ことが最大のポイントです。個人スクリプトで長大な CLAUDE.md を書くのはオーバーエンジニアリングです。
# CLAUDE.md
## プロジェクト概要
CLIツール。標準入力からCSVを受け取り、集計結果をJSONで出力する。
## 技術スタック
- Python 3.12
- 外部ライブラリ不可（標準ライブラリのみ）
## コーディング規約
- 型ヒント必須
- 関数には1行のdocstringを書く
## ビルド・実行
- 実行: `python main.py < input.csv`
- テスト: `python -m pytest tests/`
テンプレートのサイズ目安: 10〜20行
必要なのは「何を作っているか」「使っていい道具は何か」「どう動かすか」の3点だけです。
3. 中規模Webアプリ向け：レイヤー分離型テンプレート
想定規模: 2〜5人 / ファイル数 50〜300 / Webアプリケーション
レイヤードアーキテクチャの境界を明示することで、Claude Code が「どのファイルにどのロジックを置くべきか」を正しく判断できるようになります。
# CLAUDE.md
## プロジェクト概要
社内向け在庫管理システム（SaaS）。
## 技術スタック
- Backend: TypeScript / NestJS / Prisma / PostgreSQL
- Frontend: TypeScript / Next.js (App Router) / Tailwind CSS v4
- テスト: Vitest (unit) / Playwright (E2E)
- CI: GitHub Actions
## アーキテクチャ方針
### ディレクトリ構造と責務
- `src/domain/` … ドメインモデル・ビジネスルール。外部依存禁止。
- `src/application/` … ユースケース。domain のみ import 可。
- `src/infrastructure/` … DB・外部API連携。Prisma Client はここだけ。
- `src/presentation/` … Controller / DTO / バリデーション。
### 依存方向（厳守）
presentation → application → domain ← infrastructure
### コーディング規約
- 変数・関数: camelCase / クラス: PascalCase
- `any` 禁止。`unknown` + 型ガードを使う。
- エラーは Result 型（neverthrow）で返す。throw しない。
- マジックナンバー禁止。定数は `src/constants/` に定義。
## やってはいけないこと
- `domain/` から `infrastructure/` を直接 import
- Prisma のモデル型をドメイン層に漏洩させる
- `console.log` でのデバッグ（logger を使う）
## テスト方針
- domain / application はユニットテスト必須（カバレッジ80%以上目標）
- infrastructure はインテグレーションテスト
- E2E は主要ユーザーフローのみ
## コマンド集
- 開発: `pnpm dev`
- テスト: `pnpm test`
- 単一テスト: `pnpm test -- --run src/path/to/file.test.ts`
- Lint: `pnpm lint`
- マイグレーション: `pnpm prisma migrate dev`
テンプレートのサイズ目安: 40〜80行
「依存方向」と「やってはいけないこと」のセクションが特に効きます。Claude Code はこれを守ったコードを高い精度で生成するようになります。
4. モノレポ・チーム開発向け：階層CLAUDE.md＋サブディレクトリ分割パターン
想定規模: 5人以上 / パッケージ数 3以上 / モノレポ構成
大規模になると、1ファイルにすべてを書くのは破綻します。ルートには共通方針だけを書き、各パッケージに固有の CLAUDE.md を置くのが鉄則です。
ルート CLAUDE.md（共通方針のみ）
# CLAUDE.md（ルート）
## プロジェクト概要
ECプラットフォーム。モノレポ（pnpm workspace）。
## 共通ルール
- TypeScript strict モード必須
- コミットメッセージ: Conventional Commits 形式
- PR は1機能1PR。500行以下を目安にする。
## パッケージ間依存
- shared → 他パッケージに依存しない
- api, web → shared に依存可
- api ↔ web の直接依存は禁止
## 共通コマンド
- 全体ビルド: `pnpm build`
- 全テスト: `pnpm test`
- 特定パッケージ: `pnpm --filter @app/api test`
サブディレクトリ CLAUDE.md（例：packages/api/）
# CLAUDE.md（packages/api）
## このパッケージの責務
REST API サーバー。認証・在庫・注文ドメインを提供。
## 追加の技術スタック
- NestJS v10 / Prisma v6 / PostgreSQL 16
## このパッケージ固有のルール
- エンドポイント追加時は OpenAPI デコレータを必ず付ける
- `src/modules/` 配下に機能単位でモジュールを作る
- DB マイグレーションは必ず `pnpm prisma migrate dev --name <説明>` で作成
## テスト
- `pnpm --filter @app/api test`
テンプレートのサイズ目安: ルート 20〜40行 ＋ 各パッケージ 15〜30行
5. 用途特化型テンプレート──3つのバリエーション
プロジェクト規模とは別軸で、Claude Code に特定のタスクをやらせるときに効くテンプレートです。ルートの CLAUDE.md に追記するか、~/.claude/CLAUDE.md に用途別セクションとして管理します。
5-1. コードレビュー特化型
## コードレビューモード
以下の観点でレビューしてください：
### 必ずチェックする項目
1. セキュリティ: SQLインジェクション・XSS・認証バイパスの可能性
2. パフォーマンス: N+1クエリ・不要な再レンダリング・メモリリーク
3. エラーハンドリング: 例外の握りつぶし・ユーザーへの情報漏洩
4. テスト: 境界値・異常系のテストケース不足
### レビュー出力形式
- 重大度（Critical / Warning / Info）を明記
- 該当行番号を示す
- 修正案をコード付きで提示
5-2. テスト生成特化型
## テスト生成モード
### 方針
- テストフレームワーク: Vitest
- AAA パターン（Arrange / Act / Assert）で構造化
- 1テストケース1アサーション を原則とする
### 必須テストケース
- 正常系: 代表的な入力での期待動作
- 境界値: 空配列・空文字・0・最大値
- 異常系: null/undefined・型不正・ネットワークエラー
- 冪等性: 同じ入力で同じ結果が返ること
### モック方針
- 外部APIコールは必ずモック化
- DB は in-memory SQLite またはモックリポジトリ
- 時刻依存のテストは `vi.useFakeTimers()` を使う
5-3. リファクタリング特化型
## リファクタリングモード
### 原則
- 外部から見た振る舞い（入出力）を変えない
- リファクタリング前に既存テストが通ることを確認
- 1コミット1リファクタリング（混ぜない）
### 優先的に適用するパターン
1. 関数の抽出（Extract Function）: 5行以上のネストは分離
2. 早期リターン（Guard Clause）: ネスト削減
3. マジックナンバーの定数化
4. 型の厳密化: `string` → ユニオン型 / ブランド型
### やってはいけないこと
- 機能追加をリファクタリングに混ぜる
- テストのないコードの構造変更（先にテストを書く）
- パフォーマンス最適化とリファクタリングの同時実行
6. アンチパターン：CLAUDE.md が肥大化して逆効果になるケース
CLAUDE.md は「書けば書くほどよい」わけではありません。以下のアンチパターンに注意してください。
❌ アンチパターン一覧
| パターン | 症状 | 対処法 |
|---|---|---|
| 全部入り型 | 1ファイルに全パッケージの詳細を記述。300行超。 | 階層分割（パターン4）に移行 |
| 追記オンリー型 | 矛盾する指示が共存。「any禁止」と「型は気にしなくてよい」が同居。 | 月次で棚卸し。不要な行を削除。 |
| コード埋め込み型 | サンプルコードを50行以上貼り付け。 | 例は最小限（5行以内）にし、詳細は別ドキュメントを参照。 |
| 願望リスト型 | 「可読性の高いコードを書いてください」のような曖昧な指示の羅列。 | 具体的なルール（「関数は30行以内」「ネスト3段以内」）に書き換え。 |
| 秘密情報混入型 | APIキーやDBのパスワードを CLAUDE.md に記載。 | 環境変数名のみ記載。.env を参照するよう指示。 |
適切なサイズの目安
- 個人プロジェクト: 10〜20行
- チーム中規模: 40〜80行
- モノレポ（ルート）: 20〜40行 + 各パッケージ 15〜30行
- 合計で500行を超えたら赤信号
7. まとめ──プロジェクト初日に15分で CLAUDE.md を整備するチェックリスト
以下の3点を押さえれば、Claude Code の出力品質は大きく向上します。
- 規模に合ったテンプレートを選ぶ。 個人スクリプトならミニマル型（10行）、チーム開発ならレイヤー分離型（40〜80行）、モノレポなら階層分割。過不足なく書くことが最重要です。
- 「やってはいけないこと」を必ず書く。 Claude Code は「やるべきこと」よりも「やってはいけないこと」に対して忠実に従う傾向があります。禁止事項を明記しましょう。
- 月に1回、棚卸しする。 技術スタックの変更、ルールの追加・廃止を反映し、矛盾や肥大化を防ぎましょう。CLAUDE.md もコードと同じく継続的にメンテナンスするものです。
🚀 初日15分チェックリスト
□ プロジェクト概要を1〜2行で書く
□ 技術スタックを列挙する
□ ディレクトリ構造と各ディレクトリの責務を書く
□ 依存方向のルールを書く
□ コーディング規約を5項目以内で書く
□ 「やってはいけないこと」を3項目以上書く
□ ビルド・テスト・実行コマンドを書く
□ モノレポなら階層分割が必要か判断する
参考リンク
- Claude Code 公式ドキュメント – Memory – CLAUDE.md の仕組みと配置方法の公式解説
- Anthropic公式 – Claude Code Overview – Claude Code の全体像
- Claude Code Best Practices – Anthropic 公式のベストプラクティスガイド