Claude Code の CLAUDE.md 設計パターン完全ガイド
はじめに
Claude Code を使い始めてしばらくすると、2つの壁にぶつかる。
壁1：「CLAUDE.md に何を書けばいいのか分からない」
公式ドキュメントには「プロジェクトのコンテキストを書く場所」とあるが、実際のところ何をどのレイヤーに書き、どう構造化すれば AI が本当に「賢く動く」のかは試行錯誤なしには分からない。
壁2：「CLAUDE.md にルールを書いたのに、Claude が守ってくれない」
実はこれは仕様だ。Claude Code の公式ドキュメントには明記されている。
CLAUDE.md はアドバイザリー（約70%遵守）。Hooks は100%決定論的に実行される。
CLAUDE.md は LLM へのソフトな指示にすぎない。確率的にしか守られない。一方、Hooks（フック）はシェルコマンドとして実行されるため100%動作する。
この前提を踏まえた上で、「それでも CLAUDE.md を最大限に活かすにはどう設計すればよいか」を実践的なパターンで解説する。筆者は複数プロジェクト・数十本のスキルを横断管理する Vault 環境を運用してきた中で、以下のパターンを確立した。
CLAUDE.md の基本構造：3レイヤー設計
Claude Code は CLAUDE.md を 3つのスコープ で読み込む。
~/.claude/CLAUDE.md # グローバル（全プロジェクト共通）
<プロジェクトルート>/CLAUDE.md # プロジェクトスコープ
<サブディレクトリ>/CLAUDE.md # ローカルスコープ
| レイヤー | 書くべき内容 | 書いてはいけないもの |
|---|---|---|
| グローバル | 言語設定・出力形式・汎用ルール・セキュリティポリシー | プロジェクト固有の仕様 |
| プロジェクト | フォルダ構造・ルール・検索規則 | 個人の認証情報・シークレット |
| ローカル | サブシステムの詳細仕様 | 上位レイヤーと重複する内容 |
グローバルに書くべきこと（セキュリティルール・言語設定等）とプロジェクト固有に書くべきことを分離する設計が基本になる。
パターン1: 優先度階層を明示する
複数の CLAUDE.md が存在する場合、どのルールが優先されるかを ファイル冒頭に明示する。
> 優先度: グローバル `~/.claude/CLAUDE.md` > このファイル > PJローカル `CLAUDE.md`
これだけで Claude が複数の CLAUDE.md を参照した際の判断精度が上がる。特にグローバルにセキュリティルールを書いておくと、プロジェクト側がどう書かれていてもセキュリティポリシーが優先される。
パターン2: Map パターン（フォルダ構造を宣言する）
最も効果の高いパターンの一つが 冒頭にフォルダマップを置く ことだ。
## Map
| フォルダ | 内容 |
|---------|------|
| `00_Inbox/` | 未整理メモの一時置き場 |
| `01_Projects/Products/` | サービス化・収益化PJ |
| `02_Knowledge/` | 永続参照ノート |
| `03_Archive/` | 完了PJ（**検索対象外**） |
Claude はプロジェクト全体のファイル構造を把握していない。マップを渡すことで「どこを見ればよいか」を一発で理解させられる。
重要: 03_Archive/ は検索対象外 のような 除外指示 を必ず書く。これがないと Claude が不要なファイルを参照して無駄なトークンを消費し、誤回答を生む。
詳細なツリーは別ファイルに切り出すと CLAUDE.md が肥大化しない。
詳細ツリー: → `.claude/docs/vault-structure.md`
パターン3: 検索戦略を明示する
Claude はデフォルトでは Grep や Glob を使って全ファイルを走査しようとする。これはトークンの無駄遣いになる。使い分けルールを明示しておく。
## 検索ルール
以下の優先順で使い分ける。Vault全走査しない。`03_Archive/` は除外。
1. **特定ファイル名・正確なキーワード** → Grep/Glob（高速・正確・コスト最小）
2. **概念・文脈検索 / 3PJ以上横断** → RAG検索ツールを優先（Grepをn回繰り返すより速い）
3. **特定ノートの関連ノート発見** → find_similar_notes ツール
4. **上記全て失敗** → Glob広範囲でフォールバック
ポイント: 「失敗したらどうするか」のフォールバックチェーンを定義すること。これがないと Claude がループする。
このような「検索フローチャート」を書くと、「〜に関するノートを探して」のような曖昧な指示に対して Claude が適切なツールを選択するようになる。
パターン4: イベントトリガーテーブル（Layer 2記録）
CLAUDE.md に最も価値を生む設計の一つが、イベント駆動の記録ルールだ。
## イベントトリガー定義
| イベント | 検知条件 | 書き込み先 | アクション |
|---------|---------|-----------|-----------|
| ツールエラー | Bash exit!=0 / MCP error | `memory/skill-traces.md` | エラー内容+解決策を追記 |
| ユーザー修正 | 「違う」「やめて」等で方向転換 | `memory/feedback_*.md` | ルール+Why+How to apply で記録 |
| 設計判断 | CLAUDE.md / agents/ への書き込み | `02_Knowledge/decisions/` | ADR形式で記録 |
| 外部API使用 | 課金API呼び出し | その場でメモ | session-end フラグに反映 |
セッション終了を待たずに即座に記録するルールにすることで、コンテキスト圧縮（compact）後もナレッジが残る。「判断に迷ったら書く」という哲学を Claude に植え付けるのが重要だ。
パターン5: コード変更トリガーテーブル
変更と参照すべきドキュメントを対応表として書いておくと、AI が変更後の整合性チェックを自律的に行う。
## コード変更トリガーテーブル
| 変更対象 | 参照すべき仕様 | 対応 |
|---------|--------------|------|
| `CLAUDE.md` | `memory/MEMORY.md`, `workflow-orchestration.md` | 3箇所の整合性を確認 |
| `.claude/agents/` のAgent定義 | `MEMORY.md`, `skill-index.md` | Agent数・名前の同期 |
| `.claude/skills/` のスキル追加・削除 | `skill-index.md`, `MEMORY.md` | INDEX更新必須 |
| API・MCP設定変更 | `MEMORY.md` の該当セクション | 接続情報の整合 |
| `.env*` / シークレット変更 | `.gitignore`, gitleaks設定 | フォールバック値禁止確認 |
これにより Claude が「CLAUDE.md を変更したので MEMORY.md も自動で更新する」という行動を学習する。「スキルを追加したらインデックスの更新を忘れた」という事故がほぼゼロになる。
パターン6: クエリキーワード辞書
繰り返し使う操作をショートカットとして定義する。
## クエリキーワード
| キーワード | 動作 |
|-----------|------|
| `pj-review` | 指定PJの全体レビュー |
| `risk-scan` | Vault内リスク情報を抽出・分類 |
| `daily-start` | デイリーノート雛形生成 |
| `知識整理` | 00_Inbox → 02_Knowledge 仕分け提案 |
| `朝刊` | `/morning-briefing` スキル実行 |
「朝刊」と入力するだけでニュースブリーフィングが走る、という UX が実現できる。Claude との会話を自然言語インターフェース化するパターンだ。ドキュメントとしても機能するため、チームで使う場合も有効だ。
パターン7: 哲学セクションで行動指針を与える
細かいルールを羅列するより、AI の行動原理（哲学） を先に定義するほうが柔軟に機能する。
## 哲学
- AIの知識を信頼し、ゴールと方向性だけ渡す。手順書は最小限に
- コンテキストに応じた最適解をAIが自律判断することを歓迎する
- ルールを追加したくなったら「人格で代替できないか」を先に考える
「ルールを追加したくなったら人格で代替できないか考える」は特に重要だ。ルールが増えると CLAUDE.md が肥大化し、遵守率がさらに下がる。哲学レベルで方向性を示し、細かいルールは最小限に留めるのが長期運用のコツだ。
パターン8: シークレット管理ルールの明文化
セキュリティミスは CLAUDE.md に明記することで防げる。Claude はコード生成時にこのルールを参照するため、うっかりキーをハードコードするリスクが激減する。
## シークレット管理（必須）
- コード内に `os.environ.get("KEY", "実値")` のフォールバック値でAPIキーを書くことは**禁止**
- フォールバックは空文字 `""` or 例外を raise
- 新規リポ作成時は `.gitignore` に `.env*`（`.env.example` 除く）+ `.mcp.json` が含まれていることを確認
- Public リポには `gitleaks` pre-commit hook を必ず導入
# NG: フォールバックに実値を書く
api_key = os.environ.get("OPENAI_API_KEY", "sk-xxxxx")
# OK: フォールバックは空文字 or 例外
api_key = os.environ.get("OPENAI_API_KEY", "")
if not api_key:
raise ValueError("OPENAI_API_KEY is not set")
パターン9: 段階的参照（CLAUDE.md を肥大化させない）
CLAUDE.md に全情報を詰め込むと肥大化してトークンを浪費する。詳細は別ファイルに切り出し、必要なときだけ参照させるのが鉄則だ。
## 詳細ドキュメント（必要時に参照）
- **分析フレームワーク** → `.claude/docs/analysis-frameworks.md`
- **ワークフロー設計** → `.claude/docs/workflow-orchestration.md`
- **Vault構造詳細** → `.claude/docs/vault-structure.md`
- **スキル管理** → `.claude/docs/skill-management.md`
メイン CLAUDE.md には「地図」を置き、「詳細」は別ファイルに委譲する。Claude は必要に応じて参照先を読みに行くため、無駄な読み込みが発生しない。これはレイヤー構造と呼べる設計で、CLAUDE.md の肥大化を長期にわたって防ぐ。
まとめ
CLAUDE.md の設計で効果的だったパターンをまとめる。
| パターン | 効果 |
|---|---|
| 優先度階層の明示 | グローバル・PJ・ローカルの役割を分離する |
| Mapパターン | フォルダ構造と「検索除外ディレクトリ」を宣言する |
| 検索フローチャート | Grep/RAG/Glob の使い分け＋フォールバックチェーンでループを防ぐ |
| イベントトリガーテーブル | セッション中の記録タイミングを機械的に定義する |
| コード変更トリガー | 変更時に連動すべきドキュメントをテーブルで対応付ける |
| クエリキーワード辞書 | 頻出操作をショートカット化してUXを高める |
| 哲学セクション | ルールではなく方向性を与え、細かい指示への依存を減らす |
| シークレット管理 | コード生成時のセキュリティミスを未然に防ぐ |
| 段階的参照 | CLAUDE.md は「地図」として機能させ、詳細は別ファイルに委譲する |
CLAUDE.md は「書いたら終わり」ではなく、使いながら育てるドキュメントだ。遵守率70%という制約を理解した上で、Hooks と組み合わせて「100%決定論的に動かすべきこと」と「LLMに任せるべきこと」を明確に分離することが、長期運用の鍵になる。まずは本記事のパターンを1〜2個試してみてほしい。