CLAUDE.md最適化の本質は、長いプロンプトを書くことではない

TL;DR

• CLAUDE.md は「AIへの長いお願い文」ではなく、Repo Memoryの入口として設計する
• 必要な文脈は Why / Map / Rules / Workflows の 4 種類に分類できる
• 毎セッション必要なものだけを CLAUDE.md に置き、それ以外は skills・hooks・docs に分散させる
• 強制したいルールは CLAUDE.md ではなく hooks（決定論的制御） に寄せる
• CLAUDE.md を長くするほど、遵守率は下がる

Claude Code を使い始めると、多くの人が最初にやりがちなのが、CLAUDE.md を「AIへの長いお願い文」にしてしまうことです。

プロジェクトの背景、設計思想、禁止事項、レビュー観点、運用手順、コマンド一覧、注意点、チームの作法。 気づくと、あらゆるものを 1 ファイルに押し込みたくなる。

でも、ここに罠があります。

Anthropic の公式ドキュメントでも、CLAUDE.md は毎セッション読み込まれる特別なファイルであり、短く、人間にも読みやすく保つべきだとされています。さらに、CLAUDE.md に何でも詰め込むのではなく、たまにしか必要にならない知識やワークフローは skills に逃がすのが推奨されています。ファイルが膨らむほど、肝心の指示が埋もれ、Claude が実際の指示を無視しやすくなる——そうはっきり書かれています。コンテキストは有限です。

つまり、CLAUDE.md 最適化の本質は、 **「何をたくさん書くか」ではなく、「何をどこに分離するか」**にあります。

前提：Claude Code は"記憶するチャット"ではなく"文脈で動く作業者"

チャットボットとの根本的な違い

Claude Code は、単なる質疑応答のチャットボットとは違います。Anthropic の説明でも、Claude Code はファイルを読み、コマンドを実行し、変更を加え、自律的に作業を進める agentic coding environment として位置づけられています。だからこそ、必要なのは毎回の場当たり的なお願いではなく、リポジトリに定着した文脈です。

Anthropic 公式の「How Claude remembers your project」でも、各セッションは新しいコンテキストウィンドウから始まり、継続的な文脈を渡す手段として CLAUDE.md と auto memory が説明されています。特に CLAUDE.md は、プロジェクト単位・ユーザー単位・組織単位で置ける持続的な指示の置き場です。

設計の基本原則

ここから導ける設計思想はシンプルです。

プロンプトは一時的。構造は永続的。

その場その場で Claude を賢く見せるのではなく、 Claude が迷わず安全に働けるように、リポジトリそのものを作業環境として設計する。

これが本筋です。

Claude に必要なのは 4 種類の文脈だけ

文脈の分類

突き詰めると、Claude に必要な文脈は次の 4 種類に整理できます。

• why: このシステムは何のために存在するのか
• map: 何がどこにあるのか
• rules: 何をしてよくて、何をしてはいけないのか
• workflows: 作業をどう進めるのか

この 4 種類を、1 ファイルに全部押し込むのではなく、役割ごとに置き場所を分ける。 それだけで Claude の振る舞いは安定します。

CLAUDE.md / AGENTS.md / Skill / Subagent / Hook の役割分担表

2026 年中頃の Anthropic 公式を整理すると、各仕組みは 役割が直交しており、置き場所と起動タイミングで使い分けます。

ポイントは「CLAUDE.md が context、Hook が enforcement で、両者は別物」という点です。必ず守らせたい制約は Hook、共有したい知識は CLAUDE.md、再利用したい手順は Skill、独立コンテキストでの並列処理は Subagent、と分けます。

1. CLAUDE.md = Repo Memory

入れるべきものと入れるべきでないもの

CLAUDE.md は中心ファイルです。 ただし、中心だからといって、百科事典にしてよいわけではありません。

Anthropic は CLAUDE.md について、毎セッション読み込まれるので広く適用されることだけを書くべきだと明言しています[公式値]（Claude Code memory 公式）。また、「その行を消したら Claude がミスするか？」を基準に削る、という実務的な判断基準も示しています。

つまり、CLAUDE.md に入れるべきなのは、主に次のようなものです。

• Purpose: このリポジトリは何を解決するために存在するのか
• Repo map: 主要ディレクトリ、責務、依存関係のざっくりした地図
• Rules / commands: 全体に効くルールや基本コマンド

肥大化させない

ここで大事なのは、知識を全部ここに詰め込まないことです。 公式ドキュメントでも、200 行を超えるファイルはコンテキストを多く消費し、遵守率が下がる可能性があると案内されています。大きくなりすぎた場合は、@path で別ファイルを import したり、.claude/rules/ に分割したりするのが推奨です。

要するに、CLAUDE.md は「全部入りメモ帳」ではなく、 Repo Memory の入口であるべきです。

2. .claude/skills/ = 再利用可能な専門ワークフロー

skill 化すべき作業の例

毎回同じ指示を書くのは、効率が悪いうえに品質のブレを生みます。

Anthropic 公式では、skills は SKILL.md を使って Claude の能力を拡張する仕組みで、Claude が関連すると判断したときに自動で読み込むこともできますし、/skill-name のように明示的に呼び出すこともできます[公式値]（Claude Code skills 公式）。CLAUDE.md には広く効くことだけを書き、たまにしか使わない知識やワークフローは skills に分けるのが推奨されています。Skill と Subagent の使い分けは別記事 Skills対Subagents使い分け5軸 で整理しています。

skill 化しやすいものの例です。

• コードレビュー手順
• リファクタ手順
• リリース手順
• デバッグ手順
• PR 作成手順
• 障害調査の定型フロー

分離の 2 つの利点

1. 再現性が上がる。 セッションが変わっても、人が変わっても、同じ作業に同じ手順を適用しやすくなります。

2. 常時ロードする情報量を増やさずに済む。 CLAUDE.md に全部入れると、毎回全員が全資料を抱えて会議しているようなものです。skills なら必要なときだけ呼べます。

3. .claude/hooks/ = ガードレール（決定論的な強制）

context と enforcement の違い

CLAUDE.md は文脈です。 でも、文脈は強制ではありません。

Anthropic の公式にも、CLAUDE.md は enforcement ではなく context だと明記されています[公式値]（Claude Code memory 公式）。Claude は読んで従おうとはしますが、厳密な保証はありません。だから、必ず守らせたいことをプロンプトに委ねるのは危ういわけです。

その代わりに使うのが hooks です。

hooks でできること

hooks は、Claude Code のライフサイクルの特定の地点で自動実行される仕組みで、Anthropic はこれを deterministic control（決定論的な制御）として説明しています[公式値]（Claude Code hooks 公式）。「Claude が気を利かせてくれるといいな」ではなく、必ず実行される仕組みに落とすためのものです。具体的なパターンは Claude Code hooks の実践パターン集 を参照してください。

向いている用途はたとえば次のようなものです。

• 編集後に formatter を走らせる
• 特定領域の変更時に test を実行する
• 危険なコマンドをブロックする
• セッション開始時に文脈を注入する
• Claude が入力待ちになったら通知する

守るべきことを自然言語で書いて終わりにしない。 機械的に強制する。祈りではなく、配線。

これは AI 運用における重要な発想転換です。

4. docs/ = Progressive Context

地図を渡す設計

CLAUDE.md を短く保ち、詳細は import や rules、必要時ロードに分ける考え方を Anthropic は示しています。また、子ディレクトリの CLAUDE.md や path-specific rules は、必要になったときだけ読み込まれるため、常時ノイズを増やしにくい構造です。

この思想をリポジトリ設計に翻訳すると、docs/ はこういう役割になります。

• architecture overview
• ADRs（設計判断の記録）
• runbooks（運用手順）
• onboarding 用の背景説明
• 依存サービスや外部連携の説明

「知ってもらう」ではなく「どこにあるかを知ってもらう」

重要なのは、Claude にすべてを常に読ませることではありません。 Claude に必要なのは、真実がどこにあるかを知っていることです。

全部を頭に詰め込ませるより、「必要ならここを見ればよい」という地図を渡す方が強い。 これが Progressive Context です。

5. 局所的な CLAUDE.md や .claude/rules/ = 危険地帯の局所知識

危険領域にだけ局所ルールを差し込む

複雑な領域、事故りやすい領域、暗黙知の多い領域。 そういう場所には、局所的な文脈を置くのが有効です。

Anthropic の公式では、子ディレクトリにある CLAUDE.md は、そのディレクトリ配下のファイルを Claude が読むときにオンデマンドで読み込まれるとされています。また、.claude/rules/ では path-specific なルールも設定でき、必要な範囲にだけルールを適用できます。

たとえばこうです。

src/
├─ auth/
│  └─ CLAUDE.md       # 認証まわりの局所ルール
└─ persistence/
   └─ CLAUDE.md       # DB/永続化の注意点

あるいは .claude/rules/ で分割するなら：

.claude/
└─ rules/
   ├─ auth.md
   ├─ database.md
   └─ migrations.md

認証や課金やマイグレーションのような「壊すと取り返しのつかない領域」で、Claude にピンポイントの注意事項を与えられます。毎回グローバルな長文を読ませるより、ずっと理にかなっています。

この設計思想のコア：プロンプトエンジニアリングから環境設計へ

この話の本質は、単なるファイル整理術ではありません。

AI 運用を、プロンプトエンジニアリング中心の発想から、環境設計中心の発想へ移すことです。

避けるべきアンチパターン

• CLAUDE.md を肥大化させる
• すべての知識とルールを 1 ファイルに詰め込む
• 毎回同じワークフローを自然言語で繰り返す
• 危険操作の防止までプロンプトに頼る

目指すべき設計

• CLAUDE.md は短く、地図と原則に絞る
• ワークフローは skills に分離する
• 強制したいことは hooks に寄せる
• 詳細知識は docs に置く
• 危険領域はローカル CLAUDE.md や .claude/rules/ で補強する

CLAUDE.md は常時ロードなので短く広く、skills は必要時ロード、hooks は決定論的制御、子ディレクトリや rules は局所文脈の注入——全部、役割が分かれています。

Claude を賢く見せる最短ルートは、長文プロンプトを書くことではなく、Claude が迷わない repo を作ることです。

すぐ使える実践テンプレート

/
├─ CLAUDE.md                  # 全体方針、地図、基本ルール
├─ docs/
│  ├─ architecture.md         # 全体設計
│  ├─ decisions/              # ADR
│  └─ runbooks/               # 運用手順
├─ .claude/
│  ├─ skills/
│  │  ├─ code-review/
│  │  │  └─ SKILL.md
│  │  ├─ refactor/
│  │  │  └─ SKILL.md
│  │  └─ release/
│  │     └─ SKILL.md
│  ├─ hooks/
│  └─ rules/                  # path/file-type specific rules
├─ src/
│  ├─ auth/
│  │  └─ CLAUDE.md            # 認証まわりの局所ルール
│  └─ persistence/
│     └─ CLAUDE.md            # DB/永続化の注意点

文脈の「重さ」で置き場所を決める

この構成の利点は、Claude に必要な文脈を、重さごとに分けられることです。

一文でまとめると

CLAUDE.md 最適化とは、ファイルを書くことではなく、 Claude が迷わず安全に働けるようにリポジトリを構造化することです。

CLAUDE.md を長くするほど賢くなるわけではありません。むしろ逆です。

本当に強い構成は、Claude にその場しのぎの指示を与えることではなく、 プロジェクトに馴染んだシニアエンジニアのように振る舞える環境を用意することにあります。

プロンプトは一時的。構造は永続的。

CLAUDE.md の最適化は「何を書くか」ではなく、**「何をどこに分離するか」**の問題です。

関連記事

• CLAUDE.mdの次に整備すべきコンテキスト設計 — 三層分離を具体的なファイル構成に落とし込む
• AIが迷わないリポジトリ設計 — repo全体をエージェントが読める構造にする方法

参考リンク

• How Claude remembers your project - Claude Code Docs
• Skills の活用について - Claude Code Docs
• Hooks の設定ガイド - Claude Code Docs
• Subagents 公式ドキュメント - Claude Code Docs
• OpenAI Codex AGENTS.md 公式

FAQ

Q1. CLAUDE.md と AGENTS.md は両方必要ですか？

ツールを混在運用するなら両方必要です。CLAUDE.md は Claude Code 専用、AGENTS.md は OpenAI Codex 等の汎用エージェント向けに公式採用されている命名です[公式値]。共通情報は片方に置いて他方からシンボリックリンクや @import でつなげる運用が多いです（経験則）。両方を分担して使う組織展開は AIコーディング組織展開の段階設計 を参照。

Q2. CLAUDE.md が肥大化したらどうすべきですか？

200 行を超えると遵守率が下がる傾向があります[公式値]（公式ドキュメント記載）。対応は次の 3 つです: (1) @path で別ファイル import に分割、(2) たまにしか使わない手順は Skill 化、(3) 必ず守らせる制約は Hook に移動。詳細は本記事の §1〜§3 と §5 を参照。

Q3. Skill と Subagent はどう使い分けますか？

Skill は「同じ処理を再利用したい」、Subagent は「コンテキストを隔離して並列実行したい」が分かれ目です[公式値]。詳細な 5 軸（粒度・並列性・状態管理・ツール権限・呼び出し方）は Skills対Subagents使い分け5軸 を参照。

Q4. Hook を導入する際の最初の 1 個は何がおすすめですか？

「commit 直前のフォーマッタ実行」または「危険コマンドのブロック」 が低リスクで効果が見えやすい入門例です（経験則）。実装パターンは Claude Code hooks の実践パターン集 を参照。<claude-mem-context> 等の auto-injected ブロックを除去するパターンも 1 例として有用です。

Q5. CLAUDE.md 最適化の効果はどう測りますか？

定量指標は (1) CLAUDE.md 行数の推移（200 行以下を維持）、(2) Skill 数の増加（再利用度の代理指標）、(3) PR 内の手戻り回数の減少（経験則）、の 3 つを推奨します。組織全体の生産性指標との接続は DORAとSPACEの選び方 を参照。