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 の振る舞いは安定します。

---

1. CLAUDE.md = Repo Memory

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

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

Anthropic は CLAUDE.md について、毎セッション読み込まれるので広く適用されることだけを書くべきだと明言しています。また、「その行を消したら 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.md には広く効くことだけを書き、たまにしか使わない知識やワークフローは skills に分けるのが推奨されています。

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

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

分離の 2 つの利点

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

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

---

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

context と enforcement の違い

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

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

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

hooks でできること

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

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

• 編集後に 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/skills/ | | 強制 | 守らせたいルール | .claude/hooks/ | | 深い知識 | 設計・運用ドキュメント | docs/ | | 局所知識 | 危険領域のルール | rules/ や子 CLAUDE.md |

---

一文でまとめると

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

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

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

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

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

---

参考リンク

• How Claude remembers your project - Claude Code Docs
• Skills の活用について - Claude Code Docs
• Hooks の設定ガイド - Claude Code Docs