結論：CLAUDE.mdは「プロジェクト類型」に合わせて設計しないと逆効果になる
CLAUDE.mdは「書けば効く」ものではありません。プロジェクトの性質に合わない指示はむしろClaude Codeの出力品質を下げます。
この記事では、7つのプロジェクト類型ごとに最適化されたCLAUDE.mdテンプレートと、実際に品質が劣化した5つのアンチパターン、そして段階的にCLAUDE.mdを育てる運用フローを紹介します。
読み終わるころには、あなたのプロジェクトに最適なCLAUDE.mdの骨格が手に入るはずです。
環境・前提条件
- Claude Code CLI版を利用していること
- プロジェクトルートに
CLAUDE.mdを配置する運用を想定 - Git管理下のプロジェクトであること
- 本記事のテンプレートはすべてClaude Code公式のCLAUDE.md仕様に準拠
なぜCLAUDE.mdの設計が重要なのか
Claude Codeはセッション開始時にCLAUDE.mdを読み込み、その内容をコンテキストとして保持します。つまり、CLAUDE.mdの内容は毎回のリクエストでトークンを消費する常駐コストです。
トークン効率と出力精度の関係
私が複数プロジェクトで検証した体感ベースの傾向をまとめます。
| CLAUDE.mdの状態 | トークン消費 | 出力精度の傾向 |
|---|---|---|
| 空（未設定） | 最小 | プロジェクト文脈を欠いた汎用的な回答になりがち |
| 適切に設計（300〜800語） | 中程度 | コードスタイル・アーキテクチャに沿った出力が得られやすい |
| 過剰に記述（1500語超） | 大 | 指示同士が競合し、優先度が曖昧になる傾向 |
| 的外れな記述 | 中〜大 | 関係ない制約に引きずられ、品質が下がることがある |
目安として、CLAUDE.mdは300〜800語程度に収めるのが効果的と感じています。これはあくまで私の経験則であり、プロジェクト規模や複雑さによって変わります。
CLAUDE.mdの構造設計
まず、CLAUDE.mdを構成する基本セクションとその関係を整理します。
重要な原則：上位セクション（role, architecture, constraints）が下位セクション（codeStyle, testing）を制約する関係になっています。上位が曖昧だと下位の指示がブレます。
5つの基本セクション
| セクション | 役割 | 記述量の目安 |
|---|---|---|
| role | このプロジェクトが何で、AIに何を期待するか | 2〜3文 |
| architecture | 技術スタック、ディレクトリ構成、主要な設計判断 | 5〜10行 |
| constraints | やってはいけないこと、守るべきルール | 3〜7項目 |
| codeStyle | 命名規則、フォーマット、import順など | 3〜5項目 |
| testing | テストの書き方、実行方法、カバレッジ方針 | 3〜5項目 |
7つのプロジェクト類型別テンプレート
類型1：API開発（REST/GraphQL）
# CLAUDE.md
## Role
ECサイトのバックエンドAPI（REST）を開発するプロジェクト。
NestJS + TypeScript + Prisma + PostgreSQL構成。
## Architecture
- src/modules/ 配下にドメインごとのモジュール（users, products, orders）
- 各モジュールは controller / service / repository の3層
- DTOはclass-validatorでバリデーション
- エラーは HttpException を継承したカスタム例外を使う
## Constraints
- データベースへの直接クエリは禁止。必ずPrisma経由
- controllerにビジネスロジックを書かない
- レスポンス型は必ずDTO経由で返す（エンティティを直接返さない）
## Code Style
- 変数・関数: camelCase / クラス: PascalCase
- async/awaitを使用（.then()チェーン禁止）
- importは外部 → 内部の順
## Testing
- テストコマンド: `npm run test`
- 各serviceに対してunit testを書く
- E2Eテストはsupertest使用。`npm run test:e2e`
ポイント： API開発では「層の責務分離」と「レスポンス形式の制約」が最も効果的です。これらがないと、Claude Codeはcontrollerにロジックを書いたり、エンティティをそのまま返すコードを生成しがちです。
類型2：フロントエンド（React/Next.js）
# CLAUDE.md
## Role
SaaS管理画面のフロントエンド。Next.js 14 App Router + TypeScript。
## Architecture
- app/ 配下にルーティング（App Router）
- components/ui/ : 汎用UIコンポーネント（Button, Modal等）
- components/features/ : 機能固有コンポーネント
- hooks/ : カスタムフック
- 状態管理: Zustand（グローバル） + React Hook Form（フォーム）
- スタイリング: Tailwind CSS
## Constraints
- "use client" は必要な場合のみ。Server Componentをデフォルトとする
- anyの使用禁止
- コンポーネントのpropsは必ず型定義する
- 直接fetchせずAPI呼び出しは lib/api/ のラッパー経由
## Code Style
- コンポーネント: 名前付きexport（export default禁止）
- Tailwindのクラス順序: layout → spacing → typography → color
## Testing
- テストコマンド: `npm run test`
- Vitest + Testing Library
- ユーザー操作ベースのテストを書く（実装詳細をテストしない）
ポイント： フロントエンドでは「Server Component vs Client Component の判断基準」を明記することが非常に重要です。
類型3：データパイプライン
# CLAUDE.md
## Role
日次バッチでデータを収集・変換・格納するETLパイプライン。Python 3.12。
## Architecture
- src/extractors/ : データソース別の取得ロジック
- src/transformers/ : 変換・クレンジング処理
- src/loaders/ : データベース・S3への書き込み
- src/orchestrator.py : パイプライン実行順序の管理
- 設定: YAML（config/）で環境ごとに分離
## Constraints
- pandasのDataFrameをグローバル変数で持ち回さない
- 各ステップは冪等性を保証する（再実行しても結果が同じ）
- ログは標準のloggingモジュール。printデバッグ禁止
- 機密情報は環境変数から取得（ハードコード禁止）
## Code Style
- 型ヒント必須
- 関数のdocstring必須（Google style）
## Testing
- テストコマンド: `pytest`
- 各transformer関数に対してunit testを書く
- テスト用のフィクスチャデータは tests/fixtures/ に配置
ポイント： データパイプラインでは「冪等性」と「ステップ間のデータ受け渡し方針」を明記することで、再実行耐性のあるコードが生成されやすくなります。
類型4：モノレポ
# CLAUDE.md
## Role
フロント（Next.js）・バックエンド（NestJS）・共通パッケージを含むモノレポ。
pnpm workspace + Turborepo構成。
## Architecture
- apps/web/ : Next.jsフロントエンド
- apps/api/ : NestJSバックエンド
- packages/shared/ : 共通の型定義・ユーティリティ
- packages/ui/ : 共通UIコンポーネント
- packages/config/ : ESLint・TypeScript設定
## Constraints
- パッケージ間の依存は packages/shared 経由のみ。apps同士は直接参照しない
- 新しいパッケージ追加時は pnpm-workspace.yaml を更新する
- 共通の型は packages/shared/src/types/ に定義
## Code Style
- 各パッケージのルールはそのパッケージ内の設定に従う
## Testing
- ルートから: `pnpm run test --filter=<package>`
- CIでは `pnpm run test --filter=...[HEAD~1]` で変更パッケージのみテスト
ポイント： モノレポでは「パッケージ間の依存ルール」が最重要です。これがないとClaude Codeはapps同士を直接importするコードを生成することがあります。
類型5：ライブラリ/SDK
# CLAUDE.md
## Role
外部開発者が使うTypeScript製のHTTPクライアントライブラリ。
## Architecture
- src/client.ts : メインのClientクラス
- src/resources/ : APIリソースごとのクラス（Users, Projects等）
- src/types/ : 公開型定義
- src/errors/ : カスタムエラークラス
## Constraints
- 公開APIの破壊的変更は禁止（semverを厳守）
- 外部依存は最小限（現在: undici のみ）
- Node.js 18+ とブラウザ両対応（DOM APIに依存しない）
- すべてのpublic関数にJSDocコメント必須
## Code Style
- export する型は types/ に集約
- internal な関数は _ prefix
## Testing
- テストコマンド: `npm run test`
- 公開APIの全メソッドにテストを書く
- モックサーバー（msw）を使用
類型6：インフラ/IaC
# CLAUDE.md
## Role
AWS上のインフラをTerraformで管理するIaCプロジェクト。
## Architecture
- envs/dev/, envs/staging/, envs/prod/ : 環境別ルートモジュール
- modules/ : 再利用可能なTerraformモジュール
- modules/networking/ : VPC, サブネット, セキュリティグループ
- modules/compute/ : ECS, Lambda
- modules/storage/ : RDS, S3, DynamoDB
## Constraints
- リソースのハードコードは禁止。必ず変数化する
- stateファイルはS3 + DynamoDBでリモート管理
- セキュリティグループで 0.0.0.0/0 の許可は禁止（明示的に許可されたもの以外）
- destroyを伴う変更にはコメントで理由を記載
## Code Style
- リソース命名: {project}-{env}-{resource}-{purpose}
- 変数にはdescriptionとtypeを必ず定義
## Testing
- `terraform validate` と `terraform plan` を確認
- tflintによる静的解析
類型7：個人開発/プロトタイプ
# CLAUDE.md
## Role
個人開発のタスク管理Webアプリ。速度優先でプロトタイピング中。
## Architecture
- Next.js + Supabase（認証・DB）
- 1ファイル1機能で小さく保つ
- ORMは使わずSupabase JSクライアント直接利用
## Constraints
- 過度な抽象化をしない（現時点ではベタ書きOK）
- 型定義は最低限（interfaceよりtype推奨）
- エラーハンドリングは最低限のtry-catchで十分
## Code Style
- シンプルさ優先。デザインパターンの適用は不要
## Testing
- 現時点ではテスト不要。動作確認はブラウザで手動
ポイント： 個人開発では**「やらなくていいこと」を明示する**のが重要です。これがないとClaude Codeは過度に堅牢なコードを生成し、プロトタイピングの速度が落ちます。
類型別の重点セクション比較
アンチパターン集：品質が劣化した5つのCLAUDE.md記述例
❌ アンチパターン1：「全知全能」型
# 悪い例
あなたは世界最高のフルスタックエンジニアです。
どんな問題でも最適な解決策を提示してください。
コードは完璧でバグがないようにしてください。
なぜダメか： 具体的な制約がないため、Claude Codeは「何でもあり」の状態になります。結果として、プロジェクトの既存コードスタイルを無視した出力が増えます。
❌ アンチパターン2：「百科事典」型
# 悪い例（2000語超の巨大CLAUDE.md）
## Git運用ルール（20行）
## コミットメッセージ規約（15行）
## PRレビュー基準（20行）
## デプロイフロー（25行）
## 障害対応手順（30行）
## コーディング規約（50行）
...
なぜダメか： トークンを大量に消費し、指示同士が競合します。Claude Codeは「コード生成」が主タスクなので、Git運用やデプロイ手順は別のドキュメントに分離すべきです。
❌ アンチパターン3：「矛盾」型
# 悪い例
## Constraints
- コードはシンプルに保つこと
- すべての関数にエラーハンドリングを実装すること
- すべての関数にログ出力を追加すること
- すべての関数にバリデーションを追加すること
- すべての関数にキャッシュ機構を検討すること
なぜダメか： 「シンプルに保て」と「すべてに○○を追加」が矛盾しています。Claude Codeはすべてを満たそうとして、過度に複雑なコードを生成します。
❌ アンチパターン4：「技術スタック羅列」型
# 悪い例
## Tech Stack
React, Next.js, TypeScript, Tailwind CSS, Prisma, PostgreSQL,
Redis, Docker, Kubernetes, GitHub Actions, Terraform, Datadog,
Sentry, Stripe, SendGrid, AWS S3, CloudFront, Lambda, SQS, SNS
なぜダメか： 羅列だけでは「どの技術をどこでどう使うか」がわかりません。Claude Codeは文脈なしにこれらの技術を混ぜたコードを生成することがあります。
❌ アンチパターン5：「コピペ放置」型
# 悪い例（6ヶ月前に書いて放置）
## Architecture
- pages/ 配下にルーティング ← 実はApp Routerに移行済み
- Redux Toolkit で状態管理 ← 実はZustandに移行済み
- styled-components でスタイリング ← 実はTailwindに移行済み
なぜダメか： 現実と乖離したCLAUDE.mdは、古いパターンのコードを生成させてしまいます。**CLAUDE.mdはプロジェクトとともに更新する「生きたドキュメント」**であるべきです。
段階的に育てるCLAUDE.md運用フロー
CLAUDE.mdは最初から完璧を目指す必要はありません。プロジェクトの成長に合わせて段階的に育てましょう。
初期（プロジェクト立ち上げ〜2週間）
書くもの： roleとarchitectureのみ
# CLAUDE.md
## Role
○○を開発するプロジェクト。[技術スタック]構成。
## Architecture
- [ディレクトリ構成を3〜5行で]
この段階では「Claude Codeにプロジェクトの文脈を伝える」ことだけに集中します。
中期（2週間〜2ヶ月）
追加するもの： constraintsとcodeStyle
Claude Codeに対して繰り返し同じ修正指示をしている内容をconstraintsに昇格させます。
「またcontrollerにロジック書いてる…」→ constraintsに追加
「またany使ってる…」→ constraintsに追加
成熟期（2ヶ月以降）
やること： 削除と洗練
- もう違反しなくなった制約を削除（トークン節約）
- testingセクションを充実させる
- チームで使っている場合、メンバーのフィードバックを反映
定期メンテナンスの目安： 月に1回、CLAUDE.mdの内容が現実のプロジェクトと一致しているか確認しましょう。
付録：コピペで使えるCLAUDE.mdスターターキット
どのプロジェクトでも使える最小構成のテンプレートです。コメント部分を自分のプロジェクトに合わせて書き換えてください。
# CLAUDE.md
## Role
<!-- 1〜2文でプロジェクトの概要を書く -->
<!-- 例: BtoB SaaSの請求管理システムのバックエンドAPI。 -->
## Architecture
<!-- 技術スタックを1行で -->
<!-- 例: NestJS + TypeScript + Prisma + PostgreSQL -->
<!-- 主要なディレクトリ構成を3〜5行で -->
<!-- 例:
- src/modules/ : ドメインごとのモジュール
- src/common/ : 共通ユーティリティ、ガード、フィルター
- prisma/ : スキーマとマイグレーション
-->
## Constraints
<!-- Claude Codeが繰り返し違反する内容を3〜5項目で -->
<!-- 例:
- controllerにビジネスロジックを書かない
- anyの使用禁止
- エンティティを直接レスポンスとして返さない
-->
## Code Style
<!-- プロジェクト固有の命名規則・フォーマットルール -->
<!-- 例:
- 変数・関数: camelCase
- ファイル名: kebab-case
- async/await使用（.then禁止）
-->
## Testing
<!-- テスト実行コマンドと方針 -->
<!-- 例:
- テストコマンド: npm run test
- serviceごとにunit test必須
-->
まとめ
- CLAUDE.mdはプロジェクト類型に合わせて設計する。 API開発なら層の責務分離、フロントエンドならServer/Client Componentの判断基準、個人開発なら「やらなくていいこと」が最重要セクションになる
- 300〜800語に収め、上位セクション（role→architecture→constraints）から書く。 巨大なCLAUDE.mdはトークンを浪費し、指示の競合を引き起こす
- CLAUDE.mdは「生きたドキュメント」として段階的に育てる。 初期はroleとarchitectureだけで十分。繰り返し指摘する内容をconstraintsに昇格させ、不要になった制約は削除する
参考リンク
- Claude Code 公式ドキュメント - Memory - CLAUDE.mdの仕様と配置場所の公式リファレンス
- Anthropic公式 - Claude Code Overview - Claude Codeの全体像
- Claude Code 公式ドキュメント - Best Practices - CLAUDE.mdの書き方を含むベストプラクティス