CLAUDE.md設計パターン集 — プロジェクト規模別・7つのテンプレートと設計意図を全公開

CLAUDE.mdは「AIへの指示書」ではなく「チームの判断基準の言語化」である——この視点を持つだけで、Claude Codeの出力精度は劇的に変わります。

本記事では、プロジェクト規模別に7つのCLAUDE.mdテンプレートを提示し、「なぜこの項目を書いたのか」「なぜ書かなかったのか」という設計意図まで踏み込んで解説します。コピペして使えるテンプレート集であると同時に、自分のプロジェクトに最適なCLAUDE.mdを設計するための思考フレームワークとしてお使いください。

環境・前提条件

• Claude Code CLI版を利用していること
• CLAUDE.mdファイルの基本的な役割を理解していること（公式ドキュメント参照）
• Git管理下のプロジェクトで作業していること

なぜCLAUDE.mdの設計が開発品質を左右するのか

多くのエンジニアがCLAUDE.mdを「プロンプトの延長」として捉えています。しかし、本質的にはCLAUDE.mdはコードベースに埋め込まれた意思決定の記録です。

指示書と判断基準の違い

観点	指示書（❌ よくある書き方）	判断基準（✅ 目指す書き方）
例	「関数名はcamelCaseで書いて」	「外部APIとの境界ではsnake_caseに変換し、内部ではcamelCaseを使う。理由: APIレスポンスとの対応を明確にするため」
曖昧な状況	判断できず毎回質問される	コンテキストから自律的に判断できる
保守性	ルールが増え続け破綻する	原則が明確なので例外も判断できる

Claude Codeは**「なぜそうするのか」が書いてあると、書かれていない類似状況にも正しく判断を適用**します。ルールの羅列より、判断の根拠を書くほうが出力精度は高くなります。

規模別テンプレート7選 — 構成要素マトリクス

まず、7つのプロジェクト規模と、CLAUDE.mdに含めるべき構成要素の関係を俯瞰します。

◎ = 必須 / ○ = 推奨 / △ = あれば良い / × = 不要

では、各テンプレートを見ていきましょう。

---

1. 個人スクリプト（〜500行）

# CLAUDE.md

## このプロジェクト
CSV売上データを集計してSlackに投稿するPythonスクリプト。
自分だけが使う。動けばよい。

## 技術スタック
- Python 3.12 / pandas / slack_sdk

## 方針
- 型ヒントは省略してよい
- エラーハンドリングは最低限（printしてsys.exit(1)）
- テストは不要。動作確認はスクリプト直接実行で行う

設計意図: 「動けばよい」と明示することで、Claude Codeが過剰な抽象化・テスト生成・型定義を行うのを防ぎます。個人スクリプトの最大の敵はオーバーエンジニアリングです。

---

2. 副業MVP（1人開発・数週間リリース）

# CLAUDE.md

## プロダクト概要
フリーランス向け請求書自動生成SaaS。Stripeで課金。
MVP段階のため、コア機能（請求書PDF生成）以外は最小限に。

## 技術スタック
- Next.js 14 (App Router) / TypeScript / Prisma / PostgreSQL
- デプロイ: Vercel + Supabase

## アーキテクチャ方針
- app/ ディレクトリ配下にfeatureごとにディレクトリを切る
- Server Actionsを優先し、API Routesは外部webhook受信のみに使う
- 理由: MVPではサーバー/クライアントの境界をシンプルに保ちたい

## コーディング規約
- コンポーネントは named export のみ（default export禁止）
- DB操作は lib/db/ に集約。コンポーネントから直接Prismaを呼ばない

## やらないこと（MVP期間中）
- i18n対応
- ダークモード
- E2Eテスト（ユニットテストのみ書く）

設計意図: 「やらないこと」セクションが鍵です。Claude Codeはデフォルトで「良いプラクティス」を適用しようとするため、MVP段階で不要な機能を明示的に除外しないと、スコープが際限なく膨らみます。

---

3. スタートアップ（3〜5人チーム）

# CLAUDE.md

## プロダクト
B2B SaaS - 製造業向け在庫管理システム

## 技術スタック
- バックエンド: Go 1.22 / Echo / sqlc
- フロントエンド: React 18 / TypeScript / TanStack Query
- インフラ: AWS ECS Fargate / RDS (PostgreSQL 15)

## アーキテクチャ
### バックエンド
- レイヤードアーキテクチャ: handler → usecase → repository
- handler: HTTPリクエストのバリデーションとレスポンス整形のみ
- usecase: ビジネスロジック。他のusecaseを呼び出してよいが、循環依存は禁止
- repository: DB操作。sqlcで生成されたコードをラップする

### フロントエンド
- src/features/ 配下にドメインごとにディレクトリ
- API呼び出しは必ずカスタムhook経由（コンポーネントで直接fetchしない）

## テスト戦略
- バックエンド: usecase層のユニットテスト必須。repositoryはモック
- フロントエンド: カスタムhookのテスト推奨。UIコンポーネントのテストは任意
- テストコマンド: `make test`（バックエンド）、`pnpm test`（フロントエンド）

## コミット規約
- Conventional Commits形式: feat/fix/docs/refactor/test
- 日本語は使わない（英語のみ）

設計意図: チーム開発では「暗黙の合意」が最大のリスクです。レイヤーの責務を明文化することで、Claude Codeだけでなく新メンバーのオンボーディングにも機能します。

---

4. 中規模チーム（10人以上）

# CLAUDE.md

## プロダクト
金融機関向けコンプライアンス管理プラットフォーム

## 必読ドキュメント
- アーキテクチャ決定記録: docs/adr/ 配下を必ず確認すること
- API設計ガイドライン: docs/api-guidelines.md
- セキュリティポリシー: docs/security-policy.md

## 禁止事項（厳守）
- 顧客データをログに出力しない（個人情報保護法対応）
- ORM の raw query は使用禁止（SQLインジェクション防止）
- 新しい外部ライブラリの追加は docs/adr/ にADRを書いてから
- env変数を直接参照しない。必ず config/ 経由で取得する

## コードレビュー基準
以下を満たさないPRはマージしない:
1. 関連するユニットテストが追加/更新されている
2. 既存のCIが全てパスしている（`make ci`で確認）
3. 公開APIの変更にはOpenAPIスキーマの更新が含まれている

## テスト戦略
- ユニットテスト: カバレッジ80%以上を維持
- 統合テスト: API境界のテストを重点的に
- テスト実行: `make test-unit` / `make test-integration`
- CI: GitHub Actions（PR作成時に自動実行）

設計意図: 中規模以上では「禁止事項」の重要度が跳ね上がります。特にセキュリティ・コンプライアンスに関する制約は、Claude Codeが自動生成するコードで意図せず違反するリスクがあるため、最上位に記載します。また、CLAUDE.md自体を軽量に保ち、詳細は別ドキュメントへの参照にとどめるのがポイントです。

---

5. モノレポ

# CLAUDE.md（ルート）

## リポジトリ構成
このリポジトリはpnpm workspacesによるモノレポです。

## パッケージ一覧
- apps/web - Next.jsフロントエンド → apps/web/CLAUDE.md を参照
- apps/api - NestJSバックエンド → apps/api/CLAUDE.md を参照
- packages/ui - 共有UIコンポーネント → packages/ui/CLAUDE.md を参照
- packages/shared - 共有型定義・ユーティリティ

## 全パッケージ共通ルール
- パッケージ間の依存は packages/ → apps/ の方向のみ（apps間の相互依存禁止）
- 共有型定義は packages/shared/src/types/ に置く
- コミット時は変更したパッケージ名をscopeに含める: `feat(web): ...`

## 作業前の確認コマンド
- 全体ビルド: `pnpm build`
- 全体テスト: `pnpm test`
- 特定パッケージ: `pnpm --filter @myapp/web test`

設計意図: モノレポではCLAUDE.mdも階層化します。ルートには全体ルールのみを置き、各パッケージ固有のルールはサブディレクトリのCLAUDE.mdに委譲します。Claude Codeは作業ディレクトリのCLAUDE.mdを自動で読み込むため、この構造と相性が良いです。

---

6. OSSプロジェクト

# CLAUDE.md

## プロジェクト概要
Markdownパーサーライブラリ（TypeScript）。
GitHub Starは外部コントリビューターの参加意欲に影響するため、
DX（開発者体験）を最優先に設計する。

## コントリビューション文脈
このCLAUDE.mdはメンテナーがClaude Codeで作業する際のガイドです。
外部コントリビューター向けにはCONTRIBUTING.mdを参照してください。

## API設計原則
- 破壊的変更は semver major で管理。CHANGELOG.mdに必ず記載
- public APIは最小限に。内部実装は`internal/`配下に隠蔽
- 新しいpublic APIには必ずJSDocを書く（使用例を含む）

## テスト戦略
- 全public APIに対するテスト必須
- スナップショットテストでMarkdown変換結果を検証
- `pnpm test` で全テスト実行
- `pnpm test:watch` で開発中の変更を監視

## 禁止事項
- node_modules内のコードを直接参照しない
- devDependenciesを dependencies に入れない
- any型の使用禁止（unknown + 型ガードを使う）

設計意図: OSSでは「後方互換性」が最重要です。Claude Codeが善意でAPIシグネチャを変更してしまうケースを防ぐため、破壊的変更のルールを明示します。

---

7. レガシー改修

# CLAUDE.md

## プロジェクト概要
10年稼働している社内発注管理システムのモダナイゼーション。
PHP 7.4 + jQuery → Laravel 11 + React 段階移行中。

## 現在のアーキテクチャ状態
- `/legacy/` : 旧コード（PHP 7.4）。修正はバグ修正のみ許可
- `/src/` : 新コード（Laravel 11）。新機能はここに書く
- `/resources/js/` : React移行中。jQueryとReactが混在している

## 最重要ルール
- legacy/ 配下のリファクタリングは絶対にしない（動いているコードに触らない）
- 新旧コードの接続は app/Bridge/ 経由で行う
- legacy/のテーブル構造は変更禁止。新テーブルを追加してビューで統合する

## 移行戦略
段階的にページ単位で移行する（ストラングラーフィグパターン）。
1. 新ルートを Laravel で作成
2. 旧画面と同等の機能を React で実装
3. nginx で新旧ルーティングを切り替え
4. 旧コードのルートを削除

## テスト
- 新コード: Feature Test 必須（`php artisan test`）
- legacy: 手動テストのみ（自動テスト基盤なし）

設計意図: レガシー改修でClaude Codeが最もやりがちなミスは、善意のリファクタリングです。「動いている旧コードに触るな」を最上位ルールとして明記します。

---

各テンプレートの設計意図 — 「書かなかった」理由

テンプレートに共通する設計判断の背景を整理します。

書かない判断が正しいケース

• 言語・フレームワークの標準規約: ESLintやgo fmtが強制するルールをCLAUDE.mdに重複して書く必要はありません
• 自明なベストプラクティス: 「変数名はわかりやすく」のような抽象的な指示は、書いてもClaude Codeの振る舞いを変えません
• 頻繁に変わる実装詳細: スプリントごとに変わるような内容はCLAUDE.mdに入れず、チケットやプロンプトで都度伝えるべきです

アンチパターン集

❌ アンチパターン1: 百科事典型

# 悪い例
## コーディング規約
- インデントはスペース2つ（←.editorconfigで設定済み）
- セミコロンは省略（←ESLint+Prettierで強制済み）
- importの順番はビルトイン→外部→内部（←ESLint auto-fixで対応済み）
... （100行続く）

問題: ツールが既に強制しているルールを書くと、CLAUDE.mdの信号対雑音比が下がります。Claude Codeは長文のCLAUDE.mdで重要なルールを見落とすことがあります。

❌ アンチパターン2: 矛盾放置型

## 方針
- シンプルさを最優先にする
## テスト
- カバレッジ100%を目指す
- 全メソッドにユニットテスト・統合テスト・E2Eテストを書く

問題: 「シンプルさ優先」と「カバレッジ100%」は多くの場合矛盾します。Claude Codeはどちらを優先すべきかわからず、中途半端な出力になります。

❌ アンチパターン3: コピペ神殿型

他のプロジェクトのCLAUDE.mdをそのまま流用し、自プロジェクトの実態と乖離している状態です。存在しないディレクトリへの参照や、使っていないツールのルールが混在すると、Claude Codeが混乱してハルシネーションを起こす原因になります。

CLAUDE.mdのGit管理戦略

.claude/ ディレクトリ構成

管理のベストプラクティス

項目	推奨方針
ルートCLAUDE.md	Git管理する。全メンバーが参照する「判断基準の正本」
サブディレクトリCLAUDE.md	Git管理する。パッケージ担当者が責任を持つ
~/.claude/CLAUDE.md	Git管理しない。個人の好み（エディタ設定等）を記載
.claude/settings.json	Git管理する。許可コマンド等のチーム共有設定

ブランチ別の使い分け

CLAUDE.md自体をブランチで分ける必要は基本的にありません。ただし以下のケースでは例外的にブランチ上で一時変更することがあります。

• 大規模リファクタリングブランチ: 移行期間中だけ「旧実装パターンを使わない」ルールを追加
• 実験ブランチ: 新しいアーキテクチャを試す際に一時的に方針を変更

いずれもmainへのマージ時にCLAUDE.mdの差分をレビューし、恒久化するか元に戻すかを判断してください。

まとめ — CLAUDE.mdは「生きたドキュメント」として育てる

• CLAUDE.mdは指示書ではなく判断基準。「なぜそうするか」を書くことで、Claude Codeは書かれていない状況にも正しく対応できるようになります
• プロジェクト規模に応じて構成要素を増減させる。個人スクリプトに禁止事項は不要であり、レガシー改修にはアーキテクチャ制約が不可欠です。過不足なく書くことが最重要です
• 定期的に見直す。スプリントレトロスペクティブや月次で「CLAUDE.mdに追加・削除すべき項目はないか」をチームで議論し、コードベースの進化とともにCLAUDE.mdも育てましょう

参考リンク

• Claude Code公式ドキュメント - Memory
• Claude Code公式ドキュメント - Settings
• Claude Code公式ドキュメント - Best practices for agentic coding