CLAUDE.md ベストプラクティス完全版 — 200行の壁・@import・モジュールルーティングを Anthropic 公式仕様で再設計する（2026年5月版）

三ヶ月前にきれいに書いた CLAUDE.md が、なぜか今は守られない——。Claude Code を本気で使い込み始めると、ほぼ全員が一度はぶつかる現象です。原因は 「ファイルが腐った」のではなく、「context window という有限資源の中で、その指示が静かに無視されるしきい値を超えた」 こと。本記事は Anthropic 公式ドキュメント^[1][2]と、HumanLayer が公開した実装ノウハウ^[3]、そして筆者が自身の personal-os リポジトリで運用している実例を統合し、CLAUDE.md を腐らせない設計原則を 13 章にわたって整理します。所要時間は約 18 分です。

you@your-repo:~/.claude ❯ 01_intro.mdなぜ CLAUDE.md は「ある日突然」効かなくなるのか

Claude Code をしばらく使い込んだ人は、ほぼ全員が同じ場面に遭遇します。最初は数行のシンプルな CLAUDE.md から始まり、Claude が同じミスをするたびに「これも書いておこう」と一行ずつ足していく。半年後、ファイルは 400 行を超え、プロジェクトの宝典のような体裁になっている。それなのに——肝心の指示が、いつのまにか守られていない。

HumanLayer のエンジニア Sean Smith は、自身の運用経験からこの現象を明確に言語化しています^[3]。

All else being equal, an LLM will perform better on a task when its context window is full of focused, relevant context. This is the central reason why a bloated CLAUDE.md can hurt more than it helps.

Sean Smith, "Writing a Good CLAUDE.md" (HumanLayer, 2025) / [3]

そして Anthropic 公式のベストプラクティス文書も、同じことを別の角度で警告しています^[2]。

Bloated CLAUDE.md files cause Claude to ignore your actual instructions! ... If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost.

Anthropic, "Best Practices for Claude Code" / [2]

つまり 「指示を増やすほど、各指示の効きは弱くなる」。この一見直感に反する性質こそが、CLAUDE.md 設計の出発点です。本記事では、なぜそうなるのか・何をどう書くべきか・どう腐らせずに運用するかを、公式仕様と実運用の両面から整理していきます。

you@your-repo:~/.claude ❯ 02_summary.md結論：CLAUDE.md 設計の 3 原則

本論に入る前に、本記事の結論を 3 つに圧縮しておきます。残りの章はすべて、この 3 原則の補強と実装方法です。

1. 200 行を厳守する。これは Anthropic 公式が明示する目安^[1]であり、HumanLayer の研究^[3]が示す「フロンティア LLM が一貫して守れる指示数の壁（150〜200）」とも一致する。超えた瞬間に、すべての指示の遵守率が下がる。
2. 4 階層のスコープを使い分ける。Managed policy / Project / User / Local の 4 種類の置き場所^[1]はそれぞれ役割が異なる。「全部 root の CLAUDE.md に書く」発想を捨てるところから始まる。
3. Progressive Disclosure（進歩的開示）で参照に逃がす。常に必要な指示だけを CLAUDE.md に残し、それ以外は @import^[1] や .claude/rules/ の path-scoped ルール^[1]、Skill^[4]へ追い出す。

この 3 つは独立した tips ではなく、「context window は有限である」という 1 つの物理法則から導かれる帰結です。LLM の「文脈に何を入れるか」が出力品質を決める以上、CLAUDE.md は「何を書くか」よりも「何を書かないか」のほうが重要になります。

you@your-repo:~/.claude ❯ 03_vs_auto_memory.mdCLAUDE.md と Auto memory：混同しないための境界線

2026 年に入ってから Claude Code には、CLAUDE.md とは別の記憶機構として Auto memory^[1]（v2.1.59 以降）が標準搭載されました。両者は似た役割を持ちながら、扱いが本質的に異なります。最初にここを切り分けないと、設計の出発点が崩れます。

境界の引き方は単純です。「チームメンバー全員に共有したい」なら CLAUDE.md、「自分の作業環境に閉じる学習」なら Auto memory に任せる。あなたが「いつも pnpm を使って」と Claude に伝えると、Claude は黙って Auto memory に保存します^[1]。それを git で共有したい瞬間が来たら、初めて CLAUDE.md に昇格させればいい——という運用が公式の想定です。

you@your-repo:~/.claude ❯ 04_scopes.md4 階層スコープ：どこに何を置くか

Anthropic は CLAUDE.md の置き場所として、明確に 4 つの階層を用意しています^[1]。「とりあえずプロジェクト直下に CLAUDE.md を置く」だけでは、4 つあるうちの 1 つしか使っていないことになります。

すべての階層の CLAUDE.md は「上書きではなく連結」でロードされます^[1]。読み込み順はファイルシステムのルートから作業ディレクトリへ降りる順なので、より具体的なファイル（プロジェクト直下）が後ろに置かれ、優先されます。同一階層では CLAUDE.local.md が CLAUDE.md の後に追記される、という細部まで仕様化されています。

# 例: foo/bar/ で claude を起動した場合

[1] /Library/Application Support/ClaudeCode/CLAUDE.md     # Managed
[2] ~/.claude/CLAUDE.md                                   # User
[3] foo/CLAUDE.md                                         # 親
[4] foo/CLAUDE.md  + foo/CLAUDE.local.md
[5] foo/bar/CLAUDE.md + foo/bar/CLAUDE.local.md           # 作業dir
                ↑ あとから読まれるほど、優先される

この仕様を理解すると、「全員に効かせたい規約は ./CLAUDE.md、自分だけの癖は ~/.claude/CLAUDE.md、特定プロジェクト固有の個人メモは ./CLAUDE.local.md」という置き分けが自然に決まります。逆に言うと、これを混同して ./CLAUDE.md に「自分は Vim で編集している」みたいな個人事情まで書き込んでしまうと、それがチーム全員の context を毎セッション圧迫することになります。

you@your-repo:~/.claude ❯ 05_200_line_wall.md破綻パターン①：「200 行の壁」と context window の物理学

本記事の最重要ポイントです。なぜ 200 行なのか、そこに物理的な根拠があります。Anthropic 公式の表現は単刀直入です^[1]。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

Anthropic, "How Claude remembers your project" — Write effective instructions / [1]

HumanLayer の Sean Smith は、これに研究的裏付けを加えて 「150-instruction wall」と呼んでいます^[3]。フロンティアモデル（Claude Opus / Sonnet 等）は 150〜200 個程度の指示までは合理的に守れるが、それを超えると遵守率が崩れる。さらに重要なのは、Claude Code の system prompt 自体が独立に約 50 個の指示を消費しているという事実です。つまり、あなたの CLAUDE.md に与えられた純粋な「指示予算」は、実は 100〜150 個程度しかありません。

200 行というのは「指示数換算で残予算を超えないライン」を表す経験則です。逆にいえば、200 行をオーバーした瞬間にすべての指示の遵守率が下がるので、本当に効かせたい 1 行のために、雑多な 100 行を削る価値があります。Anthropic 公式は「For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it」^[2] と剪定の問いまで提供しています。

# 全 CLAUDE.md と CLAUDE.local.md を行数つきで一覧
$ find . -maxdepth 4 \( -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) -exec wc -l {} +

# ホーム以下も含めるなら
$ wc -l ~/.claude/CLAUDE.md ./CLAUDE.md ./CLAUDE.local.md 2>/dev/null

you@your-repo:~/.claude ❯ 06_what_not_to_write.md破綻パターン②：書いてはいけない 7 つの内容

200 行を守るだけでは足りません。「200 行に何を入れないか」のセンスを持つことのほうが重要です。Anthropic 公式と HumanLayer のガイドを突き合わせて、CLAUDE.md に書かないほうが結果が良くなる項目を 7 つに整理しました^[2][3]。

1 番目について、HumanLayer の表現が秀逸です^[3]。

Never send an LLM to do a linter's job.

Sean Smith, "Writing a Good CLAUDE.md" / [3]

Claude にトークンを払って毎回スタイルチェックをさせるのは、Ferrari でゴミ収集に行くのと同じです。スタイルは Hook^[5]（Claude のファイル編集後に biome check --write を自動実行）か pre-commit hook（git 側）で機械的に処理し、CLAUDE.md は人間が判断すべき設計事項に集中させる——これが正しい役割分担です。

you@your-repo:~/.claude ❯ 07_what_why_how.md設計原則①：WHAT / WHY / HOW で取捨選択する

「何を書くか」を悩んだとき、HumanLayer が提唱している WHAT / WHY / HOW の 3 軸^[3] はそのままチェックリストとして使えます。

大事なのは、これら 3 軸すべてを「Claude がコードを読んで自力で導けない情報か？」でフィルタすることです。package.json を見れば分かるコマンドは書く価値が低い。逆に「monorepo 内のあるパッケージは過去の事情で別の build tool を使っている」のような歴史的・暗黙の制約は、コードからは絶対に推測できない——ここが CLAUDE.md の真の存在意義です。

you@your-repo:~/.claude ❯ 08_progressive_disclosure.md設計原則②：Progressive Disclosure と @import

200 行で収まらない情報を「捨てる」のではなく、必要なときだけ見に行ける場所に置くのが Progressive Disclosure（進歩的開示）の発想です。Claude Code は @path/to/file 構文で他のファイルを CLAUDE.md から参照できます^[1]。

# Project Overview

このリポジトリは B2B SaaS のバックエンド（Python + FastAPI）。

# 詳細は以下を参照

- 全体アーキテクチャ: @docs/architecture.md
- API 設計規約: @docs/api-conventions.md
- リリース手順: @docs/release.md

# 個人作業ファイル（worktree 共有）

@~/.claude/my-shortcuts.md

仕様の細部は重要なので押さえておきます^[1]。

• 相対パス・絶対パス・~/ いずれも可
• 相対パスは「その import を書いているファイルからの相対」（カレントディレクトリ基準ではない）
• import の中で更に import 可能、最大 5 階層のネスト
• 初回 import 時、外部ファイルは Claude が承認ダイアログを出す

もう一つ、Cursor 等他ツールとの併用問題もこの仕組みで解決できます。Anthropic 公式の推奨は次のとおり^[1]。

@AGENTS.md

## Claude Code 固有の追記
- src/billing/ 配下を変更する時は plan mode を使え

これで Cursor は AGENTS.md、Claude Code は CLAUDE.md を読みつつ、実体は同じファイルを参照する——という二重管理ゼロの運用が成立します。

you@your-repo:~/.claude ❯ 09_path_scoped_rules.md設計原則③：.claude/rules/ で path-scoped に追い出す

本物の context 削減策がこちらです。.claude/rules/ ディレクトリに置いた markdown ファイルは、デフォルトでは CLAUDE.md と同じく毎セッションロードされますが、YAML frontmatter で paths を指定すると、Claude が該当パターンのファイルを開いた時にだけロードされます^[1]。これが本記事の最重要テクニックです。

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.py"
---

# API 開発ルール

- すべてのエンドポイントで input validation を必須とする
- エラーレスポンスは標準の `ApiError` 形式に従う
- OpenAPI コメントを忘れない

このルールは、Claude が src/api/ 配下のファイルに触れた時にだけ context に入ります。フロントエンドの修正をしているときは一切ロードされないので、context window の節約になります。「いつも必要なルールは CLAUDE.md、たまにしか使わないルールは .claude/rules/ に paths 付きで」が黄金パターンです。

you@your-repo:~/.claude ❯ 10_personal_os.md実例：personal-os のモジュールルーティング表方式

ここまでの原則を実際にどう適用するか、筆者が運用している personal-os リポジトリ（個人の Brain OS としての Claude Code 環境）を例に解説します。root CLAUDE.md はわずか 30 行。本体の指示は同じリポジトリの 11 個のサブディレクトリに分散しています。

# Personal OS

このリポジトリは [筆者] の Personal Brain OS。
AI エージェントが私のコンテキスト（声・ブランド・目標・連絡先・ワークフロー）
を把握し、一貫性のある出力を生成するためのファイルベース OS。

## モジュール一覧（ルーティング表）
タスクに応じて、以下の該当モジュールのみを参照すること。

- 文章作成・ブランド関連 → `identity/` を参照
- ブログ・SNS 投稿・コンテンツ制作 → `content/` を参照
- リサーチ・学習メモ → `knowledge/` を参照
- 連絡先・人間関係・会議準備 → `network/` を参照
- タスク管理・目標・日次運用 → `operations/` を参照
- 過去の判断・経験・失敗 → `memory/` を参照
- 価値観・判断基準 → `values/` を参照

## コアルール
1. 全モジュールを一度に読み込まない。タスクに関連するモジュールのみ参照する。
2. データファイル（JSONL）は行単位で読む。全件パースしない。
3. JSONL への書き込みは追記（append）のみ。既存行の編集・削除は禁止。
4. 判断に迷ったら `values/heuristics.yaml` を参照する。
5. 文章を書く際は必ず `identity/tone-of-voice.md` を参照する。

この CLAUDE.md がやっていることは、たった 2 つです。

1. ルーティング表：「どのタスクなら、どのディレクトリを読みに行けばいいか」の地図を提供する。Claude はこれを見て、当該ディレクトリの中だけを Glob / Read する。
2. 絶対遵守の不変ルール：5 個だけ。「全モジュールを一度に読み込まない」「データは追記専用」のような各モジュールに共通の鉄則のみ書く。

この方式の効果は、毎セッションのトークン消費が劇的に下がる点にあります。詳細は各サブディレクトリの identity/CLAUDE.md や content/CLAUDE.md に書いてあり、Claude がそのディレクトリのファイルを読んだ瞬間にだけ自動で context に入る——前章で説明した Anthropic 公式の subdirectory CLAUDE.md オンデマンドロード^[1] をそのまま活用しています。

you@your-repo:~/.claude ❯ 11_compaction_safe.mdCompaction 耐性のある書き方

長時間セッションで /compact が発火（または自動圧縮）したとき、何が残り何が消えるかを把握しておかないと、せっかく書いた CLAUDE.md が「圧縮後だけ無視される」事態になります。Anthropic 公式の挙動仕様は次のとおり^[1]。

含意は明確です。「絶対に守らせたいルールは root CLAUDE.md に置け、サブディレクトリ任せにするな」。逆に、サブディレクトリの CLAUDE.md はあくまで「そのディレクトリで作業する時だけ効けばいい補助情報」として位置づけるのが正解です。

もう一つ、見落とされがちなのが HTML コメントが除去される仕様^[1]。これを利用すれば、人間メンテナ向けのメモを context を消費せずに残せます。

<!-- 2026-04 update: Auto memory 導入につき
     ここに書いていた個人の癖は ~/.claude/CLAUDE.md に移動 -->

# Build & Test
- `pnpm install --frozen-lockfile` でインストール
- `pnpm test` ではなく `pnpm vitest run --coverage` を使え

「なぜここをこう書いたか」「いつ整理予定か」のような履歴情報を Claude に読ませる必要はない。HTML コメントに退避させて、token 予算を本物の指示に集中させましょう。

you@your-repo:~/.claude ❯ 12_maintenance.mdCLAUDE.md を「コードのように」運用する

CLAUDE.md は書いて終わりのドキュメントではありません。Anthropic 公式は次のように位置づけています^[2]。

Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude's behavior actually shifts.

Anthropic, "Best Practices for Claude Code" / [2]

具体的には次のような運用ルーチンに落とせます。

1. 「同じ訂正を 2 回入力したら 3 回目は CLAUDE.md に追加」。これは Anthropic 公式の追加トリガーそのもの^[1]。
2. 月 1 回の剪定セッション。「Claude がもう正しく動いている指示」を勇気を持って消す。守られているなら、その指示は仕事を終えた、または不要だった証拠。
3. 強調語は最後の手段。IMPORTANT や YOU MUST は遵守率を上げるテクニック^[2] ですが、乱用すれば全体的に弱まります。本当に外せないルールにだけ使う。
4. /memory コマンドで現状確認。今のセッションでどの CLAUDE.md / rules がロードされているかが一覧表示されます^[1]。「書いたのに効かない」と思った時は、まずここを開く。
5. git commit して history を残す。ファイルの変遷自体が、プロジェクトの「Claude チューニング履歴」になります。

you@your-repo:~/.claude ❯ 13_summary.mdセルフチェック 10 項目とまとめ

本記事の内容を、いつでも自分の CLAUDE.md に当てるためのチェックリストに落とし込みました。1 つでも該当したら、剪定の余地があります。

1. root CLAUDE.md が 200 行を超えている（Ch05）
2. 「インデント幅」「セミコロンの有無」など linter の仕事が書かれている（Ch06 #1）
3. /init で生成された初期ファイルをそのまま運用している（Ch06 注釈）
4. npm script や API ドキュメントの写経がある（Ch06 #3, #4）
5. 個人プリファレンスとプロジェクト規約が同じファイルに混在（Ch04）
6. Cursor 等のために AGENTS.md と二重管理している（Ch08）
7. 特定タスクでだけ使う手順が CLAUDE.md に居座っている（Ch09 → Skill 化）
8. サブディレクトリの CLAUDE.md に絶対遵守ルールを入れている（Ch11）
9. 履歴メモやメンテナの吐露が、HTML コメントでなく本文に書かれている（Ch11）
10. 3 ヶ月以上、剪定コミットがない（Ch12）

最後に、本記事のすべてを 3 行に圧縮します。

1. CLAUDE.md は context window という有限資源を奪い合うコードである。書く前に「これがないと Claude が間違える？」を必ず問う。
2. 4 階層（Managed / Project / User / Local）と 3 つの逃がし先（@import / .claude/rules/ / Skill）を使い分ければ、200 行の縛りは現実的に維持できる。
3. CLAUDE.md は書いて終わりではなく「育てて剪定するコード」。月 1 回の剪定セッションを習慣化するだけで、Claude の品質は半年後に明確に変わる。

あなたの CLAUDE.md は、Claude のためにあるのではありません。Claude を通して未来の自分とチームを楽にするためにあります。今夜 5 分だけ、自分の CLAUDE.md を開いて行数を数えるところから始めてみてください。