結論：CLAUDE.mdは「チームの暗黙知」を形式知に変える設計書
Claude Codeをチームで使い始めた瞬間、「人によって出力が全然違う」 問題にぶつかりませんでしたか？
同じリポジトリで作業しているのに、Aさんが生成したコードはTypeScript厳格モード準拠、Bさんのコードはanyだらけ。Cさんはテストを書いてくれるけど、Dさんはテストなし――。この問題の根本原因は指示の属人化です。
解決策はシンプルです。CLAUDE.mdファイルにチームの設計方針・制約・ルールを書き、リポジトリにコミットする。これだけで、誰がClaude Codeを使っても再現性のある出力が得られるようになります。
この記事では、実践で使える 7つの設計パターン を具体的なスニペット付きで紹介します。
環境・前提条件
| 項目 | 内容 |
|---|---|
| ツール | Claude Code（CLI） |
| CLAUDE.mdの配置 | プロジェクトルート直下 ./CLAUDE.md
|
| 対象読者 | Claude Codeをチーム（2名以上）で利用するエンジニア |
| 前提知識 | Claude Codeの基本操作、Git運用の基礎 |
CLAUDE.mdは階層構造で配置でき、プロジェクトルートのほか、サブディレクトリごとに設置して指示をスコーピングすることも可能です。また、ユーザー個人のホームディレクトリ（~/.claude/CLAUDE.md）に置くことで、個人設定とプロジェクト設定を分離できます。
なぜCLAUDE.mdが必要か ― 個人利用とチーム利用の決定的な差
個人利用であれば、毎回のプロンプトで「TypeScriptのstrictモードで書いて」「テストも書いて」と指示すれば済みます。しかしチーム開発では、次の3つの問題が生まれます。
- 指示のバラつき ― 人によって伝える粒度・内容が異なる
- 暗黙知の共有漏れ ― 「うちのプロジェクトではこうする」が口頭伝承になる
- レビューコストの増大 ― AI生成コードの品質がバラバラでレビューが重くなる
CLAUDE.mdは、この3つを一つのファイルで解決します。Claude Codeは会話の開始時にCLAUDE.mdを自動的に読み込むため、チームメンバー全員が同じコンテキストでAIを使えるようになります。
7つの設計パターン ― 全体マップ
まず、7つのパターンの全体像を俯瞰しましょう。
パターンごとの実例CLAUDE.mdスニペット
パターン1：コーディング規約型
適用場面： コードスタイルのバラつきを防ぎたいとき
# コーディング規約
## TypeScript
- strictモードを必ず有効にすること
- `any`型の使用は禁止。やむを得ない場合は`unknown`を使い、型ガードで絞り込む
- 関数の戻り値の型は必ず明示する（型推論に頼らない）
- 変数宣言は`const`をデフォルトとし、再代入が必要な場合のみ`let`を使う
- `enum`ではなく`as const`のオブジェクトを使用する
## 命名規則
- コンポーネント: PascalCase（例: `UserProfile.tsx`）
- ユーティリティ関数: camelCase（例: `formatDate.ts`）
- 定数: UPPER_SNAKE_CASE（例: `MAX_RETRY_COUNT`）
- テストファイル: `*.test.ts` または `*.spec.ts`
ポイント： 「〇〇しないこと」だけでなく 「代わりにどうするか」 を書くと遵守率が上がります。
パターン2：アーキテクチャ制約型
適用場面： レイヤー構成や依存方向を守らせたいとき
# アーキテクチャ制約
## ディレクトリ構成とレイヤー
このプロジェクトはクリーンアーキテクチャに準拠する。
src/
├── domain/ # エンティティ・値オブジェクト・リポジトリインターフェース
├── application/ # ユースケース（domain層のみに依存）
├── infrastructure/ # DB・外部API実装（domain層のインターフェースを実装）
└── presentation/ # コントローラ・ルーティング（application層に依存）
## 依存ルール
- domain層は他のどの層にも依存してはならない
- application層はdomain層にのみ依存する
- infrastructure層・presentation層がdomain層のインターフェースをimportすることは許可する
- presentation層からinfrastructure層を直接importしてはならない
## 使用ライブラリ制約
- ORMは Prisma のみ使用可（TypeORMやSequelizeは使わない）
- HTTPクライアントは標準の fetch API を使用する（axiosは使わない）
- 状態管理はZustandを使用する（Reduxは使わない）
パターン3：レビュー基準型
適用場面： AI生成コードのセルフレビューをClaude自身にさせたいとき
# レビュー基準
コードを生成・修正した後は、以下のチェックリストで自己レビューを行い、
結果を出力の末尾に表示すること。
## チェックリスト
- [ ] 新しい関数にはJSDocコメントがあるか
- [ ] エラーハンドリングは適切か（try-catchの握りつぶしがないか）
- [ ] 既存のテストが壊れていないか（関連するテストファイルの確認）
- [ ] 新規ロジックに対するユニットテストを追加したか
- [ ] セキュリティ上の懸念はないか（SQLインジェクション、XSSなど）
- [ ] パフォーマンスに影響する処理（N+1クエリ等）がないか
パターン4：禁止操作型
適用場面： 触ってはいけない領域・実行してはいけないコマンドを明示したいとき
# 禁止操作
## 変更禁止ファイル
以下のファイルは絶対に変更しないこと。変更が必要な場合は提案のみ行い、実際の変更は行わない。
- `src/core/auth/` 配下の全ファイル（セキュリティクリティカル）
- `prisma/migrations/` 配下の既存マイグレーションファイル
- `.github/workflows/` 配下のCIパイプライン定義
- `package.json` の `engines` フィールド
## 実行禁止コマンド
- `rm -rf` は使用禁止
- `git push --force` は使用禁止
- `npx prisma migrate reset` は本番データ消失リスクがあるため使用禁止
- `DROP TABLE` / `TRUNCATE` を含むSQLは実行禁止
## 使用禁止API
- `eval()` や `Function()` コンストラクタ
- `document.write()`
- `innerHTML`（XSSリスク。代わりに `textContent` または適切なサニタイズを使う）
パターン5：出力フォーマット型
適用場面： コミットメッセージやドキュメントの形式を統一したいとき
# 出力フォーマット
## コミットメッセージ規約
Conventional Commitsに従うこと。
形式: `<type>(<scope>): <description>`
typeの選択肢:
- feat: 新機能
- fix: バグ修正
- refactor: リファクタリング（機能変更なし）
- test: テストの追加・修正
- docs: ドキュメントのみの変更
- chore: ビルド・CI等の雑務
例: `feat(user): ユーザープロフィール編集APIを追加`
## PR説明文テンプレート
PRの説明文を作成する際は以下の構成で書くこと:
1. **変更概要**（1〜2文で要約）
2. **変更理由**（なぜこの変更が必要か）
3. **変更内容**（箇条書きで主要な変更点を列挙）
4. **テスト方法**（どう動作確認したか）
5. **影響範囲**（他機能への影響有無）
パターン6：コンテキスト注入型
適用場面： ビジネスドメインやプロジェクト固有の前提知識を共有したいとき
# プロジェクトコンテキスト
## サービス概要
このプロジェクトは「TaskFlow」というB2B向けタスク管理SaaSのバックエンドAPIです。
## ドメイン用語集
| 用語 | 定義 |
|------|------|
| ワークスペース | 企業単位の最上位のグループ。テナントに相当する |
| ボード | プロジェクト単位のタスク管理領域 |
| チケット | 個別のタスク。ステータス（Open/InProgress/Done/Closed）を持つ |
| スプリント | 1〜4週間の作業期間。ボードに紐づく |
| アサイニー | チケットの担当者。1チケットにつき1名のみ |
## 重要なビジネスルール
- ワークスペースをまたぐデータ参照は絶対に許可しない（テナント分離）
- チケットのステータス遷移は Open→InProgress→Done→Closed の順のみ許可
- Closedのチケットは再オープン不可（新しいチケットを作成する運用）
- スプリントの期間は最大4週間。4週間を超える設定はバリデーションエラーとする
ポイント： 用語集があるだけで、Claude Codeが生成する変数名・コメント・エラーメッセージの品質が劇的に変わります。
パターン7：段階的思考強制型
適用場面： 複雑な実装でいきなりコードを書かせず、設計を先に確認したいとき
# 作業プロセス
## 実装前の確認義務
新機能の実装やリファクタリングを依頼された場合、以下のステップを必ず踏むこと。
### Step 1: 影響範囲の分析
- 変更対象のファイルを一覧化する
- 依存関係のあるモジュールを洗い出す
- 既存テストへの影響を確認する
### Step 2: 設計案の提示
- 実装方針を2〜3案提示する（それぞれのPros/Consを明記）
- ユーザーに選択を求める
- **ユーザーの承認なしにコード変更に着手しない**
### Step 3: 段階的な実装
- 1つの論理的な変更単位ごとにコードを生成する
- 各ステップで「ここまでの変更内容」のサマリーを表示する
- テストを先に書き、その後で実装コードを書く（TDDスタイル）
### Step 4: 最終確認
- 全変更のdiffサマリーを表示する
- レビュー基準（上記チェックリスト）でセルフレビューを行う
CLAUDE.mdのバージョン管理とPRレビューフロー
CLAUDE.mdはアプリケーションコードと同じくGitで管理すべきです。チームの設計方針が変われば、CLAUDE.mdも更新されるべきであり、その変更はPRを通じてレビューされるべきです。
運用のポイント
- CLAUDE.mdの変更PRには最低2名のApproveを必須にする（チーム全体のAI出力品質に影響するため）
- PRの説明文には 「なぜこのルールを追加/変更するのか」 を必ず記載する
- 定期的（月1回程度）にCLAUDE.mdの棚卸しを実施し、形骸化したルールを削除する
- CLAUDE.mdが肥大化してきたら、ディレクトリ単位のCLAUDE.mdにルールを分割する
カスタムコマンド（/commands）との使い分け判断基準
Claude Codeには、.claude/commands/ ディレクトリにMarkdownファイルを置くことでカスタムスラッシュコマンドを定義できる機能があります。CLAUDE.mdとの使い分けに迷うことがあるため、判断基準を整理します。
| 比較軸 | CLAUDE.md | カスタムコマンド（/commands） |
|---|---|---|
| 適用タイミング | 毎回のセッション開始時に自動読み込み | ユーザーが明示的に呼び出したときのみ |
| 用途 | 常時適用したいルール・制約 | 特定タスクの手順をテンプレ化 |
| 粒度 | プロジェクト全体の方針 | 個別のタスク実行手順 |
| 管理方法 | プロジェクトルートに配置 |
.claude/commands/ に配置 |
判断の原則：「常時適用か、オンデマンドか」 で切り分けましょう。
アンチパターン：CLAUDE.mdに書いても効かない指示とその回避策
CLAUDE.mdは万能ではありません。以下のような書き方をすると、意図通りに動かないことがあります。
❌ アンチパターン1：曖昧すぎる指示
# 悪い例
- きれいなコードを書いてください
- 適切にエラーハンドリングしてください
- パフォーマンスを意識してください
なぜ効かないか： 「きれい」「適切」「意識」の基準がないため、出力がブレます。
# 良い例
- 1関数あたり30行以内に収める。超える場合はプライベート関数に分割する
- 外部API呼び出しは必ずtry-catchで囲み、リトライ（最大3回、指数バックオフ）を実装する
- データベースクエリにはインデックスが効くカラムでのWHERE句を必須とし、EXPLAIN結果を確認する
❌ アンチパターン2：情報量が多すぎる（トークン溢れ）
CLAUDE.mdが数千行になると、Claude Codeのコンテキストウィンドウを圧迫し、肝心のタスク遂行に使える容量が減ります。
回避策：
- CLAUDE.mdは500行以内を目安にする
- 詳細な仕様はCLAUDE.mdから外部ドキュメントへの参照（ファイルパス）で誘導する
- ディレクトリごとのCLAUDE.mdにルールを分散させる
❌ アンチパターン3：矛盾するルール
# 悪い例
- コードにはコメントを必ず付けること
- （別のセクションで）コードは自己文書化すべき。不要なコメントは書かないこと
回避策： CLAUDE.mdを追記するだけでなく、定期的に通読して矛盾をチェックする。PRレビューで矛盾検知を行うのが効果的です。
❌ アンチパターン4：Claude Codeの能力を超えた指示
# 悪い例
- 本番サーバーにSSH接続してログを確認すること
- Figmaのデザインカンプを見て画面を実装すること
回避策： CLAUDE.mdに書くのは、Claude Codeがローカル環境で実行可能な範囲の指示に限定しましょう。
まとめ ― CLAUDE.mdはチームの「暗黙知」を形式知に変える設計書
- 7つのパターンを組み合わせることで、コーディング規約からビジネスロジック、作業プロセスまで幅広い「チームの暗黙知」をCLAUDE.mdに形式知化できます
- CLAUDE.mdはコードと同じくGitで管理し、PRレビューを通すことで、チーム全員が合意したルールとして機能します
- 常時適用のルールはCLAUDE.md、オンデマンドの手順はカスタムコマンドと使い分け、過度にCLAUDE.mdを肥大化させないことが長期運用のコツです
CLAUDE.mdを整備することは、AIツールの設定というよりもチームの設計方針を言語化する行為です。「自分たちはどういうコードを良しとするのか」を明文化するプロセスそのものが、チームの成熟度を引き上げてくれるはずです。