CLAUDE.md は、Claude Code が毎セッションの冒頭で自動的に読み込むプロジェクトメモリです。ここに何を書くかで、Claude が同じ説明を二度させずに済むか、それとも毎回ズレた実装を返してくるかが決まります。本記事では「何を書くと効くのか／書きすぎるとなぜ逆効果になるのか」を、公式ドキュメントの現行仕様（2026年6月時点）に沿って整理します。
- 要点1：CLAUDE.md はシステムプロンプトではなく、起動時に注入される「文脈」。強制力はないので、具体的・簡潔・矛盾なしが効き目を左右する
- 要点2：階層（Managed policy → ユーザー → プロジェクト → ローカル）と読み込み順、ディレクトリツリーを遡る挙動、
@pathimport、.claude/rules/のパススコープを押さえると、肥大化させずに効かせられる - 要点3：機密情報を書かない・1ファイル200行以内・矛盾ルールを定期的に掃除する、の3点が運用の肝
対象読者：Claude Code をチーム開発に導入している、あるいは導入を検討しているエンジニア・テックリード・PM。今日できること：手元の CLAUDE.md を開いて、本記事のアンチパターン表と照合し、肥大化・矛盾・機密混入をその場で削れます。
「CLAUDE.md にプロジェクトの作法を書いておけば Claude が従ってくれる」——これは半分正しく、半分は誤解です。正しくは「書き方次第で従う確率が大きく変わる」。筆者は社内の WordPress マルチサイトリポジトリで、最初は何でも CLAUDE.md に詰め込んだ結果、ファイルが400行を超えて Claude の指示遵守率がむしろ下がるという失敗をしました。原因は単純で、矛盾したルールが混在し、毎セッション大量のトークンを消費していたからです。この記事は、その手戻りを読者に踏ませないための実装ガイドです。
CLAUDE.md とは何か — 「設定ファイル」ではなく「毎回読まれる指示書」
まず性質を正確に押さえます。公式ドキュメントは CLAUDE.md をこう定義しています：「あなたが書く、永続的な指示を与えるための Markdown ファイル。Claude が毎セッションの開始時に読む」。重要なのは次の一文です。
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself.（CLAUDE.md の内容は、システムプロンプトの一部ではなく、システムプロンプトの後に user メッセージとして渡される）
つまり CLAUDE.md は「強制される設定」ではなく「Claude が読んで従おうとする文脈」です。ここを誤解すると、「書いたのに守らない」と悩むことになります。確実にブロックしたい動作（例：main への直 push 禁止、特定コマンドの拒否）は CLAUDE.md ではなく PreToolUse フックや managed settings の permissions.deny で技術的に強制するのが正解です。CLAUDE.md は「振る舞いを誘導する」レイヤー、settings/hooks は「実行を強制する」レイヤー、と役割を分けて考えてください。
Claude Code にはもうひとつ auto memory（Claude 自身が学習を書き溜める仕組み）があります。CLAUDE.md は「あなたが書く指示・ルール」、auto memory は「Claude があなたの修正や好みから書き留める学習」。本記事は前者の CLAUDE.md に絞って扱います。
メモリの階層と読み込み順を正確に理解する
CLAUDE.md は1ファイルだけではありません。スコープ別に複数の場所に置け、広いスコープから狭いスコープへの順で文脈に読み込まれます（後に読まれるものほど「近い」指示として効く）。現行の公式仕様は次のとおりです。
# 読み込み順（広い → 狭い／後ろほど優先的に効く）
1. Managed policy（組織管理・除外不可）
- macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
- Linux / WSL: /etc/claude-code/CLAUDE.md
- Windows: C:\Program Files\ClaudeCode\CLAUDE.md
2. ユーザー指示（全プロジェクト共通）
- ~/.claude/CLAUDE.md
3. プロジェクト指示（チーム共有・コミット対象）
- ./CLAUDE.md または ./.claude/CLAUDE.md
4. ローカル指示（個人用・.gitignore 推奨）
- ./CLAUDE.local.md
誤解されがちな点を3つ補足します。
- Managed policy は除外できない：組織が配布した CLAUDE.md は個人設定で無効化できません。会社のセキュリティポリシーやコンプライアンス要件を全社展開する用途です。
managed-settings.jsonのclaudeMdキーに内容を直書きする方法もあります。 - プロジェクト用は
./CLAUDE.mdでも./.claude/CLAUDE.mdでも良い：どちらも同じスコープです。チームで共有したい作法はここに置き、バージョン管理にコミットします。 CLAUDE.local.mdは廃止されていません（2026年6月時点）。個人のサンドボックスURLやテストデータなど、コミットしたくない設定用に現役で文書化されています。/initで「個人用」を選ぶと.gitignoreへの追加まで自動でやってくれます。ただし git worktree をまたぐと、作成した worktree にしか存在しない点には注意が必要です。
ディレクトリツリーを遡って読まれる挙動
Claude Code はカレントディレクトリから上位ディレクトリへツリーを遡り、各階層の CLAUDE.md と CLAUDE.local.md を探します。foo/bar/ で起動すれば、foo/bar/CLAUDE.md と foo/CLAUDE.md の両方が読まれます。並び順はファイルシステムのルート側からカレント側へ。したがって foo/CLAUDE.md が先、foo/bar/CLAUDE.md が後に文脈へ入り、起動位置に近い指示ほど後ろ（＝効きやすい位置）に来ます。
一方、カレント配下のサブディレクトリにある CLAUDE.md は起動時には読まれず、Claude がそのサブディレクトリのファイルを読むときに初めて読み込まれます（オンデマンド）。モノレポで「子ディレクトリ専用の作法」を書くときに効く挙動です。逆に言うと、/compact 後にサブディレクトリの CLAUDE.md は自動再注入されないので、消えたように見えることがあります（プロジェクトルートの CLAUDE.md は再読込されます）。
何を書くと効くか — 「毎回再説明していること」を書く
公式の指針はシンプルです。「あなたが毎回説明し直していることを書く場所」として CLAUDE.md を扱う。具体的には、以下のタイミングで追記します。
- Claude が同じミスを2回目にした
- このコードベース特有の事情を、コードレビューで Claude が見落としたと指摘された
- 前のセッションで打ち込んだのと同じ修正・補足を、また chat に打ち込んでいる
- 新しいチームメンバーが生産的になるのに必要な前提知識だと気づいた
逆に、書く内容は「毎セッション保持すべき事実」に絞ります。ビルドコマンド、命名規約、プロジェクト構成、「常に X する」ルールなどです。複数ステップの手順や、コードベースの一部にしか関係しない指示は CLAUDE.md ではなくスキルやパススコープルールへ逃がすのが現行の推奨です。良い CLAUDE.md は次のように、検証可能なくらい具体的に書きます。
# プロジェクト構成
- API ハンドラは src/api/handlers/ に置く
- 共通型は src/types/ に集約する
# コマンド
- コミット前に必ず `npm test` を実行する
- リント: `npm run lint`（PR を出す前に通す）
# コーディング規約
- インデントは半角スペース2つ
- 日付は YYYY-MM-DD 形式
# Git
- main へ直接 push しない。必ずブランチを切る
公式は「正しくフォーマットせよ」より「半角スペース2つでインデントせよ」、「テストせよ」より「コミット前に npm test を実行せよ」のように、具体的で検証できる書き方を明示的に推奨しています。曖昧な指示は遵守率が落ちます。
書きすぎは逆効果 — 200行・矛盾・機密の3原則
ここが本記事で最も伝えたいパートです。CLAUDE.md は起動時に文脈ウィンドウへ読み込まれ、会話と並んでトークンを消費します。長いファイルほど文脈を食い、かえって遵守率が下がるのが公式の明言する事実です。アンチパターンを表にまとめます。
| アンチパターン | なぜ効かなくなるか | 対処 |
|---|---|---|
| 1ファイル200行超 | 文脈消費が増え遵守率が下がる | 200行以内を目標に。超えたらパススコープルールへ分割 |
| 矛盾したルールの混在 | Claude がどちらかを恣意的に選ぶ | ネストした CLAUDE.md・.claude/rules/ も含め定期的に矛盾を掃除 |
| 機密情報の直書き | プロジェクト CLAUDE.md はコミットされ共有される | APIキー・トークン・URLは CLAUDE.local.md か環境変数へ。機密はそもそも書かない |
| 多段の手順を全部 CLAUDE.md に | 毎セッション常駐させる必要がない情報まで常駐する | 手順はスキル化（呼ばれた時だけロード） |
| 全部 import で詰め込む | import 先も起動時に展開され文脈を食う | import は「整理」には効くが「軽量化」にはならない。パススコープルールを使う |
特に 機密情報は強調します。プロジェクト用 CLAUDE.md（./CLAUDE.md）はチーム共有・バージョン管理コミット対象です。ここにステージング環境のクレデンシャルや内部URLを書くと、そのままリポジトリに残ります。個人ローカルな前提は CLAUDE.local.md（gitignore 済み）へ、本物のシークレットは .env + 環境変数へ分離してください。
import 記法 — @path で分割し、再利用する
CLAUDE.md は @path/to/import 構文で他ファイルを取り込めます。import 先は起動時に展開され、CLAUDE.md と一緒に文脈へ読み込まれます。現行仕様の要点は次のとおりです。
- 相対パス・絶対パスの両方が使える。相対パスは「working directory ではなく import を含むファイル」を基準に解決される
- import 先はさらに別ファイルを import でき、最大4ホップまで再帰展開される
@~/...のようにホームディレクトリからの import も可能。worktree をまたいで個人設定を共有したいときに有効- 外部 import を初めて踏むと承認ダイアログが出る。拒否すると以後その import は無効化される
# プロジェクトの概要は README とパッケージ定義を参照
See @README for project overview and @package.json for available npm commands.
# 追加の指示
- git ワークフロー @docs/git-instructions.md
# 個人設定（worktree をまたいで共有したい場合）
- @~/.claude/my-project-instructions.md
既に AGENTS.md を他のコーディングエージェント用に運用しているリポジトリでは、Claude Code は AGENTS.md を直接読まない点に注意してください。次のように CLAUDE.md から import すれば、両ツールが同じ指示を二重管理せずに共有できます。
@AGENTS.md
## Claude Code
- src/billing/ 配下の変更はプランモードを使う
ディレクトリ別 CLAUDE.md と .claude/rules/ でスコープを絞る
大きめのプロジェクトでは、指示を .claude/rules/ ディレクトリに分割すると保守しやすくなります。1ファイル1トピックで配置し、.md はサブディレクトリも含めて再帰的に発見されます。
your-project/
├── .claude/
│ ├── CLAUDE.md # メインのプロジェクト指示
│ └── rules/
│ ├── code-style.md # コードスタイル
│ ├── testing.md # テスト規約
│ └── security.md # セキュリティ要件
真価は パススコープルールにあります。YAML フロントマターの paths フィールドで対象ファイルを絞ると、Claude がマッチするファイルを読むときだけそのルールが文脈に入ります。常駐させずに済むので、ノイズと文脈消費を同時に減らせます。
---
paths:
- "src/api/**/*.ts"
---
# API 開発ルール
- 全 API エンドポイントに入力バリデーションを入れる
- エラーレスポンスは標準フォーマットを使う
- OpenAPI ドキュメントコメントを含める
paths を持たないルールは無条件でロードされ、.claude/CLAUDE.md と同じ優先度で起動時に読み込まれます。モノレポで他チームの祖先 CLAUDE.md が拾われて邪魔なときは、claudeMdExcludes 設定（glob 指定）で除外できます（managed policy の CLAUDE.md だけは除外不可）。
チーム運用とレビュー — 「設計→共有→棚卸し」を回す
個人で1ファイル書く話と、チームで運用し続ける話は別物です。実務で詰まる順に手順化します。
/initでひな形を生成する。Claude がコードベースを解析し、ビルドコマンド・テスト手順・規約を拾った CLAUDE.md を作る。既存があれば上書きせず改善提案に切り替わる- 生成物に「Claude が自力では発見できない前提」を手で足す（暗黙の業務ルール、外部依存の癖など）
- チーム共有すべき作法は
./CLAUDE.mdに、個人用はCLAUDE.local.mdに分ける。後者は.gitignoreに入れる - 肥大化したら
.claude/rules/へトピック分割し、サブディレクトリ固有の作法はそのディレクトリの CLAUDE.md へ移す - PR レビューに「CLAUDE.md の差分」も含める。新しいルールが既存と矛盾していないかを人間がチェックする
- 定期的に
/memoryで読み込まれているファイル一覧を確認し、矛盾・陳腐化したルールを削る
セッション中に「ちゃんと CLAUDE.md が読まれているか」を確認するには /memory コマンドが使えます。現在のセッションでロードされている CLAUDE.md・CLAUDE.local.md・rules ファイルが一覧表示され、各ファイルをエディタで開けます。「書いたのに従わない」ときは、まず /memory でそもそもロードされているかを確認するのが鉄則です。一覧に出てこなければ、Claude はそのファイルを見ていません。
HTML コメントの扱いも運用上有用です。CLAUDE.md 内のブロックレベル HTML コメント（<!-- maintainer notes -->）は文脈注入前に除去されるため、人間メンテナー向けのメモを、Claude の文脈トークンを消費せずに残せます。ただしコードブロック内のコメントは保持される点には注意してください。
「従わない」ときの切り分け — CLAUDE.md で解けない問題
最後に、CLAUDE.md の限界と切り分けを整理します。CLAUDE.md はあくまで「振る舞いの誘導」であり、厳密な遵守は保証されません。次の3パターンは CLAUDE.md では解けないので、別の仕組みへ寄せます。
- 「コミット前に必ず実行」のような特定タイミングの強制 → フックで書く。シェルコマンドとして固定のライフサイクルイベントで実行され、Claude の判断に関係なく走る
- 特定ツール・コマンド・パスのブロック → managed settings の
permissions.deny。クライアント側で強制される - システムプロンプトレベルで効かせたい指示 →
--append-system-prompt。ただし毎回渡す必要があるためスクリプト/自動化向き
CLAUDE.md が肥大化してきたと感じたら、それは「強制したい技術要件」と「誘導したい振る舞い」が混ざっているサインです。前者を settings/hooks に逃がせば、CLAUDE.md は軽く・効く状態を保てます。
まとめ — 効く CLAUDE.md の最終チェックリスト
本記事の要点を、そのまま手元の CLAUDE.md に当てて使えるチェックリストにします。
- 1ファイル200行以内に収まっているか
- 具体的・検証可能な書き方になっているか（「テストせよ」ではなく
npm testを実行） - 矛盾するルールが混在していないか（ネスト・rules も含めて確認）
- 機密情報がプロジェクト CLAUDE.md に直書きされていないか（→ CLAUDE.local.md / 環境変数へ）
- 多段手順はスキルへ、パス固有ルールは
.claude/rules/のパススコープへ逃がしているか - 「必ず実行」系は CLAUDE.md ではなくフックで強制しているか
/memoryでロード状況を確認し、定期棚卸しを回しているか
Claude Code を「賢いけれど毎回前提を忘れる新人」と捉えると、CLAUDE.md は引き継ぎ書、auto memory は本人のメモ帳、フックは就業規則、と整理できます。引き継ぎ書を分厚くしすぎず、要点だけを具体的に書く——この一点が、チーム開発で Claude Code を安定して効かせる最短ルートです。
関連記事
出典
