結論：個人で書くCLAUDE.mdとチームで運用するCLAUDE.mdは根本的に別物
個人で書くCLAUDE.mdとチームで運用するCLAUDE.mdは、構造から更新フローまで根本的に別物でした。
個人用はうまく動いているのに、チームに展開した途端に「人によって出力がバラバラ」「誰かの変更で他の人の挙動が壊れる」といった問題が起きます。この記事では、チーム運用で実際に試して効果があった 5つの設計パターン を紹介します。
- レイヤー分離型で設定の衝突を防ぐ
- ロールベース型・フェーズ連動型で文脈に合った指示を出し分ける
- Git連携型・テンプレート継承型で運用を自動化・標準化する
これらを組み合わせることで、チーム全員が一貫した品質でClaude Codeを活用できるようになります。
環境・前提条件
| 項目 | 内容 |
|---|---|
| Claude Code | 最新版（2025年6月時点） |
| チーム規模 | 3〜15名程度の開発チームを想定 |
| バージョン管理 | Git（GitHub / GitLab） |
| 前提知識 | CLAUDE.mdの基本的な書き方を理解していること |
Claude Codeでは、以下の3つのスコープでCLAUDE.mdを配置できます。
-
~/.claude/CLAUDE.md— グローバル（ユーザー単位） -
プロジェクトルート/CLAUDE.md— プロジェクト単位（Gitリポジトリにコミット可能） -
任意ディレクトリ/CLAUDE.md— サブディレクトリ単位で追加指示
この仕組みを理解した上で、チーム運用の設計に進みましょう。
なぜ個人用CLAUDE.mdをそのままチームに持ち込むと破綻するのか
個人用CLAUDE.mdが破綻する理由は明確です。「自分にとっての暗黙知」がそのまま書かれているからです。
典型的な破綻パターンを挙げます。
| 問題 | 具体例 |
|---|---|
| 暗黙の前提 | 「TypeScriptで書いて」→ バックエンドチームはGoを使っている |
| 個人の好み汚染 | 「関数型スタイルで」→ チームの既存コードはクラスベース |
| 肥大化 | 1人が足し続けて500行超え → 指示が矛盾し始める |
| 更新の衝突 | 複数人が同時編集 → マージコンフリクト地獄 |
| 文脈の欠如 | フロントの人の指示がバックエンドの作業時にも適用される |
個人用は「自分だけが使う前提」で最適化されています。チームに持ち込むには、責務の分離と更新ルールの合意が必要です。
パターン1: レイヤー分離型（global / project / personal の3層構成）
最も基本かつ重要なパターンです。Claude Codeが提供する3つのスコープを明確に使い分けます。
各レイヤーの責務
Global（個人） — .gitignore で管理外。各自が自由に設定。
# ~/.claude/CLAUDE.md
- 日本語で応答してください
- 説明は簡潔に、コード例を優先してください
Project（チーム共有） — Gitにコミットし、PRでレビュー。
# /project-root/CLAUDE.md
## 技術スタック
- 言語: TypeScript 5.x (strict mode)
- フレームワーク: Next.js 15 (App Router)
- ORM: Prisma
- テスト: Vitest + Testing Library
## コーディング規約
- 関数コンポーネントのみ使用（クラスコンポーネント禁止）
- 型定義は `types/` ディレクトリに集約
- エラーハンドリングは Result 型パターンを使用
## 禁止事項
- any 型の使用禁止
- console.log をプロダクションコードに残さない
Personal（個人ローカル） — .gitignore に追加して管理外に。
# /project-root/.claude/CLAUDE.local.md
- 現在のタスク: ユーザー認証機能の実装
- 関連ファイル: src/features/auth/ 配下を中心に作業中
運用のポイント
- Project層は チームリード or テックリードが管理者
- 変更は必ずPRを通す（後述のパターン4と組み合わせる）
-
.claude/CLAUDE.local.mdは.gitignoreに追加しておく
パターン2: ロールベース型（フロント・バック・インフラで分岐）
チーム内に複数の技術領域がある場合、ディレクトリ単位でCLAUDE.mdを配置して指示を分岐させます。
project-root/
├── CLAUDE.md # 共通ルール
├── frontend/
│ ├── CLAUDE.md # フロントエンド固有
│ └── src/
├── backend/
│ ├── CLAUDE.md # バックエンド固有
│ └── src/
└── infra/
├── CLAUDE.md # インフラ固有
└── terraform/
各ロールのCLAUDE.md例
frontend/CLAUDE.md:
## フロントエンド固有ルール
- コンポーネントは Atomic Design に従う
- スタイリングは Tailwind CSS のみ（CSS Modules 禁止）
- 状態管理は Zustand を使用
- アクセシビリティ: WAI-ARIA 準拠必須
backend/CLAUDE.md:
## バックエンド固有ルール
- APIは RESTful 設計（OpenAPI 3.1 準拠）
- バリデーションは Zod で実装
- DBアクセスは Repository パターンで抽象化
- エラーレスポンスは RFC 7807 (Problem Details) 形式
メリット
Claude Codeはカレントディレクトリから上位に向かってCLAUDE.mdを探索するため、作業ディレクトリに応じて自動的に適切な指示が適用されます。フロント担当者がバックエンドのルールに引きずられることがなくなります。
パターン3: フェーズ連動型（設計→実装→レビューで切り替え）
開発フェーズによってClaude Codeに求める役割は変わります。これを明示的に切り替えるパターンです。
実装方法
フェーズごとに別ファイルを用意し、シンボリックリンクやスクリプトで切り替えます。
project-root/
├── .claude/
│ ├── phases/
│ │ ├── design.md
│ │ ├── implement.md
│ │ └── review.md
│ └── switch-phase.sh
└── CLAUDE.md # ← シンボリックリンク or include
switch-phase.sh:
#!/bin/bash
PHASE=${1:-implement}
cp ".claude/phases/${PHASE}.md" CLAUDE.md
echo "Switched CLAUDE.md to: ${PHASE} phase"
実用的な運用
実際には、スクリプトで切り替えるよりも CLAUDE.md内にフェーズセクションを並記 し、「現在のフェーズ：実装」と1行書き換える方が手軽です。Claude Codeは文脈を理解できるので、「現在のフェーズに該当するセクションに従ってください」で十分機能します。
## 現在のフェーズ: 実装
### 設計フェーズのルール
（省略 — このフェーズでは参考程度に）
### 実装フェーズのルール ← 現在アクティブ
- テストを先に書く
- 1コミット1関心事
- ...
### レビューフェーズのルール
（省略 — このフェーズでは参考程度に）
パターン4: Git連携型（PRごとにCLAUDE.mdの差分をレビュー対象にする）
CLAUDE.mdの変更が「いつの間にか」行われると、チーム全体の出力品質が静かに崩壊します。これを防ぐのがGit連携型です。
具体的な仕組み
1. CIでCLAUDE.mdの変更を検知してラベルを付ける
# .github/workflows/claude-md-review.yml
name: CLAUDE.md Change Detection
on: [pull_request]
jobs:
detect:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check CLAUDE.md changes
run: |
if git diff --name-only origin/main...HEAD | grep -q "CLAUDE.md"; then
echo "claude_md_changed=true" >> $GITHUB_OUTPUT
gh pr edit ${{ github.event.number }} --add-label "claude-md-change"
fi
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
2. CODEOWNERS で特定メンバーの承認を必須にする
# .github/CODEOWNERS
CLAUDE.md @tech-lead @ai-champion
**/CLAUDE.md @tech-lead @ai-champion
3. PRテンプレートにCLAUDE.md変更理由の記載欄を設ける
## CLAUDE.md 変更（該当する場合）
- [ ] 変更理由を記載した
- [ ] 既存ルールとの矛盾がないことを確認した
- [ ] チームメンバーに影響を説明した
なぜここまでやるのか
CLAUDE.mdはチーム全員のAI出力を左右する設定ファイルです。本番環境の設定ファイル（.env や terraform.tfvars）と同じ重要度で管理すべきです。
パターン5: テンプレート継承型（ベーステンプレート＋チーム固有オーバーライド）
複数のプロジェクトやチームが同じ組織内にある場合、組織共通のベーステンプレートを用意し、各チームがオーバーライドする構成です。
実装方法
組織テンプレートを別リポジトリまたはパッケージとして管理します。
org-claude-template（組織共通）:
# 組織共通ルール（必ず遵守）
## セキュリティ
- シークレット情報をコードに含めない
- SQLは必ずプリペアドステートメントを使用
- ユーザー入力は必ずバリデーション
## 品質基準
- テストカバレッジ 80% 以上を維持
- Linter の警告をゼロに保つ
- 関数は50行以内を目安
各チームのCLAUDE.md:
# チームA CLAUDE.md
## 組織共通ルール
<!-- org-claude-template v2.1 を適用 -->
<!-- 以下のルールを遵守: セキュリティ / 品質基準 / ログ出力 -->
上記の組織共通ルール（org-claude-template v2.1）に従ってください。
特に、シークレット情報のハードコーディング禁止は厳守。
## チーム固有ルール
- フレームワーク: Next.js 15
- 状態管理: Jotai（Zustandから移行中）
- API通信: TanStack Query v5
更新フロー
- 組織テンプレートが更新されたら、各チームに通知（Slack Bot等）
- 各チームは自チームのCLAUDE.mdに反映するPRを作成
- 組織テンプレートのバージョンを明記しておき、追跡可能にする
実運用で落ち着いた構成と更新ルール
試行錯誤の結果、私たちのチーム（バックエンド5名 + フロントエンド3名）では パターン1 + パターン2 + パターン4の組み合わせ に落ち着きました。
採用した構成
project-root/
├── CLAUDE.md # 共通ルール（技術スタック・禁止事項）
├── .claude/
│ └── CLAUDE.local.md # 個人用（.gitignore対象）
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # フロントエンド固有
│ └── api/
│ └── CLAUDE.md # バックエンド固有
├── .github/
│ └── CODEOWNERS # CLAUDE.md変更はテックリード承認必須
└── .gitignore # .claude/CLAUDE.local.md を除外
運用ルール（チーム内で合意済み）
| ルール | 内容 |
|---|---|
| 更新頻度 | スプリント単位で棚卸し（2週間に1回） |
| 変更権限 | 誰でもPRを出せるが、テックリードの承認必須 |
| 記述量の上限 | 1ファイル100行以内（超えたら分割を検討） |
| 具体例の必須化 | ルールには必ず良い例・悪い例を添える |
| 廃止ルールの扱い | 削除ではなくコメントアウトし、理由を残す |
CLAUDE.mdの棚卸しチェックリスト
スプリント振り返りで以下を確認しています。
- 使われていないルールはないか
- 矛盾するルールが追加されていないか
- Claude Codeの出力で繰り返し手動修正している箇所はないか（→ ルール追加の候補）
- 行数が上限を超えていないか
まとめ
- レイヤー分離が最優先: Global / Project / Personalの3層を明確に分け、Git管理の境界を設定することが、チーム運用の出発点です
- 文脈の切り替えを仕組み化する: ロールやフェーズに応じた指示の出し分けを、ディレクトリ構成やセクション設計で実現すると、Claude Codeの出力精度が安定します
- CLAUDE.mdはインフラ設定と同等に管理する: PRレビュー必須・CODEOWNERS設定・定期棚卸しの3点セットで、チーム全体のAI出力品質を守れます