この記事でわかること

チームで CLAUDE.md を共有・管理するときの設計パターン
「個人ルール」と「チームルール」を分離する方法
CLAUDE.md の肥大化を防ぐメンテナンス戦略
新メンバーが即戦力になる CLAUDE.md の書き方
コードレビューの指摘が半分になった具体的な設定例

はじめに

個人で CLAUDE.md を整備した後、チームに展開しようとしてはまった話をよく聞きます。

「自分のルールをそのままチームに押し付けて反発された」
「みんなが好き勝手に追記して 500 行になった」
「新メンバーが何を信じればいいかわからなくなった」

この記事では、チームで CLAUDE.md を運用してコードレビューの指摘が半減した実例をもとに、設計パターンをまとめます。

設計の大原則：3 層構造

チーム運用の基本は「誰が書いたルールか」を明確に分けることです。

~/.claude/CLAUDE.md          ← 個人設定（git管理しない）
.claude/CLAUDE.md            ← プロジェクト共通（git管理）
CLAUDE.md                    ← リポジトリルート（最重要）

Claude は上から順に読み込み、下のファイルが優先されます。

優先度（高）
    ↑
CLAUDE.md（プロジェクトルート）
.claude/CLAUDE.md
~/.claude/CLAUDE.md
    ↓
優先度（低）

レイヤー別の書き方

1. リポジトリ CLAUDE.md（全員が守るルール）

ここには「なぜそうするか」を書く

# プロジェクト名 — Claude Code 設定

## このプロジェクトについて
Next.js 14 + TypeScript の B2B SaaS。
月1000件の仕訳を処理する会計システム。

## 絶対ルール（理由付き）

### any 型禁止
理由: 本番で型エラーが出て障害になった経緯がある。
代替: `unknown` + type guard を使う。

### console.log を残さない  
理由: 本番ログに個人情報が混入した事故があった。
代替: `logger.ts` の `logger.debug()` を使う。

### API レスポンスは必ず zod でバリデーション
理由: 外部 API の仕様変更で無言でデータが壊れた。
代替: `z.parse()` でランタイム検証を入れる。

「なぜ」があるルールは Claude が本質を理解して応用できます。「〜禁止」だけだと類似ケースで判断を誤ります。

2. .claude/CLAUDE.md（技術スタック・開発フロー）

## 技術スタック

- フロントエンド: Next.js 14 App Router, Tailwind CSS
- バックエンド: Node.js 18, Prisma, PostgreSQL
- テスト: Vitest, Testing Library
- CI: GitHub Actions

## コンポーネント設計

- Server Component をデフォルト
- `use client` は状態・イベントが必要な場合のみ
- Props は `interface` で定義（`type` ではなく）
- ファイル名 = コンポーネント名（PascalCase）

## よく使うコマンド

- 開発: `npm run dev`
- テスト: `npm run test`
- 型チェック: `npm run typecheck`
- DB マイグレーション: `npm run db:migrate`

3. ~/.claude/CLAUDE.md（個人設定）

## 個人設定（チームには適用しない）

- 説明は日本語で
- コードコメントは英語で
- 変更前に必ず現状を確認してから修正する
- 一度に複数ファイルを変更するときは、変更前に一覧を見せる

## 自動承認（個人判断）
- `npm run test` は自動承認
- `git status`, `git diff` は自動承認

チームで起きる「CLAUDE.md 崩壊パターン」と対策

❌ パターン 1：全部 CLAUDE.md に書く

# CLAUDE.md（崩壊版・500行）

## TypeScript ルール
（50行）

## React ルール
（80行）

## API ルール
（60行）

## テストルール
（70行）

## データベースルール
（80行）

## セキュリティルール
（90行）

## デプロイメント手順
（70行）

Claude のコンテキストが消費され、重要なルールが無視されます。

✅ 対策：@include で分割管理

# CLAUDE.md（60行以内）

## 絶対ルール（5つまで）
- any 型禁止
- console.log 残さない
- zod バリデーション必須
- コミット前に npm test
- 本番 DB への直接 write 禁止

## 詳細ルール（必要なときだけ読む）
@include .claude/rules/typescript.md
@include .claude/rules/react.md
@include .claude/rules/api.md
@include .claude/rules/database.md

.claude/rules/
├── typescript.md   （TypeScript固有ルール）
├── react.md        （Reactコンポーネントルール）
├── api.md          （APIエンドポイントルール）
└── database.md     （DB操作ルール）

❌ パターン 2：ルールの理由がない

- スタイルは Tailwind のみ
- Prisma の直接クエリ禁止
- エラーハンドリングは必ず入れる

Claude が例外ケースで判断できず、毎回確認してきます。

✅ 対策：決定記録（ADR スタイル）で書く

## スタイル: Tailwind のみ
決定日: 2025-10
理由: styled-components と混在してバンドルサイズが 2 倍になった。
例外: Storybook のデコレーターは styled-components を使ってもよい。

## DB アクセス: Prisma Client 経由のみ
理由: 直接 SQL だとマイグレーション管理が壊れる事故があった（2025-08）。
例外: 集計クエリでパフォーマンスが問題になる場合は DBA に確認後に SQL 可。

❌ パターン 3：古いルールが残り続ける

6ヶ月後には「なんでこのルールあるんだっけ？」というものが増えます。

✅ 対策：有効期限と棚卸しサイクル

## ルール棚卸し
最終確認: 2026-05-01
次回確認: 2026-08-01
担当: チームリーダー

## 期限付きルール
- `useEffect` の依存配列に `eslint-disable` を使わない
  有効期限: 2026-06-30（React 19 移行後に削除予定）

新メンバー向け CLAUDE.md の書き方

新メンバーが初日から Claude を正しく使えるようにするセクションを追加します：

## 新しく参加した方へ

### このプロジェクトの Claude の使い方

1. コードを書く前に必ず既存の実装を確認してもらう
   「src/components/Button.tsx を参考にして新しいコンポーネントを作って」

2. 変更の影響範囲を確認してから進める
   「この変更が影響するファイルを教えて」

3. わからないことは聞く前に調べてもらう
   「このエラーの原因を調べて」

### やってはいけないこと

- 「全部書き直して」（段階的に変更する）
- 「最適化して」（具体的に何を最適化するか指定する）
- 「テスト書いて」（どのファイルのテストか指定する）

コードレビューの指摘が半減した設定例

実際に効果があった CLAUDE.md の設定パターンです：

Before（指摘が多かった）

## コーディングルール
- TypeScript の any 禁止
- コメントを書く
- テストを書く

After（指摘が半減した）

## コードレビューで繰り返し指摘されること

### 型定義
- `any` は `unknown` + type guard に変える
- API レスポンスは必ず型定義する（`Response` 型を作る）
- `as` キャストは最終手段。使う場合はコメントで理由を書く

### コメント
- なぜそうするかを書く（何をするかはコードで分かる）
- TODO は必ず担当者と期限を書く: `// TODO(hiroto): 2026-06-30 までに修正`

### テスト
- ハッピーパスと境界値を必ずテストする
- モックは最小限にする（実際の動作に近いテストが信頼できる）
- テストの説明は「〜のとき、〜になること」の形式で書く

### PR の大きさ
- 1 PR = 1 つの目的
- 300 行を超えたら分割を検討する
- レビュワーが 30 分以内に読める量にする

「指摘されること」として書くと、Claude が自分でチェックして修正してくれます。

運用フロー

新しいルールの追加
     ↓
1. チームで合意（Slack/PR で議論）
2. 「なぜ」を含めて CLAUDE.md に追記
3. 全員が Claude Desktop を再起動
4. 1 週間後に効果確認
     ↓
効果なし → 削除
効果あり → 残す
     ↓
3ヶ月に1回、全ルールを棚卸し

まとめ

やること	効果
3 層構造（個人/プロジェクト/リポジトリ）で分離	個人ルールがチームに混入しない
ルールに「なぜ」を書く	Claude が例外ケースでも正しく判断
@include で分割管理	コンテキスト消費を最小化
新メンバー向けセクションを追加	初日から正しく使える
3ヶ月に1回の棚卸し	ルールの陳腐化を防ぐ

CLAUDE.md は「書いたら終わり」ではなく「チームの暗黙知を蓄積するドキュメント」です。コードレビューで同じ指摘が繰り返されたら、それは CLAUDE.md に書くサインです。

よくある質問（FAQ）

Q. CLAUDE.md の変更はすぐ反映されますか？
A. Claude Desktop を再起動しなくても、次のターンから反映されます。大きな変更のときは念のため再起動を推奨します。

Q. CLAUDE.md を .gitignore に入れるべきですか？
A. チームルールは git 管理を推奨します。個人設定は ~/.claude/CLAUDE.md に書いて git 管理しないのがベストプラクティスです。

Q. ルールが多すぎて Claude が無視するようになりました
A. 60 行を超えたら @include で分割してください。また「絶対ルール」を 5 個以内に絞り、残りは参照形式にすると優先度が明確になります。

Q. チームメンバーによって Claude の挙動が違うのはなぜですか？
A. ~/.claude/CLAUDE.md の個人設定が影響しています。共通にしたいルールはリポジトリの CLAUDE.md に書いてください。