Claude Code でチーム開発する実践ガイド——CLAUDE.md 共有・競合回避・権限設計の全部入り
複数人でClaude Codeを使うチーム開発の実践ガイド。CLAUDE.md の階層設計・Git Worktreeで並列作業・コンフリクト回避・権限レベル設計・オンボーディング手順まで。1人で使うのとは全然違う設計が必要になる。
エンジニアのゆとです。
Claude Codeを個人で使うのと、チームで使うのはかなり違う問題だということを、最近別の会社のエンジニアと話して実感した。
個人なら CLAUDE.md に自分の好みを書けばいい。でもチームで使うと「誰がどの設定を書くのか」「どこまで自動化を許可するか」「Claudeがpushしたら誰のコミットになるのか」みたいな問題が出てくる。
この記事はチームでClaude Codeを使うための設計の話をする。3〜15人規模の小〜中規模開発チームを想定している。
チーム開発で最初に決めること
導入前に決めておかないと後で混乱する3つのこと。
1. どのレイヤーで CLAUDE.md を管理するか
Claude Codeの設定ファイルは3層構造になっている：
~/.claude/CLAUDE.md # ユーザー個人（Gitに入れない）
プロジェクトルート/CLAUDE.md # チーム共有（Gitに入れる）
サブディレクトリ/CLAUDE.md # モジュール固有（Gitに入れる）チームで使う場合、プロジェクトルートの CLAUDE.md をGitで管理するのが基本。個人の好みはユーザー層に書いて、プロジェクト固有のルールはプロジェクト層に書く。
2. permissions の責任者を決める
~/.claude/settings.json と .claude/settings.json の両方に権限設定が書ける。チームで問題になるのはプロジェクト固有の settings.json をGitに入れるかどうか。
入れる場合は全員同じ権限設定になる（安全だが制限的）。入れない場合は各自が任意に設定できる（柔軟だが、誰かが危険な権限を開けてしまう可能性がある）。
推奨は「プロジェクト固有の設定はGitに入れる＋個人の拡張は ~/.claude/ に書く」。
3. コミットの帰属を明確にする
Claudeがコードを書いてコミットする場合、コミットの帰属が曖昧になる。チームのコーディング規約に Co-authored-by: Claude を入れるかどうかを先に決めておく。
# Claudeのコミットに自動で共同作者を追加するHook
# .claude/hooks/post-commit.sh
#!/bin/bash
git log -1 --pretty=format:"%s" | grep -q "claude" && exit 0
# 直前のコミットメッセージを取得
MSG=$(git log -1 --pretty=format:"%B")
# Co-authoredが既に含まれていれば何もしない
echo "$MSG" | grep -q "Co-authored-by" && exit 0CLAUDE.md の階層設計パターン
実際にチームで使われているパターンを3つ紹介する。
パターンA: モノリシック（小規模チーム向け）
project/
├── CLAUDE.md ← プロジェクト全体のルール
└── src/
└── ...3人以下のチームで、全員が同じコンテキストを持っている場合に向いている。CLAUDE.md に全部書く。
シンプルな反面、ファイルが肥大化しやすい。
パターンB: ドメイン分割（中規模チーム向け）
project/
├── CLAUDE.md ← 共通ルール（コーディング規約、PR手順等）
├── backend/
│ └── CLAUDE.md ← バックエンド固有（DB操作、API設計）
├── frontend/
│ └── CLAUDE.md ← フロントエンド固有（コンポーネント設計、スタイル）
└── infra/
└── CLAUDE.md ← インフラ固有（Terraform操作、AWS設定）# backend/CLAUDE.md
## このディレクトリのルール
@../CLAUDE.md を継承する。
### データベース操作
- マイグレーションファイルを自動生成しない（必ず手動で確認してからcommit）
- N+1クエリを含むコードを書かない
- トランザクションが必要な処理は明示的に書く
### API設計
- REST: /api/v1/ プレフィックスを必須
- レスポンスは必ず { data, meta, errors } の形式@../CLAUDE.md でルートの共通設定を継承できる。サブCLAUDE.mdは追加・上書きのみ書けばいい。
パターンC: ロール分離（大規模チーム向け）
project/
├── CLAUDE.md ← 全員が読む共通ルール
├── .claude/
│ ├── settings.json ← チーム共通の権限設定
│ └── commands/
│ ├── pr-review.md ← PRレビュー用スラッシュコマンド
│ ├── deploy-check.md ← デプロイ前チェック
│ └── onboarding.md ← 新メンバーオンボーディング
└── docs/
└── ai-guidelines.md ← 人間が読むAI活用ガイドラインカスタムスラッシュコマンドを使ってチームの定型作業をコマンド化する。
実際の CLAUDE.md テンプレート（チーム用）
# CLAUDE.md — チーム共通設定
## プロジェクト概要
- Next.js 15 + TypeScript + PostgreSQL
- テストフレームワーク: Jest + Playwright
- デプロイ: Vercel（main → production, staging/* → preview）
## コードを書く時のルール
- TypeScriptの型は any を使わない。unknown か型を明示する
- コメントは日本語
- コンポーネントは src/components/ 以下に置く
- API ルートは src/app/api/ 以下に置く
- DB操作は src/lib/db/ 以下に集約する
## 絶対にやってはいけないこと
- main/staging ブランチに直接 push しない
- .env ファイルを読み書きしない
- npm パッケージを勝手にインストールしない（package.json の変更は都度確認）
- データベースのマイグレーションを自動実行しない
## PRを出す前にやること
1. `npm run lint` でエラーがないこと
2. `npm run test` が通ること
3. 型エラーがないこと（`npm run type-check`）
4. 変更の概要を PR 本文に日本語で書く
## ブランチ命名規則
- feature/xxx — 機能追加
- fix/xxx — バグ修正
- refactor/xxx — リファクタリング
- docs/xxx — ドキュメント更新
## 内部のドキュメント参照
- API仕様: docs/api-spec.md
- DB スキーマ: prisma/schema.prisma
- 環境変数の説明: docs/env-vars.md権限設定（settings.json）のチーム推奨値
チームで使うプロジェクト固有の設定。安全側に倒す。
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git diff*)",
"Bash(git log*)",
"Bash(git add*)",
"Bash(git commit*)",
"Bash(git checkout*)",
"Bash(git branch*)",
"Bash(npm run*)",
"Bash(npx jest*)",
"Bash(npx playwright*)",
"Read(**)",
"Write(src/**)",
"Write(tests/**)",
"Write(docs/**)"
],
"deny": [
"Bash(git push*)",
"Bash(git rebase*)",
"Bash(git reset --hard*)",
"Bash(rm -rf*)",
"Write(.env*)",
"Write(prisma/migrations/**)"
]
}
}git push を deny にしているのがポイント。Claudeが勝手にリモートにpushする事故を防ぐ。pushは必ず人間が手動でやる設計にする。
Git Worktree で並列開発する
チームメンバーが別々のブランチで作業する場合、Git Worktreeを使うとClaudeに別ブランチのコードを参照させながら作業できる。
# feature/payment-integration ブランチの Worktree を作成
git worktree add ../myapp-payment feature/payment-integration
# 別のターミナルで Claude Code を起動
cd ../myapp-payment
claudeこの方法だと：
- メインの作業ブランチと切り離されているのでコンフリクトしない
- Claudeに「この機能ブランチのコードを参照しながら別の修正をして」と依頼できる
- 完了したら Worktree を削除するだけ
# Worktree の削除
git worktree remove ../myapp-payment詳細な Worktree の使い方は別記事で解説している。
コンフリクト回避の設計
複数人がClaude Codeを使うと、同じファイルを同時に変更するリスクが上がる。
ファイルロック的な運用
完全なロックはできないが、作業開始時に宣言するカスタムコマンドを作れる。
.claude/commands/start-work.md:
# 作業開始コマンド
引数として作業するファイルパスを受け取る。
以下を実行する:
1. git status で現在の状態を確認
2. 対象ファイルの最終更新者とコミットを git log --follow -1 で確認
3. 同じファイルを今日誰かが変更していたら警告を出す
4. 問題なければ作業を開始する
$ARGUMENTS分担の基本原則
Claude Codeを使うチームで現実的に機能するコンフリクト対策：
- ファイルを機能単位で分割する（1ファイルが1つの責務を持つ）
- Claudeに変更させるファイル範囲を指示で明示する（「src/lib/payment.ts だけを変更して」）
- PRを小さくする（大きいPRほどコンフリクトリスクが上がる）
オンボーディング用カスタムコマンド
新しいメンバーがClaude Codeを使い始める時のガイダンスをコマンド化できる。
.claude/commands/onboarding.md:
# 新メンバーオンボーディングガイド
新しくチームに参加したエンジニア向けに、このプロジェクトのコードベースを案内する。
以下の順序で説明する:
1. プロジェクト構造の全体像（ディレクトリの役割）
2. データフロー（ユーザーのリクエストがどこを通るか）
3. 主要なモジュールの説明（src/lib/ 以下のファイル）
4. よく使う開発コマンド（CLAUDE.mdのルールに基づく）
5. 最初のタスクとして試してほしい小さな改修の提案
コードを読んで説明する。推測で説明しない。/onboarding を実行すると、Claudeがコードベースを読んで新メンバー向けのガイドを生成する。ドキュメントが古くなっていても、実際のコードを読んで説明するので常に最新の状態になる。
チームでの運用コスト
実際の話をすると、チームで使う場合のコストは個人とは桁が違う。
Claude Maxは個人プラン$100/月。チーム全員にMaxを契約する場合：
| チーム規模 | 月額コスト | 年間コスト |
|---|---|---|
| 3人 | $300 | $3,600 |
| 5人 | $500 | $6,000 |
| 10人 | $1,000 | $12,000 |
現実的な対策として：
- APIキー + 予算上限 — チームで1つのAPIキーを使い、月のAPI使用量に上限を設ける（AnthropicコンソールでBudget設定）
- ロールベースの使い分け — 全員にMaxを買うより、ヘビーユーザー3人 × Max + 軽いユーザー × Proという構成
- 用途を絞る — 全作業でClaude Codeを使うのではなく、「レビュー」「テスト生成」「ドキュメント更新」に限定してAPI経由で使う
まとめ
チームでClaude Codeを使う時に設計すべきことを整理すると：
- CLAUDE.mdの階層を決める — プロジェクト共通とモジュール固有を分離する
- settings.jsonをGitに入れる — チーム全員が同じ権限制約で動くようにする
- pushだけは人間が手動でやる — 最後の砦をAIに渡さない
- 作業範囲を指示で明示する — 「このファイルだけ変更して」という習慣をチームに根付かせる
個人開発と違って、チーム開発ではAIの行動範囲を明示的に設計することが重要になる。
