CLAUDE.md設計パターン集 ― プロジェクト規模別に使い分ける7つのテンプレート

結論：CLAUDE.mdは「書き方」で生産性が3倍変わる

Claude Codeの実力を引き出すも殺すも、CLAUDE.mdの書き方次第だと3ヶ月使い込んで痛感しました。

この記事では、プロジェクト規模別に最適化した7つのCLAUDE.mdテンプレートを全文公開します。個人スクリプトからモノレポ・OSS運用まで、そのまま使えるテンプレートと「なぜその構成なのか」の設計意図を解説します。

読み終えたあと、あなたのプロジェクトに合ったCLAUDE.mdをすぐに作れるようになるはずです。

環境・前提条件

• Claude Code CLI版（2025年7月時点の仕様に基づく）
• CLAUDE.mdファイルはプロジェクトルートに配置
• Git管理下での運用を前提

1. CLAUDE.mdとは何か ― プロジェクトの『憲法』としての役割

CLAUDE.mdは、Claude Codeがプロジェクトのコンテキストを理解するために読み込むメモリファイルです。

通常のREADME.mdが「人間向けの説明書」なのに対し、CLAUDE.mdは「AIエージェント向けの行動指針」として機能します。私はこれを**プロジェクトの『憲法』**と呼んでいます。

CLAUDE.mdに書くべき情報の分類

大きく分けて以下の4カテゴリがあります。

カテゴリ	内容例	重要度
プロジェクト概要	技術スタック、ディレクトリ構造	★★★
コーディング規約	命名規則、フォーマッタ設定、使用パターン	★★★
禁止操作	触ってはいけないファイル、実行禁止コマンド	★★★
テスト・ビルド方針	テストコマンド、CI/CDの概要	★★☆

配置場所と読み込み優先度

Claude Codeは以下の3階層のCLAUDE.mdを認識します。

• ~/.claude/CLAUDE.md — ユーザーグローバル設定（全プロジェクト共通）
• ./CLAUDE.md — プロジェクトルート設定（Git管理推奨）
• ./サブディレクトリ/CLAUDE.md — サブディレクトリ設定（モノレポで活躍）

下位のファイルほど優先度が高く、上位の設定を上書きします。

2. プロジェクト規模別 ― 7つの設計パターン

ここからが本題です。プロジェクトの性質と規模に応じて、CLAUDE.mdに書くべき内容は大きく変わります。

以下、7パターンそれぞれのテンプレートと設計意図を解説します。

3. パターン別テンプレート全文公開

---

パターン①：個人スクリプト（〜500行）

想定: 自動化スクリプト、ちょっとしたツール、学習用コード

# CLAUDE.md

## プロジェクト概要
Python製のCSV変換スクリプト。入力CSVのカラムを変換ルールに従ってマッピングし、新しいCSVを出力する。

## 技術スタック
- Python 3.12
- 外部ライブラリ: pandas, click

## コマンド
- 実行: `python main.py --input data.csv --output result.csv`
- テスト: `pytest tests/`

## 規約
- 型ヒントを必ずつける
- docstringはGoogle style

設計意図: 最小構成。書きすぎるとトークンの無駄になるため、概要・スタック・コマンド・最低限の規約に絞ります。

---

パターン②：CLIツール

想定: npm/pip等で配布するCLIツール、1人〜2人開発

# CLAUDE.md

## プロジェクト概要
`fmtx` — Markdown テーブルを自動整形するCLIツール（Rust製）。

## 技術スタック
- Rust 1.79 (edition 2024)
- clap v4（CLI引数パーサー）
- 配布: crates.io

## ディレクトリ構成
- `src/main.rs` — エントリポイント
- `src/formatter/` — 整形ロジック
- `src/cli/` — 引数パース・バリデーション
- `tests/` — 統合テスト（fixtureベース）

## コマンド
- ビルド: `cargo build`
- テスト全体: `cargo test`
- 単一テスト: `cargo test test_name`
- lint: `cargo clippy -- -D warnings`
- フォーマット: `cargo fmt`

## コーディング規約
- `unwrap()` はテストコード以外で使用禁止。`?` 演算子か `anyhow::Result` を使う
- publicな関数・構造体には必ずdocコメントをつける
- エラーメッセージはユーザー向けに分かりやすく書く（内部エラーコードは不要）

## 禁止操作
- `Cargo.toml` の edition を変更しない
- `main` ブランチに直接pushしない

設計意図: CLIツールは「エラーハンドリング方針」と「公開API（public関数）のドキュメント規約」が特に重要です。Claudeは放っておくとunwrap()を多用しがちなので明示的に禁止しています。

---

パターン③：Webアプリケーション

想定: フロントエンド + バックエンドの典型的なWebアプリ、2〜4人チーム

# CLAUDE.md

## プロジェクト概要
社内向けタスク管理アプリ。フロントエンドはNext.js (App Router)、バックエンドはFastAPI。

## 技術スタック
- フロントエンド: Next.js 15, React 19, TypeScript 5.7, Tailwind CSS v4
- バックエンド: Python 3.12, FastAPI, SQLAlchemy 2.x, PostgreSQL 16
- インフラ: Docker Compose (開発), AWS ECS (本番)

## ディレクトリ構成

frontend/ — Next.jsアプリ
backend/ — FastAPI アプリ
docker/ — Docker関連ファイル
docs/ — 設計ドキュメント

## コマンド
- フロントエンド起動: `cd frontend && npm run dev`
- バックエンド起動: `cd backend && uv run uvicorn app.main:app --reload`
- フロントテスト: `cd frontend && npm test`
- バックテスト: `cd backend && uv run pytest`
- 単一テスト: `cd backend && uv run pytest tests/test_file.py::test_name -xvs`
- DB マイグレーション: `cd backend && uv run alembic upgrade head`
- lint: `cd frontend && npm run lint` / `cd backend && uv run ruff check .`

## アーキテクチャ方針
- フロントエンドはApp Routerを使い、Server Componentsをデフォルトとする
- 'use client' は最小限のインタラクション部分にのみ使用
- APIエンドポイントは `/api/v1/` プレフィックスで統一
- バックエンドはクリーンアーキテクチャ: router → service → repository の3層構造
- ビジネスロジックはserviceレイヤーに集約し、routerにロジックを書かない

## コーディング規約
### フロントエンド
- コンポーネントはアロー関数 + named export
- CSS は Tailwind のユーティリティクラスのみ（カスタムCSSファイル追加禁止）
- APIコールは `lib/api/` 配下に集約

### バックエンド
- 型ヒント必須
- Pydantic v2のモデルでリクエスト/レスポンスを定義
- SQLAlchemy モデルと Pydantic スキーマは明確に分離

## 禁止操作
- `frontend/package-lock.json` を手動編集しない
- `.env` ファイルをGitにコミットしない
- 本番DBへの直接接続コマンドを生成しない
- `alembic downgrade` を自動実行しない

## テスト方針
- バックエンド: pytest + httpx.AsyncClient でAPIテスト
- フロントエンド: Vitest + Testing Library
- テストを書かずにPRを出さない

設計意図: フロントエンドとバックエンドで規約が異なるため、セクションを明確に分けています。「禁止操作」セクションが厚いのは、Claudeがマイグレーションやenv操作で事故を起こしやすいためです。

---

パターン④：モノレポ

想定: 複数パッケージを1リポジトリで管理、5人以上のチーム

モノレポではルートCLAUDE.md + 各パッケージCLAUDE.mdの階層構造が有効です。

ルートCLAUDE.md（抜粋）:

# CLAUDE.md（ルート）

## プロジェクト概要
マルチプラットフォーム対応のECアプリケーション。モノレポ構成（turborepo）。

## パッケージ構成
| パッケージ | 用途 | 技術スタック |
|-----------|------|------------|
| `packages/web` | 購入者向けWebアプリ | Next.js 15 |
| `packages/api` | REST API | FastAPI |
| `packages/shared` | 共有型定義・ユーティリティ | TypeScript |
| `packages/mobile` | モバイルアプリ | React Native |

## 共通ルール
- 各パッケージ間の依存は `packages/shared` を経由する（直接import禁止）
- 環境変数は `packages/<name>/.env.local` で管理
- コミットメッセージは Conventional Commits 準拠

## コマンド
- 全体ビルド: `turbo build`
- 全体テスト: `turbo test`
- 特定パッケージのみ: `turbo build --filter=web`

## 禁止操作
- ルート `package.json` に依存を直接追加しない
- パッケージ間で循環依存を作らない

設計意図: ルートには「パッケージ間のルール」だけを書き、各パッケージ固有のルールはサブディレクトリのCLAUDE.mdに委譲します。Claudeが特定パッケージ内で作業するとき、そのディレクトリのCLAUDE.mdが自動で追加読み込みされます。

---

パターン⑤：チーム開発（中規模）

想定: 3〜8人チーム、スプリント開発、コードレビューあり

# CLAUDE.md

## プロジェクト概要
BtoB SaaS の請求管理システム。Rails 7 + React (SPA)。

## 技術スタック
- バックエンド: Ruby 3.3, Rails 7.2 (API mode)
- フロントエンド: React 19, TypeScript, Vite
- DB: PostgreSQL 16
- キュー: Sidekiq + Redis
- CI: GitHub Actions

## コマンド
- サーバー起動: `bin/dev`
- テスト: `bundle exec rspec`
- 単一テスト: `bundle exec rspec spec/path/to/file_spec.rb:LINE`
- lint (Ruby): `bundle exec rubocop`
- lint (TS): `cd frontend && npm run lint`
- 型チェック: `cd frontend && npm run typecheck`

## アーキテクチャ方針
- Rails は API mode。ビューは持たない
- Fat Model 禁止。ビジネスロジックは `app/services/` に Service Object として実装
- フロントエンドの状態管理は TanStack Query を使う（Redux禁止）
- 金額計算は必ず BigDecimal を使う（Float禁止）

## コーディング規約
- Ruby: rubocop の設定（`.rubocop.yml`）に従う
- TypeScript: strict mode 必須。`any` 型は原則禁止
- テーブル変更時は必ずマイグレーションファイルを作成する
- N+1 クエリを絶対に発生させない（`bullet` gem で検出）

## Git / ブランチ運用
- ブランチ名: `feature/TICKET-123-short-description`
- コミットメッセージ: `[TICKET-123] 変更内容の要約`
- `main` ブランチへの直接pushは禁止
- PRには必ずテストを含める

## 禁止操作
- `db:reset` や `db:drop` を実行しない
- `Gemfile.lock` / `package-lock.json` を手動編集しない
- 本番環境の環境変数やシークレットをコードに記述しない
- `binding.pry` をコミットしない

設計意図: チーム開発では「Git運用ルール」の追記が鍵です。Claudeがコミットメッセージを生成する際、チームの規約に合わせた形式になります。また、金額計算にFloat禁止のようなドメイン固有の制約を明記すると、バグの予防に直結します。

---

パターン⑥：OSSプロジェクト

想定: 外部コントリビュータがClaude Codeを使ってPRを送ることを想定

# CLAUDE.md

## プロジェクト概要
`logpilot` — 構造化ログをリアルタイムにフィルタ・変換するCLIツール（Go製）。
OSSプロジェクト（MIT License）。

## 技術スタック
- Go 1.23
- 依存: cobra (CLI), zerolog (ログ), testify (テスト)

## コマンド
- ビルド: `go build -o logpilot ./cmd/logpilot`
- テスト: `go test ./...`
- 単一テスト: `go test -run TestName ./path/to/package`
- lint: `golangci-lint run`
- ドキュメント生成: `go doc ./...`

## アーキテクチャ
- `cmd/` — エントリポイント（CLIの定義）
- `internal/filter/` — フィルタロジック（外部公開しない）
- `internal/transform/` — 変換ロジック
- `pkg/config/` — 公開設定API
- `internal` パッケージは外部から import させない設計

## コーディング規約
- `golangci-lint` の設定に従う
- エラーは `fmt.Errorf("context: %w", err)` でラップする
- グローバル変数は使用禁止
- コメントは英語で書く

## コントリビューション時の注意
- CONTRIBUTING.md を必ず読んでから作業する
- 破壊的変更（APIシグネチャ変更）は事前にIssueで議論する
- 新機能追加時はテストカバレッジを下げない
- ドキュメント（README / GoDoc）の更新も忘れない

## 禁止操作
- `go.sum` を手動編集しない
- `replace` ディレクティブを `go.mod` に追加しない（ローカル開発目的であっても）
- ライセンスヘッダーを削除しない

設計意図: OSSでは「コントリビューターが使う」ケースを想定します。CONTRIBUTING.mdとの連携を明記し、ライセンス周りの事故を禁止操作で防ぎます。

---

パターン⑦：データパイプライン

想定: ETL/ELTジョブ、ML前処理パイプライン、1〜3人

# CLAUDE.md

## プロジェクト概要
日次バッチで売上データを集計し、BIダッシュボード用のデータマートを構築するETLパイプライン。

## 技術スタック
- Python 3.12, dbt-core 1.8, DuckDB (開発) / BigQuery (本番)
- オーケストレーション: Dagster
- テスト: pytest + dbt test

## ディレクトリ構成

pipelines/ — Dagster ジョブ定義
models/ — dbt モデル（SQL）
scripts/ — 手動実行ユーティリティ
tests/ — Python テスト
seeds/ — dbt seed データ

## コマンド
- パイプライン起動(dev): `dagster dev`
- dbt実行: `dbt run --target dev`
- dbtテスト: `dbt test`
- pytest: `pytest tests/`
- データプロファイル: `python scripts/profile.py`

## データ設計方針
- モデル命名: `stg_`(ステージング), `int_`(中間), `fct_`(ファクト), `dim_`(ディメンション)
- 全テーブルに `created_at`, `updated_at` カラムを持たせる
- 冪等性を保証する（何回実行しても同じ結果）
- DELETE文は使わない。冪等なMERGE/UPSERT戦略を使う

## 禁止操作
- 本番BigQueryのデータを直接UPDATE/DELETEしない
- `seeds/` 配下に個人情報を含むデータを置かない
- `dbt run` を `--full-refresh` なしで本番実行しない（開発環境では可）
- 環境変数 `BQ_PROJECT_ID` を本番値にハードコードしない

## テスト方針
- dbt: `not_null`, `unique`, `relationships` テストを全モデルに設定
- Python: パイプライン関数は純関数にし、入出力のスナップショットテスト
- 本番デプロイ前に `dbt test` が全パスすることをCIで強制

設計意図: データパイプラインは「冪等性」と「本番データ保護」が最重要です。Claudeがうっかりデストラクティブなクエリを生成しないよう、禁止操作を手厚くしています。

---

4. アンチパターン：書きすぎ・書かなさすぎで起きた実際の事故

3ヶ月間の運用で遭遇したトラブルを共有します。

🚨 アンチパターン①：書かなさすぎ → テストが壊れた

CLAUDE.mdに「テスト方針」を書いていなかったプロジェクトで、Claudeが既存のテストヘルパーを無視して独自のモックを大量生成。テストスイート全体が壊れ、修復に半日かかりました。

教訓: 最低限「テストコマンド」と「テストの書き方の方針」は書く。

🚨 アンチパターン②：書きすぎ → 指示が競合して暴走

CLAUDE.mdが800行を超えたプロジェクトで、「関数は短く保つ」と「エラーハンドリングは詳細に書く」の指示が競合。Claudeが1つの関数を分割しすぎて、かえって読みにくいコードが量産されました。

教訓: CLAUDE.mdは300行以内を目安にする。それを超える場合はサブディレクトリに分割する。

🚨 アンチパターン③：禁止操作を書き忘れ → 本番DBに接続

「本番環境に接続するコマンドを生成しない」という禁止操作を書き忘れたところ、Claudeが.envから本番のDB URLを読み取り、マイグレーションコマンドを提案。幸い実行前に気づいたものの、冷や汗ものでした。

教訓: 「やってほしいこと」より「絶対にやってはいけないこと」を先に書く。

5. CLAUDE.mdをチームでバージョン管理する運用フロー

CLAUDE.mdはコードと同じくらい重要な資産です。チームで運用する際のフローを紹介します。

運用のポイント

1. CLAUDE.mdの変更もPRレビューを通す
   コードと同様に、ルール変更の意図をチームで共有します。「なぜこのルールが必要か」をPR descriptionに書くと、後から振り返りやすくなります。

2. スプリントレトロで振り返る
   「今週Claudeが生成したコードで困ったこと」をレトロで共有し、CLAUDE.mdに反映します。これを繰り返すと、チーム固有のベストプラクティスが蓄積されます。

3. グローバルCLAUDE.mdとプロジェクトCLAUDE.mdを使い分ける
   「コミットメッセージは日本語で書く」のような個人の好みは~/.claude/CLAUDE.mdに、プロジェクト固有のルールはリポジトリのCLAUDE.mdに書きます。

まとめ

• CLAUDE.mdはプロジェクト規模で構成を変える。個人スクリプトなら30行で十分、モノレポなら階層化して分割する
• 「禁止操作」セクションが最重要。Claudeにやってほしいことより、やってはいけないことを先に・明確に書く
• チームでバージョン管理し、スプリントごとに育てる。CLAUDE.mdは「書いて終わり」ではなく、コードと一緒に進化させる生きたドキュメント

参考リンク

• Claude Code 公式ドキュメント — Memory
• Claude Code 公式ドキュメント — Overview
• Claude Code Best Practices（Anthropic公式）