CLAUDE.md設計パターン集｜プロジェクト規模別のベストプラクティスと実例

「CLAUDE.mdを書き始めたが、どこまで細かく書くべきか分からない」「プロジェクトが大きくなるにつれてCLAUDE.mdが肥大化し、Claude Code自体の動作が重くなってきた」——CLAUDE.mdを使い込むほどに直面する設計上の悩みです。

CLAUDE.mdは、Claude Codeに「このプロジェクトではどう振る舞うべきか」を教えるための設定ファイルであり、人間のオンボーディングドキュメントに相当します。しかし、1ファイルに全てを詰め込む書き方は、プロジェクト規模が中規模以上になった時点で破綻します。@importによるファイル分割、.claude/rules/のpaths指定によるスコープ制御、モノレポでの階層設計といったパターンを、プロジェクト規模に応じて使い分けることが重要です。

本記事では、設定ファイルの読み込み優先順位、個人開発から大規模モノレポまでの規模別ベストプラクティス、マネージドCLAUDE.mdとローカルCLAUDE.mdの使い分けまでを、実例とともに解説します。

この記事でわかること

CLAUDE.mdの設計パターンを学び、プロジェクトに最適化したい開発リーダーに向けた記事です。

• CLAUDE.mdの基本構造と、Claude Codeが設定ファイルを読み込む優先順位 — ClaudeCodeは複数の設定ファイルを階層的に読み込みます。
• @importディレクティブによるファイル分割と、.claude/rules/ ディレクトリの使い方 — 配下のMarkdownファイルには、フロントマターを指定することで、特定のファイルパスに対してのみルールを適用できます。
• pathsフロントマターによるルールの適用スコープ制御
• モノレポにおけるCLAUDE.md設計（複数プロジェクト・複数チーム対応） — CLAUDE.mdは、ClaudeCodeに「このプロジェクトではどう振る舞うべきか」を教えるための設定ファイルです。
• マネージドCLAUDE.mdとローカルCLAUDE.mdの使い分け

CLAUDE.mdとは

CLAUDE.mdは、Claude Codeに「このプロジェクトではどう振る舞うべきか」を教えるための設定ファイルです。プロジェクトのルートに配置された CLAUDE.md を読み込み、その内容に基づいて応答スタイル、コーディング規約、禁止事項、ワークフローなどを自動的に適用します。

人間のチームにおける「オンボーディングドキュメント」に相当します。新しいメンバーが入社したときに渡す「このプロジェクトのルール集」と同じ役割を、AIエージェントに対して果たします。

設定ファイルの読み込み優先順位

Claude Codeは複数の設定ファイルを階層的に読み込みます。優先順位（後から読まれたものが上書き）は以下の通りです。

この優先順位を理解することで、「全体に適用するルール」と「特定の領域にだけ適用するルール」を効率的に設計できます。

基本的な書き方

最小構成（個人開発・小規模プロジェクト）

個人開発やファイル数が少ないプロジェクトでは、ルートの CLAUDE.md 1ファイルで十分です。

# プロジェクトルール

### 技術スタック
- Next.js 15 / TypeScript / Supabase / Tailwind CSS

### コーディング規約
- 関数はアロー関数で統一
- コンポーネントはfunction宣言
- 型はinterface優先（typeは複合型のみ）
- エラーハンドリングはtry-catchで明示的に

### 禁止事項
- any型の使用禁止
- console.logを残さない（console.errorは可）
- .envファイルへの直接値書き込み禁止

### テスト
- テストフレームワーク: Vitest
- 新規関数には必ずユニットテストを作成

この構成は50ファイル以下のプロジェクトに適しています。ルールが増えてきたら分割を検討します。

中規模構成（チーム開発・100〜500ファイル）

チーム開発では、CLAUDE.mdの責務を分割して管理性を高めます。

プロジェクトルート/
├── CLAUDE.md                    ← 全体ルール（簡潔に）
├── .claude/
│   ├── rules/
│   │   ├── frontend.md          ← フロントエンド固有ルール
│   │   ├── backend.md           ← バックエンド固有ルール
│   │   ├── testing.md           ← テスト規約
│   │   └── security.md          ← セキュリティルール
│   ├── settings.json            ← Hooks・権限設定
│   └── agents/                  ← カスタムエージェント
│       └── reviewer.md
└── src/
    ├── app/
    └── components/

ルートCLAUDE.mdの記述例（中規模）

# プロジェクト概要

ECサイトのリニューアルプロジェクト。Next.js + Supabase構成。

## アーキテクチャ

<img src="https://start-link.jp/hubfs/blog/h2-kv/DD-14_h04.png" alt="アーキテクチャ" style="width:100%;max-width:1200px;height:auto;margin:24px 0;border-radius:12px;box-shadow:0 4px 16px rgba(0,0,0,0.08);"/>
- フロントエンド: Next.js 15 App Router
- バックエンド: Supabase Edge Functions
- DB: Supabase PostgreSQL
- 認証: Supabase Auth

### ディレクトリ構造
- src/app/ → ページ・ルーティング
- src/components/ → UIコンポーネント
- src/lib/ → ユーティリティ・ヘルパー
- supabase/functions/ → Edge Functions
- supabase/migrations/ → DBマイグレーション

### 共通ルール
- TypeScript strict mode
- ESLint + Prettier準拠
- 詳細ルールは .claude/rules/ を参照

@importによるファイル分割

@importの基本構文

@import ディレクティブを使うと、外部のMarkdownファイルをCLAUDE.mdにインライン展開できます。

# プロジェクトルール

@import .claude/rules/coding-standards.md
@import .claude/rules/api-guidelines.md
@import .claude/rules/deployment.md

Claude Codeが CLAUDE.md を読み込む際に、@import で参照されたファイルの内容が自動的にその位置に挿入されます。

@importの活用パターン

# CLAUDE.md

## 絶対遵守ルール

<img src="https://start-link.jp/hubfs/blog/h2-kv/DD-14_h05.png" alt="絶対遵守ルール" style="width:100%;max-width:1200px;height:auto;margin:24px 0;border-radius:12px;box-shadow:0 4px 16px rgba(0,0,0,0.08);"/>
@import .claude/rules/critical.md

### コーディング規約
@import .claude/rules/coding-standards.md

### テスト規約
@import .claude/rules/testing.md

### デプロイ手順
@import .claude/rules/deployment.md

.claude/rules/ ディレクトリの設計

pathsフロントマターによるスコープ制御

.claude/rules/ 配下のMarkdownファイルには、paths フロントマターを指定することで、特定のファイルパスに対してのみルールを適用できます。

---
paths:
  - "src/components/**"
  - "src/app/**/page.tsx"
---

# フロントエンドコンポーネントルール

#### コンポーネント命名
- PascalCase（例: UserProfile.tsx）
- ページコンポーネントは page.tsx 固定

#### スタイリング
- Tailwind CSSのユーティリティクラスを使用
- カスタムCSSは components.css にまとめる
- !important 禁止

---
paths:
  - "supabase/functions/**"
  - "src/lib/api/**"
---

# バックエンドAPIルール

#### Edge Functions
- レスポンスは必ずJSON形式
- エラーレスポンスは { error: string, code: number } 形式
- レートリミット: 設定ファイルから取得（ハードコード禁止）

pathsの動作原理

Claude Codeがファイルを操作（読み取り・書き込み・分析）する際、そのファイルパスが paths の条件に一致する .claude/rules/ ファイルのルールが自動的に適用されます。

ユーザー: 「src/components/Header.tsx を修正して」
→ Claude Codeの内部処理:
  1. CLAUDE.md（全体ルール）を読み込み
  2. src/components/** にマッチする rules/ をスキャン
  3. frontend.md のルールが追加適用
  4. 修正を実行

この仕組みにより、フロントエンド担当のルールがバックエンドのコードに誤って適用される——といった事故を防げます。

モノレポ設計パターン

モノレポのCLAUDE.md階層

複数のプロジェクトが1つのリポジトリに同居するモノレポでは、CLAUDE.mdの階層設計が特に重要です。

monorepo/
├── CLAUDE.md                        ← 全プロジェクト共通ルール
├── .claude/
│   └── rules/
│       ├── git-workflow.md          ← Git運用ルール（全体共通）
│       └── security.md             ← セキュリティルール（全体共通）
│
├── apps/
│   ├── web/
│   │   └── CLAUDE.md               ← Webアプリ固有ルール
│   ├── api/
│   │   └── CLAUDE.md               ← APIサーバー固有ルール
│   └── admin/
│       └── CLAUDE.md               ← 管理画面固有ルール
│
├── packages/
│   ├── ui/
│   │   └── CLAUDE.md               ← UIライブラリ固有ルール
│   └── shared/
│       └── CLAUDE.md               ← 共有ユーティリティのルール
│
└── marketing/
    ├── blog/
    │   └── CLAUDE.md               ← ブログ制作ルール
    └── website/
        └── CLAUDE.md               ← Webサイト管理ルール

実例: StartLink型モノレポの設計

CRMコンサルティングとブログ運営、プロダクト開発を1つのリポジトリで管理するケースを見てみます。

ルートCLAUDE.md（共通ルール）:

# StartLink プロジェクト全体仕様書

## 会社基本情報

<img src="https://start-link.jp/hubfs/blog/h2-kv/DD-14_h07.png" alt="会社基本情報" style="width:100%;max-width:1200px;height:auto;margin:24px 0;border-radius:12px;box-shadow:0 4px 16px rgba(0,0,0,0.08);"/>
- 事業: CRM特化型コンサルティング、AI活用アドバイザリー

### 全体共通ルール
- 実名事例のみ（匿名A社/B社禁止）
- 内部情報の外部公開禁止
- です/ます調で統一

### ディレクトリマップ
- 00_strategy/ → 経営戦略
- 01_marketing/ → マーケティング・ブログ
- 02_product/ → プロダクト開発

01_marketing/CLAUDE.md（マーケティング固有）:

# マーケティングルール

### ブログ記事制作
- 3,000文字以上
- FAQセクション3問以上
- blog-reviewスキルで90点以上必須
- レビュー未実行での公開は絶対禁止

02_product/CLAUDE.md（プロダクト固有）:

# プロダクト開発ルール

### 技術スタック
- Next.js / TypeScript / Supabase

### Git戦略
- main → feature/* → PR → main
- Vercel自動デプロイ

この設計により、Claude Codeが 01_marketing/ 配下で作業するときはブログ制作ルールが、02_product/ 配下で作業するときはプロダクト開発ルールが自動的に適用されます。なお、Claude Codeを活用した経営データの可視化やコンテンツマーケティングの支援についても、具体的な取り組みをご紹介しています。

マネージドCLAUDE.mdとローカルCLAUDE.md

2つのスコープの使い分け

マネージドCLAUDE.mdに書くべき内容

# 個人設定

#### 応答スタイル
- 日本語で応答
- コードコメントも日本語
- 省略せず正式名称で記述

#### エディタ設定
- インデント: スペース2つ
- 行末: LF
- エンコーディング: UTF-8

#### 好みの設定
- テスト作成時はエッジケースを多めに
- エラーメッセージは具体的に（何が・どこで・なぜ失敗したか）

ローカルCLAUDE.mdに書くべき内容

# プロジェクト固有ルール

#### アーキテクチャ（チーム共有）
- ディレクトリ構造と各フォルダの責務
- 使用ライブラリとバージョン
- APIの設計方針

#### コーディング規約（チーム共有）
- 命名規則
- エラーハンドリング方針
- コメント規約

#### 禁止事項（チーム共有）
- 破壊的変更の禁止ファイル
- 直接変更禁止のブランチ

実務での活用パターン

パターン1: 段階的に育てるCLAUDE.md

CLAUDE.mdは最初から完璧に書く必要はありません。プロジェクトの成長に合わせて段階的に拡充していくのが現実的です。

【フェーズ1: プロジェクト開始】
CLAUDE.md → 10行（技術スタック + 基本ルール3つ）

【フェーズ2: チーム拡大】
CLAUDE.md → 50行（ディレクトリ構造 + コーディング規約）
.claude/rules/testing.md → テスト規約を分離

【フェーズ3: 本番運用】
CLAUDE.md → 30行（概要のみ。詳細は@importで分割）
.claude/rules/ → 5ファイル（frontend / backend / testing / security / deploy）
.claude/agents/ → 3ファイル（reviewer / test-writer / doc-writer）

Before: プロジェクト開始時に200行のCLAUDE.mdを書こうとして挫折。

After: 10行からスタートし、「AIが間違えた箇所」を都度ルールとして追記。

パターン2: ミスドリブンでルールを追加

CLAUDE.mdにルールを追加する最も効果的なタイミングは、「AIが間違えたとき」です。

【ミス発生】
Claude Codeがconsole.logをプロダクションコードに残した

【ルール追加】
.claude/rules/coding-standards.md に以下を追記:
- console.logをプロダクションコードに残さない（console.errorのみ許可）

【再発防止確認】
同じ種類のタスクを再実行し、ルールが適用されることを確認

この「ミス→ルール追加→検証」のサイクルを回すことで、CLAUDE.mdが実践的なナレッジベースとして成長していきます。

パターン3: CLAUDE.mdのコードレビュー

CLAUDE.md自体もプロダクトコードと同様にコードレビューの対象とします。

PR: 「CLAUDE.mdにAPI設計ガイドラインを追加」
レビュー観点:
- ルールが具体的か（「適切に」ではなく「必ず try-catch で」）
- 矛盾するルールがないか
- pathsのスコープが適切か
- 既存ルールとの重複がないか

関連コマンドとの組み合わせ

カスタムコマンドとの関係

カスタムコマンド（.claude/commands/）はCLAUDE.mdを補完する仕組みです。CLAUDE.mdが「常に適用されるルール」なら、カスタムコマンドは「特定のタスクを実行するときのレシピ」です。CLAUDE.mdでプロジェクトの大方針を定め、カスタムコマンドで具体的な作業手順を定義する——という分担が効果的です。

Hooksとの連携

Claude Code Hooksは .claude/settings.json で定義しますが、CLAUDE.mdにフックの概要と目的を記載しておくと、AIエージェントがフックの存在を認識した上で作業を進められます。

メモリ・コンテキストとの関係

CLAUDE.mdは「プロジェクトのルール」を定義し、メモリ・コンテキストは「セッションをまたいだ記憶」を保持します。CLAUDE.mdに書くべきは「変わらないルール」、メモリに記録すべきは「変化する状態や学習結果」です。

あわせて読みたい

• Claude Code × Stitchでワイヤーフレーム・UIデザインを自動生成する方法
• Claude Code × Chrome DevTools連携｜WebアプリのライブデバッグをAIで効率化する
• Claude Code MCP連携の始め方｜HubSpot・freee・Slackを接続する設定手順【2026年版】

まとめ

まずは自社の現状を棚卸しし、最も効果が見込める領域から第一歩を踏み出してみてください。

属人化を防ぎ、チーム全体で再現可能な仕組みとして標準化することが成功の鍵です。

自社の業務フローや要件に応じて、段階的にカスタマイズしていくことをおすすめします。

• CLAUDE.mdの設計は、プロジェクト規模に応じて段階的に進化させるのが最善のアプローチです
• 小規模プロジェクトではルートに1ファイル、中規模では.claude/rules/による分割とpathsスコープ制御、大規模モノレポではディレクトリごとのCLAUDE.md階層と@import分割を適用します
• マネージドCLAUDE.md（個人設定）とローカルCLAUDE.md（プロジェクト共有）を使い分け、ミスが発生するたびにルールを追加する「ミスドリブン」の運用が、最も実践的なCLAUDE.mdの育て方です

• *Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください
• AI活用の全体像はAI活用完全ガイドで解説しています

よくある質問（FAQ）

Q1. CLAUDE.mdが長くなりすぎると、Claude Codeの性能に影響しますか？

CLAUDE.mdの内容はセッション開始時にコンテキストウィンドウに読み込まれるため、極端に長い場合はトークンを消費します。目安として、CLAUDE.md全体（@import展開後）で5,000〜10,000文字程度に収めるのが推奨です。それ以上になる場合は、pathsによるスコープ制御で「必要なルールだけ読み込まれる」設計にすることで、トークン効率を改善できます。

Q2. CLAUDE.mdとREADME.mdの違いは何ですか？

README.mdは人間の開発者向けのドキュメントで、セットアップ手順や使い方を記載します。CLAUDE.mdはAIエージェント向けの設定ファイルで、コーディング規約や禁止事項を記載します。両者は目的が異なるため、どちらか一方に統合するのではなく、それぞれ独立して管理するのが適切です。

Q3. .claude/rules/ のファイルに命名規則はありますか？

技術的な制約はありませんが、ファイル名から内容が推測できる命名を推奨します。frontend.md、backend.md、testing.md、security.md のように、ルールの対象領域をファイル名にするのが一般的です。番号プレフィックス（01-critical.md、02-standards.md）を使って優先度を明示するパターンもあります。

Q4. チームでCLAUDE.mdを共同編集する際のベストプラクティスは？

CLAUDE.mdをGit管理下に置き、変更はPR経由で行うことを推奨します。CLAUDE.mdの変更は「プロジェクトのルール変更」に等しいため、チームメンバー全員がレビューできるフローにすべきです。特に禁止事項やセキュリティルールの変更は、テックリードの承認を必須にするのが安全です。