Claude Code CLAUDE.md 完全ガイド：AI に指示を確実に守らせる設定方法（2026年版）

Claude Code の開発者 Boris Cherny は、800万回閲覧されたツイートの中で、自身の CLAUDE.md 設定は「surprisingly vanilla（驚くほどシンプル）」だと語りました。

この発言はずっと頭に残っていました。私たちは Shareuhack で 8 つの autonomous agent で構成されたコンテンツシステムを運用しており、CLAUDE.md は300行超、専用のスキルディレクトリと agent ごとの operational memory も備えています。この複雑さは一般的な開発者にとって価値があるのか？そして、CLAUDE.md にルールを書き続けても Claude が従わないという人たちは、一体何を間違えているのか？

この記事の答えは多くの方を驚かせるでしょう：指示が無視されるのはバグではなく、理解すべき設計です。メカニズムを把握すれば、大半の人が最初から間違った方向に進んでいたことに気づくはずです。

鮮度に関する注記：本記事は2026年3月時点の Claude Code 公式ドキュメントとコミュニティの実践に基づいています。Claude Code は頻繁にアップデートされるため、具体的な API、hooks の構文、設定構造はバージョンによって変わる可能性があります。Anthropic 公式ドキュメントと併せてご利用ください。

TL;DR

• CLAUDE.md は「指令」ではなく「ガイダンス」。ユーザーメッセージ層で配信され、Claude が関連性を能動的に判断するため、100% 強制されるわけではない
• 良い CLAUDE.md は引き算で作る。ある論文（arxiv 2602.11988）がコーディングエージェント向け context files を研究した結果：LLM が自動生成した context files は 5/8 のシナリオで baseline を下回り、開発者が手書きしたバージョンでも効果は限定的で、推論コストは +19% 増加。核心的な結論：下手に書くくらいなら書かない方がマシ
• settings.json はシステムを保護、CLAUDE.md は Claude を教育、hooks は強制実行。三者は役割が異なる

---

「指示が無視される」のはバグではない：知っておくべき配信メカニズム

まず、最も多くの人が誤解していること。

CLAUDE.md の内容は「システムプロンプトの後のユーザーメッセージ」として Claude に配信されます。システムレベルの強制設定ではありません。つまり、Claude は CLAUDE.md の内容と現在のタスクの関連性を自ら判断し、関連がないと判断すれば無視する可能性があるということです。GitHub issue #18660 のコミュニティ議論ではこう明示されています：「Claude はルールの存在を認識しているが、タスク完了がプロセス遵守より優先される。」

これは「ルールをもっと書く」ことで解決できる問題ではありません。

さらに重要なのが指示の均一劣化メカニズムです。HumanLayer の分析と複数のコミュニティ開発者の観察によると、LLM が確実に遵守できる指示の上限は約150〜200件（コミュニティ推定値で、公式データではありません）。Claude Code 自体のシステムプロンプトが約50枠を消費するため、CLAUDE.md に使える実質的な予算は100〜150件です。この閾値を超えると、劣化は均一に分布し、低価値なルールを1つ追加するたびに、すべての高価値ルールの遵守確率が等しく薄められます。

重要な注意：「200行上限」はコミュニティのコンセンサスであり（HumanLayer と複数の Reddit 高評価スレッドで裏付け）、Anthropic 公式のハードリミットではありません。「201行を超えると崩壊する」という硬い境界はありませんが、劣化の傾向は実在し、公式も200行以内を推奨しています。

トークンコストの補足（Claude API で支払っている開発者向け）：CLAUDE.md は100行あたり約500〜800トークンを消費し、セッション開始時に毎回全文読み込みされます（増分課金ではない）。100行の CLAUDE.md は Claude Sonnet 4.6 で1セッションあたり約 $0.0003〜$0.0006 の追加コスト。大した額ではありませんが、自動化エージェントを1日数十回実行すれば累積します。

判断ポイント：指示が無視されたとき、まず自問してください。これは配信レイヤーの問題か、それともルール品質の問題か？

簡単な診断方法：そのルールをセッションの最初のメッセージに直接貼り付けてみてください（CLAUDE.md 経由ではなく手入力で）。それで Claude が従うなら配信レイヤーの問題なので、hooks や --append-system-prompt へのアップグレードを検討してください。それでも従わない場合は、ルール自体の品質の問題なので、より具体的に書き直す必要があります。

---

三層アーキテクチャは「継承」ではなく「累積」：global / project / local の正しい使い方

project CLAUDE.md が global CLAUDE.md を「上書き」すると思っている人が多いです。CSS の specificity のようなイメージですが、これは間違いです。

三層すべてが読み込まれ、内容は累積されます：

層	パス	何を置くか	Git commit？
Global（個人）	~/.claude/CLAUDE.md	個人の好み、プロジェクト横断のツール習慣	いいえ
Project（チーム）	./CLAUDE.md または ./.claude/CLAUDE.md	アーキテクチャ決定、コード規約、ビルド/テストコマンド	はい
Local（個人上書き）	CLAUDE.local.md	このプロジェクトでの個人設定（新版では @imports での参照を推奨）	いいえ（.gitignore に追加）
Managed Policy	/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）	企業コンプライアンスの強制規範	IT 管理

注意すべき落とし穴：

サブディレクトリの CLAUDE.md は遅延読み込みされます。起動時に Claude Code が完全に読み込むのは、作業ディレクトリとその上位祖先ディレクトリの CLAUDE.md だけです。サブディレクトリ内の CLAUDE.md は、Claude のツールが実際にそのディレクトリにアクセスしたときにオンデマンドで読み込まれます。重要なルールをサブディレクトリの CLAUDE.md に置くと、最初は本当に見えない可能性があります。

HTML コメントはトークンを消費しません：CLAUDE.md に人間向けのメンテナンスメモを残したい場合、<!-- メンテナンスメモ：このルールは X のインシデントで追加された --> のブロックレベルコメントを使いましょう。Claude Code は読み込み前にこれらを自動的に除去するため、指示予算を消費しません。

---

CLAUDE.md の必須構造：最小限テンプレートからフルテンプレートまで

Claude Code の /init コマンドはコードベースを分析し、技術スタック、ビルドコマンド、既存のコンベンションを含む CLAUDE.md を自動生成します。良い出発点ですが、生成される内容は「Claude が元々知っている」当たり前の常識だらけになりがちです。

CLAUDE.md に本当に必要なのはコードから読み取れない暗黙知です。

必須セクション構造（スキャン効率順。ヘッダー＋箇条書きは散文テキストよりはるかに高速に処理される）：

1. WHAT：このプロジェクトが何か、技術スタック（言語、フレームワーク、主要ツール）を一文で
2. HOW：ビルド、テスト、デプロイの具体的なコマンド（npm run dev、npm test など）。Claude に推測させないこと
3. Code Style：最も重要なコードの好みを数点。具体的かつ実行可能でなければならない（「関数は30行以内、超えたら分割」であって「きれいなコードを書く」ではない）
4. Gotchas：Claude がコードから読み取れない地雷と非直感的な設計判断（「src/generated/ ディレクトリは Prisma が自動生成するので手動で修正しない」）

インディーメーカー向け最小限テンプレート（/init 後の最初のステップ）：

1. 技術スタック＋コアコマンド：フレームワークバージョン、起動/テスト/デプロイコマンド
2. 最も重要なコードの好み1つ：一番こだわりたいものを選び、具体的に書き、反例も付ける
3. 実際の Gotcha 1つ：先週か先月踏んだ地雷。Claude に同じ轍を踏ませないため

サイドプロジェクトはこの3点から始めましょう。CLAUDE.md で完璧な未来を計画しようとしないでください。

コピペ可能な最小限テンプレート：

# [プロジェクト名]

## 技術スタック
Next.js 15 + TypeScript + PostgreSQL + Prisma

## コマンド
- 開発：`npm run dev`
- テスト：`npm test`
- ビルド：`npm run build`

## コード規約
- コンポーネントは function declaration を使い、arrow function export は使わない
- すべての API route で input validation（zod 使用）を行うこと

## Gotchas
- `src/generated/` ディレクトリは Prisma が自動生成するため、手動で編集しない
- 環境変数は `.env.local` に格納し、git に commit しない

上記を自分のプロジェクト情報に置き換えれば、有効な出発点になります。

上級者向けモジュール化（単一 CLAUDE.md が300行を超えた場合のみ検討）：メインファイルをスリムに保ち、@imports や .claude/rules/ フォルダで階層化します。.claude/rules/ 下のファイルは、Claude が対応するディレクトリにアクセスした時にのみオンデマンドで読み込まれます（例：frontend.md は Claude が src/components/ を読む時にトリガー）。サイドプロジェクトにはこの階層化は不要で、チーム開発やマルチエージェントシナリオでのみ維持する価値のある複雑さです。

---

settings.json vs CLAUDE.md：2つのシステム、2つの強制力

この2つはよく混同されますが、責務はまったく異なります：

settings.json = ファイアウォール（技術的強制、LLM を経由しない）

• Claude Code クライアントが直接実行し、Claude の判断は介入できない
• 用途：セキュリティ制御（permissions.deny ブラックリスト）、sandbox 設定、環境変数注入

CLAUDE.md = 社員ハンドブック（行動ガイダンス、LLM の判断を経由）

• テキストコンテキストとして配信され、Claude の振る舞いを形成
• 用途：アーキテクチャ上の意思決定の文脈、コードスタイル規約、ワークフロー説明、非直感的な Gotchas

判断フロー：

• 絶対に阻止する必要がある操作（例：rm -rf 禁止、本番 DB の直接変更禁止）→ settings.json permissions.deny
• API キーや環境変数の注入 → settings.json env
• Claude に理解させて従わせたいワークスタイル → CLAUDE.md

一言で：settings.json はシステムを保護し、CLAUDE.md は Claude を教育する。

---

ルール vs Hooks：責務分担であり、二者択一ではない

Reddit ユーザー u/DevMoses（536ポイント）の観察は的確でした：「CLAUDE.md にルールを追加するのをやめて、インフラを構築し始めた」。彼のケース：ルールが45行から190行に増えたが、遵守率はかえって低下しました。

理由は、「機械的ルール」を「行動ガイダンス」システムに入れていたためです。

hooks の位置づけ：物理的強制（シェル実行、LLM の判断を経由しない）。客観的に判定可能なルールに適しています：フォーマットチェック、テストカバレッジ、特定コマンドの傍受。hooks には2種類あります：command（シェルスクリプトを直接実行）と prompt（LLM 評価——注意：この種類はまだ LLM に依存するため100% 信頼できるわけではない）。PreToolUse イベントでは exit code 2 で操作をブロックできますが、PostToolUse の exit code 2 は既に実行されたアクションを遡って阻止できず、stderr を Claude にフィードバックするだけです。

3ステップの振り分け判断：

1. Linter/CI でできる？ → Linter に任せて、指示予算を消費しない
2. 客観的に判定可能で、コンテキスト不要？ → hooks command（シェル強制）
3. LLM がアーキテクチャの意図やビジネスロジックを理解する必要がある？ → CLAUDE.md

最小限の hooks 設定例（settings.json の hooks フィールド内）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}

この例では、Claude が Bash コマンドを実行するたびに事前に lint チェックを走らせます。lint 失敗時はゼロ以外の exit code が返され、Claude は問題を修正してからリトライします。

hooks を使わずにルールの遵守率を高めるテクニック（シェルスクリプトに慣れていない方向けの代替手段）：

• 具体的に、反例付きで：「きれいな関数を書く」ではなく「関数が30行を超えたら分割すること（❌ 既存の関数にロジックを詰め込み続けない、✅ 別の関数に抽出して呼び出し元を更新する）」
• 結果を明記：重要なルールの後に「このルールに違反した場合、自分で判断せず私に確認してください」を追加
• 本当に重要なものだけに絞る：少なくて具体的なルールの方が、多くて曖昧なルールより効果的

hooks の落とし穴：command hook にはシェル環境依存性（PATH、環境変数）があり、cron スケジュールやリモート実行のシナリオでは環境の違いにより失敗する可能性があります。

---

マルチエージェント Fleet 設計：Shareuhack 8-agent システムの実例

私たち自身がこのようなシステムを運用しているため、第一手の設計知見を共有できます。

Shareuhack の 8 つの autonomous agent（CEO/Researcher/Scout/Writer/Reviewer/Developer/Auditor/Data Analyst）は、project CLAUDE.md を「憲法」として共有しています。この憲法は、すべてのエージェントが守るべきハードルール（捏造禁止、内部リンク形式、frontmatter 規約など）と、システム全体の情報アーキテクチャを定義しています。

実際のディレクトリ構成：

project CLAUDE.md          ← 全エージェント共通ルール（憲法）
.claude/skills/            ← 各エージェントのスキル定義（個別の SKILL.md）
agents/memory/             ← エージェントごとの operational memory（個別学習、相互汚染なし）
agents/system-state.yaml   ← システム状態（CEO が管理）

Anthropic Docs の技術的裏付け：Project CLAUDE.md は git 経由で共有され、すべての subagent がベースコンテキストを取得します。各 subagent は独自の Auto Memory を維持でき、メインエージェントの記憶を汚染しません。

zero-HITL シナリオの特別な考慮事項：人間の監視がない cron スケジュールシナリオでは、指示が無視されるリスクがより高くなります。キーテクニック：

• --append-system-prompt パラメータ：指示をシステムプロンプトレベルに昇格させ、強制力を大幅に高めます。注意：このパラメータは毎回の呼び出し時に渡す必要があり、CI/CD や cron スクリプトに適しています。CLI フラグはバージョン更新で変更される可能性があるため、使用前に最新の公式ドキュメントで確認してください
• hooks は CLAUDE.md のルールより信頼性が高い（hooks は機械的に実行され、LLM の判断に依存しない）

規模別の設定推奨：

規模	推奨構成
ソロ開発者	project CLAUDE.md（300行以内）+ 1〜2 の subagent skill（最も繰り返すタスクを選択）
小規模チーム	project CLAUDE.md（git 共有）+ .claude/rules/ でモジュール分類（frontend/backend/testing）
マルチエージェント fleet	憲法の階層化 + スキルディレクトリ + エージェントごとの operational memory

8-agent fleet はすべての開発者に必要な構成ではありません。重要な原則は規模に応じてスケールすることです。ソロ開発者なら、300行以内の project CLAUDE.md と subagent skill 1つから始められます。subagent skill のコンセプトはシンプルです：.claude/skills/ に .md ファイルを作成し、よく繰り返すタスク（例：「コードレビュー」や「ブログ記事のドラフト」）を定義すれば、Claude はそのタスク実行時に自動的にそのガイダンスを読み込みます。1つの skill だけで同じアーキテクチャ思想の恩恵を受けられ、fleet 全体を複製する必要はありません。

マルチツール環境の補足：Cursor、Zed など他の AI ツールも併用している場合、それらは AGENTS.md（クロスツール標準）を使用します。Claude Code はデフォルトで AGENTS.md を読みませんが、CLAUDE.md 内で @AGENTS.md として参照し、Claude 固有の設定を追加できます。

---

オーバーエンジニアリングの罠を避ける：規模に見合ったアーキテクチャこそ良い設計

冒頭の問いに戻ります。Claude Code の作者自身が「surprisingly vanilla」な設定を使い、核心は3要素：**past errors（踏んだ地雷）+ conventions（既存慣例）+ rules（必要なルール）**です。

Hacker News で有名な事例があります。10,000行のセマンティックメモリシステムから 1,500行の CLAUDE.md + bash scripts に戻した結果、10倍の速度向上を達成。代償：指示の均一劣化、トークン消費の爆増、ルール間の矛盾。

簡素化を検討すべき3つのシグナル：

1. CLAUDE.md が300行を超えている（単一ファイル）
2. Claude が、書いたはずのルールを頻繁に無視し始める
3. あるルールがまだ機能しているかどうか、自分でも思い出せない

簡素化プロセス：

1. 各ルールを審査：「この行がなければ Claude はどんな具体的なミスをする？」答えられないなら削除
2. 静的チェック（フォーマット、Lint）は Linter や hooks に戻し、指示予算を解放
3. 長すぎる CLAUDE.md は @imports や .claude/rules/ に分割し、オンデマンド読み込みに

サイドプロジェクトの実用的な上限：300行以内の単一 CLAUDE.md で完全に十分です。.claude/rules/ の階層化は、複数人でのコラボレーションやマルチエージェントシナリオでのみ維持する価値のある複雑さです。

---

結論

CLAUDE.md は「Claude を教育する最もレバレッジの高いポイント」——HumanLayer の言葉で、私も完全に同意します。しかし最もレバレッジの高いポイントは、低品質なルールに労力を浪費してしまいやすい場所でもあります。

残す価値のあるルールとは、「Claude がコードとコンテキストから読み取れない暗黙知」でなければなりません。それ以外は、Linter に任せるか、hooks に任せるか、削除してしまいましょう。

Claude Code を使っているなら、おすすめの出発点：

1. /init でベースの CLAUDE.md を生成する
2. 「この行がなければ Claude はミスする？」で半分をフィルタリング
3. 実際に踏んだ Gotchas を追加する
4. どのルールを hooks に昇格させるべきかを特定する

この4ステップから始めて、あとは CLAUDE.md を有機的に成長させましょう。

あなたの CLAUDE.md はどう設計していますか？どんな失敗をしましたか？コメントで共有してください。