なぜCLAUDE.mdは散らかるのか

CLAUDE.md(= Claude Codeに渡す『就業規則』のようなファイル。AIに毎回読ませたいルールをまとめたテキスト)を書き始めた人の多くが、同じ壁にぶつかる。

  • 1ファイルが300行を超え、どこに何が書いてあるか分からない
  • プロジェクトごとにコピペして、微妙にズレて増殖する
  • 共通ルールを直したいのに、全プロジェクトを開いて書き換える羽目になる
  • 長大なファイルを毎回読ませるので、トークン(= AIに文章を読ませる時の従量課金の単位。文字数に比例して料金がかかる) が膨らむ

原因はシンプルで、『全部1ファイルに書いている』からである。就業規則・技術仕様書・現場の注意書きを1冊の分厚いバインダーに綴じているような状態だ。新入社員(= Claude)は毎朝それを全部読まされる。効率が悪い。

3階層設計という解法

解決策は、Claude Codeが公式にサポートしている 3階層のCLAUDE.md を使い分けることだ。

  1. グローバル層 ~/.claude/CLAUDE.md — 全プロジェクト共通の普遍ルール
  2. プロジェクト層 <project>/CLAUDE.md — そのプロジェクト固有の技術スタックと設計
  3. モジュール層 <project>/<subdir>/CLAUDE.md — そのフォルダ配下でだけ効く罠と例外

Claude Codeは作業中のディレクトリに応じて、必要な階層だけを自動で読み込む。モジュール層はそのサブディレクトリで作業しているときにだけ読まれるので、関係ない時には1文字もトークンを消費しない。

3階層CLAUDE.mdの全体像。グローバル(家のてっぺん) → プロジェクト(各プロジェクトの玄関) → モジュール(部屋ごとの注意書き)という入れ子構造

図: 3階層CLAUDE.mdの全体像。グローバル(家のてっぺん) → プロジェクト(各プロジェクトの玄関) → モジュール(部屋ごとの注意書き)という入れ子構造

層1: グローバル (~/.claude/CLAUDE.md)

ここには、どのプロジェクトでも絶対に変わらないルールだけを置く。言わば『会社全体の就業規則』だ。

# グローバルルール
- 日本語で応答する
- 機密情報(APIキー・パスワード)をコードに含めない
- 修正3回失敗したら一度立ち止まる
- コミットは conventional commits(日本語)

読めなくても大丈夫。要点はこうだ。『AIの話し方』『セキュリティの最低線』『Git運用の型』 のような、プロジェクトが変わっても変わらないものだけを置く。

ポイントは 書き過ぎない こと。ここに技術スタックを書くと、全プロジェクトで毎回読まれる無駄が生じる。『普遍 or not』で迷ったら、『普遍じゃない』側に倒すのが推奨されている。

層2: プロジェクト (/CLAUDE.md)

ここには、このプロジェクトの設計図を置く。『現場の仕様書』のイメージ。

# Claude Lab
## Stack
- Next.js 16 (App Router), TypeScript
- Supabase(= DB+認証の全部入りサービス)
- Vercel Cron(= 定時実行)
## Architecture
- lib/fetchers/ — ソース別の収集処理
- lib/ai/analyze.ts — AI分析パイプライン
- app/api/cron/ — 定時実行エンドポイント

読めなくても大丈夫。要点は 『何で作っていて、どこに何があるか』 の地図だけ書く、ということ。

ここに『日本語で応答する』と書いてしまうと、グローバル層と重複する。重複は混乱の元なので、書くなら必ずどちらか一方に寄せる。

層3: モジュール (/CLAUDE.md)

最も過小評価されているのがこの層だ。ここには、そのフォルダでだけ効く罠と例外を置く。『部屋ごとの注意書き』である。

例えば lib/ai/CLAUDE.md にはこう書く。

# AI分析モジュール固有
- Claude APIのレスポンスは必ずzodでパースする
- トークン超過エラー時は指数バックオフ(= 徐々に待ち時間を長くする再試行)
- プロンプトのハードコード禁止。prompts/配下のファイルを読み込む

読めなくても大丈夫。要点は 『このフォルダで過去にやらかした失敗』を書き残す ということ。

この層の強みは、Claudeがそのフォルダで作業している時にだけ読み込まれる点にある。別のモジュールを触っている時には1文字もトークンを食わない。

Claude Codeが作業開始時に読むファイルの流れ。cdしたディレクトリから上に向かって各層のCLAUDE.mdを順に積み上げて文脈を構築する時系列図

図: Claude Codeが作業開始時に読むファイルの流れ。cdしたディレクトリから上に向かって各層のCLAUDE.mdを順に積み上げて文脈を構築する時系列図

ある個人運営者の事例

ひとりでメディアを運営している個人開発者の話だ。最初は1ファイルのCLAUDE.mdに全部書いていた。400行を超えた頃から、AIの挙動が鈍り、トークン請求が膨らみ始めた。

3階層に分解してからの変化はこうだった。

  • グローバル層: 50行(日本語応答・セキュリティ・Git規約)
  • プロジェクト層: 80行(技術スタック・ディレクトリ構成・Cron設定)
  • モジュール層: lib/ai/ lib/social/ supabase/ に各20-40行の罠メモ

結果、1ファイルあたりの行数が3分の1以下になり、AIの応答速度が上がった。さらに、別プロジェクトを立ち上げた時もグローバル層をそのまま再利用できるため、新規プロジェクトのセットアップが数分で終わるようになった。

そして最大の効果は、『モジュール固有の罠を踏まなくなった』 こと。以前はSupabaseのjoin型キャストのような細かい落とし穴を毎回踏んでいたが、モジュール層に1行書き残しておくだけで、次回以降Claudeが自発的に回避してくれる。

1ファイル運用 vs 3階層運用の比較表。行数・トークン消費・ルールの重複・罠の再発率の4項目で左右対比

図: 1ファイル運用 vs 3階層運用の比較表。行数・トークン消費・ルールの重複・罠の再発率の4項目で左右対比

トークン効率を上げる書き方

3階層に分けるだけでも効くが、書き方の工夫でさらに効率が上がる。推奨されているのはこの3点だ。

  1. 箇条書き — 文章ではなくリストにする
  2. 命令形 — 『〜すること』『〜しない』と端的に
  3. 1行1ルール — 複数の指示を1行に詰めない

つまり、小説ではなく チェックリスト として書く。AIは自然言語も読めるが、箇条書きの方が同じ情報量でトークンが少なく済み、誤解も減る。

エンジニアじゃない方へ

ここまで読んで『自分には難しそう』と感じた方へ。

CLAUDE.mdは、AIに渡すただのテキストファイルだ。プログラミング言語でもなければ、特殊な文法もない。メモ帳で開いて、日本語で箇条書きを書けば、それがそのままルールになる。

大事なのは**『AIに何を守ってほしいか』を言葉にする**ことで、コードを書くスキルではない。むしろ非エンジニアの方が、日常業務の『暗黙知』を言語化するのが上手いケースも多い。

個人事業を立ち上げたい人にとって、Claude CodeとCLAUDE.mdは 『自分専用の新入社員に就業規則を渡す』 という作業に近い。最初の1週間だけ頑張って規則を整えれば、その後はずっとその社員が一貫した仕事をしてくれる、そういう選択肢がある。

🎁 特典: 設定ファイル一式ダウンロード

本記事で解説した3階層構造を、そのままコピーして使えるテンプレート一式として用意した。

同梱物:

  • ~/.claude/CLAUDE.md グローバルテンプレート(日本語応答・セキュリティ・Git規約入り)
  • <project>/CLAUDE.md プロジェクトテンプレート(Next.js + Supabase想定)
  • <subdir>/CLAUDE.md モジュールテンプレート3種(API/DB/AI分析)
  • カテゴリ分けチートシート(どのルールをどの層に置くかの判断基準)
  • トークン節約メモ(箇条書き化・重複削除・相対パス化のコツ)

解凍して、あなたのメディアテーマや事業内容に合わせて書き換えるだけで使える。

👉 ダウンロードはこちら

📚 参考リファレンス