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

CLAUDE.mdは、Claude Codeにプロジェクトの前提・ルール・作法を教える設定ファイルです。1ファイルへの詰め込みはプロジェクト規模が大きくなると破綻するため、@importや.claude/rules/のpaths指定で規模に応じて分割設計します。

本記事は2026年8月時点の情報です。

「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構成。

## アーキテクチャ

- フロントエンド: 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

## 絶対遵守ルール

@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 プロジェクト全体仕様書

## 会社基本情報

- 事業: 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のスコープが適切か
- 既存ルールとの重複がないか

Skills・Agent Teams時代のCLAUDE.md設計

2026年に入って、Claude Codeには CLAUDE.md 以外にも「指示の置き場所」が増えました。何をCLAUDE.mdに残し、何を外に出すか。この線引きがそのまま設計品質になります。

カスタムコマンドはスキルに統合された

.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy を作り、同じように動きます。既存の .claude/commands/ はそのまま動作し続けるので、急いで移行する必要はありません。ただしスキル側には、補助ファイル用のディレクトリを持てること、frontmatterで呼び出し主体を制御できること、関連する場面でClaudeが自動的に読み込むこと、という3つの違いがあります。

これがCLAUDE.md設計に効いてきます。特定の作業のときだけ必要な長い手順は、CLAUDE.mdに常駐させるのではなくスキルへ出すのが原則です。常時読み込まれるコンテキストが軽くなり、その手順を使わないセッションで無駄なトークンを払わずに済みます。Claudeに勝手に起動されたくない手順は、frontmatterに disable-model-invocation: true を書けばユーザーの明示呼び出しだけに限定できます。（出典: Skills / Commands、2026年8月1日確認）

常時ロードと必要時ロードで置き場所を分ける

ルートCLAUDE.mdは「地図」、.claude/rules/ は「地域ごとのルール」、スキルは「作業手順書」と考えると迷いません。長い手順書をCLAUDE.mdに直接書くと、その手順を一切使わないセッションでも毎回そのトークンを払うことになります。前述の @import による分割は「1ファイルを読みやすく割る」ための道具、スキルへの切り出しは「そもそも読み込ませない」ための道具です。目的が違う点に注意してください。

サブエージェントにはモデルを明示的に固定する

サブエージェントは、model を指定しないと親セッションのモデルをそのまま引き継ぎます。メインを上位モデルで動かしていると、実行役のサブエージェントまで同じ単価で回ることになり、コスト設計が静かに崩れます。CLAUDE.mdには「どの役割にどのモデルを充てるか」という方針を書き、エージェント定義側でも固定するのが安全です。

## サブエージェント運用ルール

- 設計・レビュー・オーケストレーションはメインセッションで行う
- コーディング・ファイル操作・データ処理は必ずサブエージェントに委任する
- 実行系サブエージェントは model を明示的に指定する（未指定だと親モデルを継承する）

エージェント定義ファイル側は、frontmatterで固定します。

---
name: bulk-editor
description: 大量のファイル編集を担当する
model: sonnet
isolation: worktree
---

isolation: worktree を書くと、そのサブエージェントは常に専用のgit worktreeで動きます。変更なしで終了したworktreeは自動的に削除されるため、ファイルを大量に触る役割ほどこの1行の価値が高くなります。なお auto mode（分類器に許可判断を任せるモード）で動かしている場合、frontmatterの permissionMode は無視されます。権限をfrontmatterで緩める前提の設計にしないでください。（出典: Subagents / Worktrees、2026年8月1日確認）

条件を満たすまで自律的に作業を続けさせる /goal を併用する場合は、CLAUDE.mdに検証コマンドを明記しておくと効果が上がります。/goal の判定役は会話に出ている内容だけで成否を判断するため、「npm test の結果を出力してから完了と宣言する」といった手順がルール化されているほど、条件成立を正しく判定できます。詳しくは/goalコマンドで条件達成まで自律実行させる方法で解説しています。

Agent Teamsを前提にした書き方

Agent Teamsを有効にすると、複数のteammateがそれぞれ独立したコンテキストウィンドウで動きます。teammateも同じCLAUDE.mdを読むため、「誰が読んでも同じ判断になる書き方」の重要度が一段上がります。実務上は次の3点です。

• 主語を「あなた」ではなく役割で書く（「実装担当は〜」「レビュー担当は〜」）
• ファイル所有権をルールとして明記する（同じファイルを2人が編集すると上書きが起きる）
• 「必ず確認を取る」ルールは、確認先まで書く（リードなのか、人間なのか）

v2.1.178で TeamCreate / TeamDelete ツールは削除され、team_name の指定も受理はされますが無視されるようになりました。古いCLAUDE.mdに「まずチームを作成して名前を付ける」という手順を書いている場合、その記述はもう不要です。有効化に必要な設定は CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 の1つだけです。（出典: Agent teams、2026年8月1日確認）

Agent Teamsそのものの設定と運用はClaude Codeで複数AIエージェントを並列実行する方法で扱っています。

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

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

カスタムコマンド（.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の変更は「プロジェクトのルール変更」に等しいため、チームメンバー全員がレビューできるフローにすべきです。特に禁止事項やセキュリティルールの変更は、テックリードの承認を必須にするのが安全です。

• Claude Codeの使い方・コマンド・並列実行・料金の全体像はClaude Code完全ガイド（ハブ）で目的別に整理しています。*