結論：個人で書く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出力品質を守れます

参考リンク