結論: CLAUDE.md をチームで運用するには「Progressive Disclosure（必要な時だけ読み込む）」と「Monorepo 対応（ディレクトリ階層に分散させる）」の 2 つの設計思想が核心です。
この記事の要点:
- CLAUDE.md は 1 ファイルにまとめるより、Root + モジュール別に分散させると Claude の動作精度が上がる（Anthropic 公式推奨: 1 ファイル 200 行以下）
- Progressive Disclosure で「今必要な知識だけ読み込む」設計にすることで、コンテキスト汚染を防ぎ、より高品質な出力が得られる
- チームで使う CLAUDE.md は Git 管理が必須。「誰が何を変えたか」の履歴がプロンプトの品質改善につながる
対象読者: Claude Code を個人利用から卒業してチームに展開しようとしている開発リーダー・DX 推進担当者
読了後にできること: チーム用の CLAUDE.md ファイル構成を今日中に設計できる
「Claude Code を自分では使いこなせてきたんですが、チームに広めようとしたら CLAUDE.md が誰でも書けるわけじゃないし、メンテナンスが大変で…」
企業向け研修で、開発チームのリーダーからよく受ける相談です。個人の CLAUDE.md は「自分さえわかればいい」で済みますが、チームで管理する CLAUDE.md はまったく違う話になります。
先日支援したある Web 系企業（開発メンバー 12 名）では、CLAUDE.md を 1 ファイルにまとめていたため、ファイルが 800 行を超えて肥大化し、Claude が後半の指示を無視するようになっていました。「プロンプトが効かない」という問い合わせが続いていたのですが、根本原因は CLAUDE.md の設計にありました。
この記事では、チームで CLAUDE.md を運用するための設計思想と実践テクニックを、コピペ可能なテンプレートとともに全公開します。
CLAUDE.md の基本的な書き方についてはCLAUDE.md 書き方完全ガイドで詳しく解説しています。この記事はチーム運用の応用編として読んでください。
まず試したい「5 分でできる」チーム対応設定 3 選
即効設定 1：共通禁止事項を Root CLAUDE.md に固定する
チームで最初にやるべきことは、「全員が守るべきルール」を Root の CLAUDE.md（リポジトリ直下）に書き、個人がローカルで上書きできないようにすることです。
研修先でよく使っている雛形です:
# [プロジェクト名] CLAUDE.md - チーム共通設定
## 絶対ルール（個人設定で上書き禁止）
- ハードコードされた認証情報（APIキー、パスワード）は絶対に記述しない
- テスト環境のデータを本番環境に適用するコードを書かない
- package.json や requirements.txt を勝手に変更しない
- 未確認の依存関係を追加しない
## コード規約
- 言語: TypeScript / Python（プロジェクトに合わせて変更）
- フォーマッター: Prettier / Black（設定ファイルを参照）
- Lint: ESLint / Ruff（.eslintrc / ruff.toml を参照）
## テスト
- 新しい機能には必ずユニットテストを追加
- テストを削除・無効化する前にチームに確認
- カバレッジ 80% 以上を維持
## 詳細設定の読み込み方（Progressive Disclosure）
作業内容に応じて以下のファイルを @import してください:
- API 開発: @docs/rules/api-conventions.md
- フロントエンド: @docs/rules/frontend-conventions.md
- DB/マイグレーション: @docs/rules/db-conventions.md
- テスト作業: @docs/rules/testing-guide.mdこのテンプレートのポイントは「絶対ルール」と「詳細設定の読み込み方」を明確に分けている点です。ルールが少ないほど Claude はちゃんと読みます。
即効設定 2：Gotchas（ハマりポイント）セクションを最初に追加する
チームの CLAUDE.md で最も ROI が高いのが「Gotchas（落とし穴）」セクションです。shanraisshan の Claude Code ベストプラクティスでも「Gotchas セクションに最も信号密度の高いコンテンツを入れよ」と推奨されています。
## Gotchas（必ず読むこと）
### 1. auth.ts は直接編集しない
認証ロジックは auth.ts ではなく auth-service.ts が正しいエントリポイント。
auth.ts を直接変えると認証テストが全滅する（2025年10月の事故を参照）。
### 2. API レスポンスの Date 型は ISO 8601 文字列
Date オブジェクトで返すと iOS クライアントで parse エラーになる。
必ず toISOString() で文字列変換して返すこと。
### 3. 環境変数の追加は .env.example にも必ず反映
.env.example を更新しないと CI が落ちる（他メンバーが気づかない）。
### 4. Prisma マイグレーションは単独で PR を出す
ビジネスロジックの変更と混在させると、ロールバック時に混乱する。この「Gotchas」は定例ミーティングで「Claude がまたやらかした」という話が出るたびに追記していきます。実際に Claude が失敗したパターンを記録した CLAUDE.md は、チームの学習資産になります。
即効設定 3：作業コンテキストをプロンプトで渡す習慣をつける
CLAUDE.md に全情報を詰め込むより、作業開始時のプロンプトでコンテキストを渡す方が効果的です。
以下のコンテキストで作業します:
【今日のタスク】
[GitHub Issue URL または Jira チケット ID]
[タスクの概要を 2〜3 行で]
【関連ファイル】
- 変更対象: src/api/users/user.service.ts
- テスト: src/api/users/__tests__/user.service.test.ts
- 型定義: src/types/user.ts
【制約条件】
- 既存のテストを壊さない
- 認証処理は auth-service.ts を通じて行う
- エラーハンドリングは既存パターン（AppError クラス）に統一
作業前に、変更の影響範囲を確認してから着手してください。
不明点は最初に質問してください。Progressive Disclosure の設計思想
「全部 CLAUDE.md に書く」は間違い
CLAUDE.md を書いていると、「もっと詳しく書いた方がいいのでは」という誘惑に駆られます。しかし Anthropic の公式ドキュメントは明確に言っています: 「各 CLAUDE.md は 200 行以下に収めること」。
なぜか？Claude のコンテキストウィンドウには限りがあります。CLAUDE.md が長すぎると、後半の指示が実質的に無視されます。「念のため書いておこう」と追加した指示が、実は邪魔になっているケースが多いです。
実際、研修先の 12 名チームで起きた「CLAUDE.md が効かない」問題の原因は、800 行を超えた CLAUDE.md にありました。後半に書いたコード規約の指示が、Claude に読まれていなかったのです。
Progressive Disclosure の実装パターン
Progressive Disclosure とは「必要な時だけ必要な情報を読み込む」設計です。`@` 記法で外部ファイルを on-demand で取り込めます。
フォルダ構成例（推奨）:
project-root/
├── CLAUDE.md ← Root: 基本ルールのみ（50〜100行）
├── .claude/
│ ├── rules/
│ │ ├── api-conventions.md ← API開発時にimport
│ │ ├── frontend.md ← フロントエンド作業時にimport
│ │ ├── db-migrations.md ← DBマイグレーション時にimport
│ │ └── testing-guide.md ← テスト作業時にimport
│ └── skills/
│ ├── code-review.md ← コードレビュー自動化
│ └── docs-generator.md ← ドキュメント生成
├── src/
│ ├── api/
│ │ └── CLAUDE.md ← APIモジュール固有ルール（30行以下）
│ └── frontend/
│ └── CLAUDE.md ← フロントエンド固有ルール（30行以下）
└── docs/
└── CLAUDE.md ← ドキュメント作業用ルールRoot CLAUDE.md でのimport例:
# Root CLAUDE.md（100行以下を目標）
## プロジェクト概要
[プロジェクト名]: [1行で何を作るか]
## チーム共通ルール
[共通禁止事項 + Gotchas]
## 詳細ルールの読み込み（作業に応じて）
API開発をする場合: @.claude/rules/api-conventions.md
フロントエンド開発: @.claude/rules/frontend.md
DB変更を伴う場合: @.claude/rules/db-migrations.mdこの設計の最大のメリットは「Claude のコンテキストウィンドウを節約できる」点です。API 開発をしている時にフロントエンドのルールが読まれると、不要なコンテキストが増えて出力品質が下がります。
Monorepo での CLAUDE.md 設計
Monorepo の基本戦略
Monorepo（複数のパッケージを 1 リポジトリで管理）では、Claude Code の CLAUDE.md の階層読み込みを最大限活用できます。Claude は作業中のファイルがあるディレクトリから上位に向かって、全ての CLAUDE.md を読み込みます。
monorepo/
├── CLAUDE.md ← 全パッケージ共通ルール
├── packages/
│ ├── api/
│ │ ├── CLAUDE.md ← APIパッケージ固有ルール
│ │ └── src/
│ ├── web/
│ │ ├── CLAUDE.md ← Webフロント固有ルール
│ │ └── src/
│ ├── shared/
│ │ ├── CLAUDE.md ← 共有ライブラリのルール
│ │ └── src/
│ └── mobile/
│ ├── CLAUDE.md ← モバイル固有ルール
│ └── src/
└── docs/
└── CLAUDE.md ← ドキュメント作業用各パッケージの CLAUDE.md を書く際のルール:
- Root CLAUDE.md に書いてある内容を繰り返さない（重複は混乱を招く）
- そのパッケージ固有の「Gotchas」だけを書く（30 行以下を目標）
- 他パッケージとのインターフェイスを明記する（依存関係の明確化）
packages/api/CLAUDE.md 例:
# API パッケージ固有ルール
# （Root CLAUDE.md の内容は繰り返さない）
## Gotchas（API固有）
- auth middleware は全エンドポイントに適用済み。新しいルートに個別設定不要
- バリデーションは zod スキーマを使う（express-validator は廃止予定）
- エラーレスポンスは AppError クラスで統一（throw new AppError(400, "message")）
## パッケージ間の依存関係
- shared パッケージの型定義を import して使う: @packages/shared/types
- web パッケージから API を呼ぶ際は /api プレフィックスが必要
## 新しいエンドポイントを追加する時
1. src/routes/ にルートファイルを追加
2. src/controllers/ にコントローラーを追加
3. __tests__/integration/ にインテグレーションテストを追加
4. docs/api/ に OpenAPI 仕様を更新「Virtual Monorepo」パターン（複数リポジトリへの応用）
複数のリポジトリに分散したマイクロサービスに対して、Monorepo と同様の CLAUDE.md 設計を適用することも可能です。Root CLAUDE.md に他リポジトリへの参照を記述します。
## 関連リポジトリとの依存関係
- 認証サービス: github.com/your-org/auth-service（API仕様: @docs/api-specs/auth.yaml）
- 通知サービス: github.com/your-org/notification-service
- フロントエンド: github.com/your-org/frontend-app
各リポジトリの最新 API 仕様は docs/api-specs/ フォルダを参照してください。
変更時は必ず関連サービスのエンジニアに確認を取ること。チームで CLAUDE.md を育てる：Git 管理と継続改善
CLAUDE.md を Git で管理する
CLAUDE.md はリポジトリにコミットし、Pull Request でレビューするべきです。「誰が何のために追加したか」のコミットメッセージが、チームの学習資産になります。
コミットメッセージ規約:
# 良いコミットメッセージの例
claude: add gotcha for auth.ts direct edit prevention
理由: 10月の事故で auth.ts を直接編集して本番が落ちた。
以後の再発防止のため Gotchas に追記。
# 悪いコミットメッセージの例
Update CLAUDE.mdPull Request テンプレートへの追加（.github/pull_request_template.md）:
## CLAUDE.md への影響
- [ ] この変更に伴う CLAUDE.md の更新が必要か確認した
- [ ] 新しい Gotchas がある場合は CLAUDE.md に追記した
- [ ] API/DB 変更がある場合は関連する rules/ ファイルを更新した月次レビューで CLAUDE.md を育てる
定例ミーティングに「CLAUDE.md レビュー」のアジェンダを 15 分追加することを強くお勧めします。実際に顧問先のチームで実施している月次レビューの議題です:
- 今月 Claude が「やらかした」パターン: Gotchas に追加すべき失敗を記録
- よく使ったプロンプトパターン: チームで共有できるテンプレートを skills/ に追加
- 不要になったルール: 削除候補を検討（CLAUDE.md は削除も大切）
- 新しいライブラリ・フレームワークの追加: 対応する rules/ ファイルが必要か確認
「Claude との仕事のやり方を記録するドキュメント」として CLAUDE.md を育てていくイメージです。
チーム内での役割分担
CLAUDE.md のメンテナンス担当を割り当てるプロンプト
以下の条件で、CLAUDE.md のメンテナンス体制を設計してください。
【チーム情報】
- チーム規模: [人数]名
- 職種構成: [例: バックエンド3名、フロントエンド4名、インフラ2名]
- 週の稼働状況: [フルタイム/パートタイム等]
【設計する体制】
1. Root CLAUDE.md のオーナー（全員のレビューが通る変更のみ実施）
2. パッケージ別 CLAUDE.md のオーナー（担当パッケージ内は自由に変更可）
3. 月次レビューのファシリテーター（持ち回り or 固定）
4. 新メンバー向けオンボーディング手順
各担当者の役割と責任範囲を明確にしてください。Anthropic 公式推奨のベストプラクティス（2026 年版）
Anthropic の公式ドキュメント「Claude Code のベストプラクティス」から、チーム運用に関わる推奨事項を整理します。
| 推奨事項 | 理由 | 実装方法 |
|---|---|---|
| 1 ファイル 200 行以下 | 後半の指示がコンテキスト不足で無視される | 大きくなったら rules/ に分割 |
| 明らかなことは書かない | 「デフォルト動作を押し出す指示だけ」が高効率 | 「削除したら Claude が間違いを犯すか？」で判断 |
| リポジトリにコミット | チームで共有・履歴管理 | .gitignore に CLAUDE.md を入れない |
| @import で分散管理 | Progressive Disclosure でコンテキスト節約 | .claude/rules/ に詳細ファイルを分離 |
| スクリプトを CLAUDE.md から参照 | 「ビルド方法」はスクリプトに書き、パスを参照 | @scripts/setup.md のように参照する |
部署・役割別 CLAUDE.md サンプル
バックエンド API チーム向け
# Backend API Team - CLAUDE.md
## Gotchas
- データベース接続は db-client.ts の singleton を使う（new PrismaClient() は直接使わない）
- 日付は全て UTC で保存・取得（表示変換はフロントエンド責務）
- ページネーションは cursor-based（offset は使わない）
## コーディング規約
- 非同期処理は async/await を使う（.then() チェーンは非推奨）
- エラーハンドリング: throw new AppError(status, message, code)
- 型: unknown を使い、as でキャストしない
## 詳細ルール
DB操作: @.claude/rules/db-conventions.md
認証関連: @.claude/rules/auth-guide.md
テスト: @.claude/rules/testing-guide.mdフロントエンド（React）チーム向け
# Frontend Team - CLAUDE.md
## Gotchas
- useEffect は最後の手段（状態の派生は useMemo/useCallback で）
- グローバル状態は Zustand を使う（Context は UI 状態のみ）
- API 呼び出しは api/client.ts を経由（直接 fetch しない）
## コンポーネント設計
- 1 コンポーネント 1 責務（150行を超えたら分割）
- props の型は明示的に定義（React.FC を使わない）
- スタイルは Tailwind CSS を使う（インラインスタイル禁止）
## 詳細ルール
コンポーネント命名: @.claude/rules/component-naming.md
アクセシビリティ: @.claude/rules/a11y-guide.mdインフラ・DevOps チーム向け
# DevOps Team - CLAUDE.md
## Gotchas
- Terraform の state ファイルは直接編集しない
- ECS タスク定義の変更は必ずステージングで 30 分動作確認
- セキュリティグループは最小権限原則（0.0.0.0/0 は絶対 NG）
## 作業手順
インフラ変更: @docs/infra/change-procedure.md
インシデント対応: @docs/infra/incident-runbook.md
コスト最適化チェック: @docs/infra/cost-review.md【要注意】チーム CLAUDE.md でよくある失敗パターン
失敗 1：「とりあえず全部書いておこう」で肥大化
❌ よくある間違い: 「これも書いておこう」「あれも必要かも」と追加を繰り返し、CLAUDE.md が 500〜1000 行に肥大化する
⭕ 正しいアプローチ: 追加前に「これを削除すると Claude が間違いを犯すか？」を問う。YESなら追加、NOなら不要
なぜ重要か: CLAUDE.md が長くなるほど後半の指示は読まれなくなります。「念のため追加した指示」が「実は邪魔になっている」状態が最もよくあるパターンです。実際に先述の 12 名チームでは、CLAUDE.md を 800 行から 120 行（Root）+ 各 rules/ ファイルに分散させることで、Claude の出力品質が改善しました。
失敗 2：属人的な CLAUDE.md で共有できない
❌ よくある間違い: 個人の ~/.claude/CLAUDE.md に全設定を書いて、チームには「なんか自分の Claude は賢い」状態
⭕ 正しいアプローチ: リポジトリの CLAUDE.md に書き、チーム全員が同じ設定で使う
なぜ重要か: 「あの人の Claude は優秀なのに自分のは…」という状況はほぼ必ず CLAUDE.md の差です。チームの共有知識として管理することで、「Claude の使い方の上手い人」が抜けても品質が落ちなくなります。
失敗 3：ルールの競合を放置する
❌ よくある間違い: Root CLAUDE.md に「コメントは英語で」と書き、packages/frontend/CLAUDE.md に「コメントは日本語で」と書いてしまう
⭕ 正しいアプローチ: 子ディレクトリの CLAUDE.md は Root を継承し、追加・上書きのみ記述する。矛盾する指示は書かない
失敗 4：「最初から完璧を目指す」で続かない
❌ よくある間違い: CLAUDE.md の整備会議を何度も開いて「完璧なドキュメント」を作ろうとして、3ヶ月後には誰もメンテしなくなる
⭕ 正しいアプローチ: まず 50 行の minimal CLAUDE.md を作り、Claude が失敗するたびに Gotchas に追記する。育てる意識
失敗 5：CLAUDE.md をソースコードと分けて管理する
❌ よくある間違い: CLAUDE.md を .gitignore に入れて個人管理にする（あるいは別 Notion ページで管理）
⭕ 正しいアプローチ: ソースコードと同じリポジトリで Git 管理。PR レビューを通じてチームのレビューを受ける
なぜ重要か: CLAUDE.md は「チームと Claude の間の契約書」です。コードが変わったのに CLAUDE.md が古いまま、というのが最もよくある問題です。コードの変更と CLAUDE.md の更新を PR で一緒にレビューする習慣が大切です。
CLAUDE.md 品質チェックプロンプト
チームの CLAUDE.md を定期的に Claude 自身にレビューさせるプロンプトです。研修先での月次レビューでそのまま使えます。
あなたは Claude Code の設定エキスパートです。
以下の CLAUDE.md を分析して品質レビューを行ってください。
【CLAUDE.md の内容】
[ここにCLAUDE.mdの全文を貼り付け]
【レビュー観点】
1. 行数チェック（200行超えていないか）
2. 矛盾した指示がないか
3. 「当たり前のことを書いている」無駄な行はないか
4. Gotchas セクションの充実度
5. Progressive Disclosure が設計されているか（詳細は rules/ に分離されているか）
6. 削除して効果がなさそうな行（候補を列挙）
7. 追加が必要そうな項目（チームでよくある問題ベース）
【改善優先度】
各項目について「今すぐ修正すべき」「余裕があれば修正」「問題なし」で分類してください。
不明点は「要確認」と明記してください。AI 導入戦略との連携
CLAUDE.md の整備は、企業全体の AI 導入戦略の一部として位置づけるべきです。開発チームの CLAUDE.md が整備されると、Claude Code の利用率・出力品質が上がり、ROI が改善されます。
AI 導入の全体像についてはAI 導入戦略完全ガイドも参照してください。Claude Code の法人導入から CLAUDE.md 整備まで、体系的に解説しています。
まとめ：今日から始める 3 つのアクション
- 今日やること: 現在の CLAUDE.md の行数を確認する。200 行を超えていたら、今日中に rules/ ファイルへの分割計画を立てる
- 今週中: チームで「最近 Claude がやらかしたパターン」を 3 つ集めて、Gotchas セクションに追記する。PR を通じて全員のレビューを受ける
- 今月中: 月次 CLAUDE.md レビューのアジェンダを定例ミーティングに追加する。「Claude の失敗 → Gotchas 追記」のフィードバックループを定常化する
次回予告: 次の記事では「Claude Code のサブエージェント設計」をテーマに、複数の専門家エージェントを CLAUDE.md で管理する方法をお届けします。
参考・出典
- Best Practices for Claude Code — Anthropic Claude Code Docs（参照日: 2026-04-25）
- GitHub – shanraisshan/claude-code-best-practice — shanraisshan（参照日: 2026-04-25）
- Writing a good CLAUDE.md — HumanLayer Blog（参照日: 2026-04-25）
- The “Virtual Monorepo” Pattern — Owen Zanzal, Medium（参照日: 2026-04-25）
- CLAUDE.md best practices – From Basic to Adaptive — DEV Community（参照日: 2026-04-25）
著者: 佐藤傑（さとう・すぐる）
株式会社 Uravation 代表取締役。早稲田大学法学部在学中に生成 AI の可能性に魅了され、X（旧 Twitter）で活用法を発信（@SuguruKun_ai、フォロワー約 10 万人）。100 社以上の企業向け AI 研修・導入支援を展開。著書『AI エージェント仕事術』（SB クリエイティブ）。SoftBank IT 連載 7 回執筆（NewsPicks 最大 1,125 ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
