/init で生成された CLAUDE.md はそのまま使える？どう改善すればいい？

/init はコードベースを分析し、技術スタック、ビルドコマンド、既存のコンベンションを含む基礎的な CLAUDE.md を自動生成します。良い出発点ですが、生成内容は「Claude が元々知っている」当たり前の常識だらけになりがちです。推奨する改善戦略：Claude が自分で判断できる部分は大胆に削除し、コードから読み取れない暗黙知と Gotchas だけを残すこと。その後「有機的成長」アプローチを採用し、Claude が誤った判断をしたら即座に「これを CLAUDE.md に追加して」と伝え、架空のルールではなく実際の失敗を反映させましょう。

CLAUDE.md の # キーショートカット更新機能はまだある？

Claude Code v2.0.70 で正式に廃止されました。現在の標準的な方法は、自然言語で直接 Claude に「これを CLAUDE.md に追加して」と伝えるか、/memory コマンドでインラインに編集することです。推奨習慣は「有機的成長」で、セッション中に問題を発見したらすぐに更新し、定期的なバッチ整理は避けましょう。

Claude Code が CLAUDE.md を無視する？原因は配信メカニズムにある（2026年版修正ガイド）

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

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

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

鮮度に関する注記：本記事は2026年5月時点の Claude Code 公式ドキュメントとコミュニティの実践に基づいています（最新バージョン v2.1.126、2026年5月1日リリース）。Claude Code は頻繁にアップデートされ、2026年4〜5月に hooks の大幅改善、Agent Teams、新しいスラッシュコマンドが追加されています。Anthropic 公式ドキュメントと併せてご利用ください。

TL;DR

ルールが無視される？ CLAUDE.md はユーザーメッセージとして配信され、システム設定ではありません。Claude が関連性を判断し、現在のタスクと無関係と判断したルールはスキップされます。これはバグではなく設計です
100%強制したい？ 機械的ルールは hooks（シェルレベル、LLM を経由しない）に移動。CLAUDE.md には暗黙知とアーキテクチャコンテキストだけを残す。セキュリティブロックは settings.json で。2026年4月に追加された条件式 if フィールドと mcp_tool タイプで hooks がより精密かつ実用的に
何を書けばいい？ /init で始めて、Claude がコードから読み取れる内容は削除。50行の実用的な Gotchas は、300行の当たり前の常識より効果的（研究が裏付け：下手な context files は無い方がマシ）

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

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

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日数十回実行すれば累積します。注意点として、2026年4月にリリースされた Claude Opus 4.7 は新しいトークナイザーを使用しており、同じ入力テキストで最大35%多くのトークンが生成される可能性があります。API 単価は据え置き（$5/$25 per MTok）ですが、実質コストが上昇する場合があります。

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

簡単な診断方法：そのルールをセッションの最初のメッセージに直接貼り付けてみてください（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 に人間向けのメンテナンスメモを残したい場合、 のブロックレベルコメントを使いましょう。Claude Code は読み込み前にこれらを自動的に除去するため、指示予算を消費しません。

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

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

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

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

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

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

技術スタック＋コアコマンド：フレームワークバージョン、起動/テスト/デプロイコマンド
最も重要なコードの好み1つ：一番こだわりたいものを選び、具体的に書き、反例も付ける
実際の 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 には3種類あります：command（シェルスクリプトを直接実行）、prompt（LLM 評価。注意：まだ LLM に依存するため100% 信頼できるわけではない）、そして2026年4月に追加された mcp_tool（接続済みの MCP サーバーのツールを直接呼び出す。例：タスク完了後に自動で Slack 通知を送信）。PreToolUse イベントでは exit code 2 で操作をブロックできますが、PostToolUse の exit code 2 は既に実行されたアクションを遡って阻止できず、stderr を Claude にフィードバックするだけです。

2026年4〜5月の hooks 主要アップデート：

条件式 if フィールド（v2.1.85+）：permission rule 構文でフック発火条件を精密にフィルタリング。matcher でツール名を選択し、if で特定の呼び出しに限定。例：Bash(git *) は git コマンドのみ、Write(src/**/test_*.py) はテストファイルの書き込みのみに対応
PostToolUse 出力置換（v2.1.121+）：hookSpecificOutput.updatedToolOutput により、すべてのツールの出力結果を置換可能
PreCompact フック（v2.1.105+）：コンテキスト圧縮前に発火し、exit code 2 で圧縮をブロック
PermissionDenied フック（v2.1.89+）：auto mode のパーミッション拒否後に発火。{retry: true} を返すとリトライ可能
duration_ms フィールド（v2.1.110+）：PostToolUse と PostToolUseFailure にツール実行時間が含まれ、パフォーマンス監視に有用

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

Linter/CI でできる？ → Linter に任せて、指示予算を消費しない
客観的に判定可能で、コンテキスト不要？ → hooks command（シェル強制）
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 は問題を修正してからリトライします。

上級例：条件式フック + MCP ツール通知（v2.1.85+）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "Bash(rm *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'ファイル削除を禁止' >&2 && exit 2"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "slack",
            "tool": "send_message",
            "input": { "channel": "#dev", "text": "Claude がタスクを完了しました" }
          }
        ]
      }
    ]
  }
}

最初のフックは if 条件で削除操作のみを傍受し（すべての Bash コマンドではなく）、2番目は mcp_tool でタスク終了時に自動的に Slack 通知を送信します。

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

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

hooks の落とし穴：command hook にはシェル環境依存性（PATH、環境変数）があり、cron スケジュールやリモート実行のシナリオでは環境の違いにより失敗する可能性があります。なお、認識されないフックイベント名が設定ファイル全体を無効化する問題は修正されています（v2.1.89+）が、公式ドキュメントに記載されたイベント名のみの使用を推奨します。

マルチエージェント 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 を維持でき、メインエージェントの記憶を汚染しません。v2.1.117 以降、forked subagent は CLAUDE_CODE_FORK_SUBAGENT=1 で外部ビルドでも有効化可能で、名前付き subagent は @ メンションのオートコンプリートにも対応しています。

Agent Teams：subagent を超えたマルチセッション連携（実験的機能、2026年2月リリース）：

複数のエージェントが並行作業しながら互いに通信するシナリオでは、Agent Teams が subagent より高度な選択肢です。主な違い：subagent は単一セッション内で動作し、メインエージェントにのみ結果を報告します。Agent Teams のメンバーはそれぞれ独立した context window（各1Mトークン）を持ち、mailbox システムと shared task list を通じて直接通信し、チームリードを経由する必要がありません。

有効化方法：settings.json または環境変数で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定（v2.1.32+ 必須）。実際にテストした感触では、Agent Teams はクロスドメインの調整が必要な大規模タスク（例：フロントエンドとバックエンドのエージェントが API コントラクトを同期する場面）に適していますが、ソロ開発者にとっては subagent の方が実用的な出発点です。

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

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

規模別の設定推奨：

規模	推奨構成
ソロ開発者	project CLAUDE.md（300行以内）+ 1〜2 の subagent skill + `/recap` でセッション記憶管理
小規模チーム	project CLAUDE.md（git 共有）+ `.claude/rules/` でモジュール分類 + `/ultrareview` でコードレビュー
マルチエージェント fleet	憲法の階層化 + スキルディレクトリ + エージェントごとの memory + Agent Teams（実験的）

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

2026年4月に追加された便利なスラッシュコマンド：

/recap：セッションを離れて戻ったとき、会話全体を読み直さなくても何をしていたか素早く把握可能
/ultrareview [target]：クラウド経由で包括的なマルチエージェント並列コードレビューを実行
/usage：旧 /cost と /stats を統合し、トークン使用量とコストを一覧表示
/effort：インタラクティブなスライダーで推論深度を調整。Claude Opus 4.7 は新しい xhigh レベルに対応

マルチツール環境の補足：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つのシグナル：

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

簡素化プロセス：

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

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

結論

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

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

Claude Code を使っているなら（2026年5月時点、最新版 v2.1.126）、おすすめの出発点：

/init でベースの CLAUDE.md を生成する
「この行がなければ Claude はミスする？」で半分をフィルタリング
実際に踏んだ Gotchas を追加する
どのルールを hooks に昇格させるべきかを特定し、条件式 if フィールドで発火タイミングを精密に制御
マルチセッションの記憶管理が必要なとき、/recap でコンテキストを素早く復元

この5ステップから始めて、あとは CLAUDE.md を有機的に成長させましょう。Agent Teams、mcp_tool hooks、/ultrareview などの新機能が続々と成熟する中、CLAUDE.md の役割はますます「人間だけが知る暗黙知」に集中し、機械的なルールは hooks と subagent に委ねるのが、2026年下半期に注目すべきトレンドです。

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