なぜCLAUDE.mdは散らかるのか
CLAUDE.md(= Claude Codeに渡す『就業規則』のようなファイル。AIに毎回読ませたいルールをまとめたテキスト)を書き始めた人の多くが、同じ壁にぶつかる。
- 1ファイルが300行を超え、どこに何が書いてあるか分からない
- プロジェクトごとにコピペして、微妙にズレて増殖する
- 共通ルールを直したいのに、全プロジェクトを開いて書き換える羽目になる
- 長大なファイルを毎回読ませるので、トークン(= AIに文章を読ませる時の従量課金の単位。文字数に比例して料金がかかる) が膨らむ
原因はシンプルで、『全部1ファイルに書いている』からである。就業規則・技術仕様書・現場の注意書きを1冊の分厚いバインダーに綴じているような状態だ。新入社員(= Claude)は毎朝それを全部読まされる。効率が悪い。
3階層設計という解法
解決策は、Claude Codeが公式にサポートしている 3階層のCLAUDE.md を使い分けることだ。
- グローバル層
~/.claude/CLAUDE.md— 全プロジェクト共通の普遍ルール - プロジェクト層
<project>/CLAUDE.md— そのプロジェクト固有の技術スタックと設計 - モジュール層
<project>/<subdir>/CLAUDE.md— そのフォルダ配下でだけ効く罠と例外
Claude Codeは作業中のディレクトリに応じて、必要な階層だけを自動で読み込む。モジュール層はそのサブディレクトリで作業しているときにだけ読まれるので、関係ない時には1文字もトークンを消費しない。
層1: グローバル (~/.claude/CLAUDE.md)
ここには、どのプロジェクトでも絶対に変わらないルールだけを置く。言わば『会社全体の就業規則』だ。
# グローバルルール
- 日本語で応答する
- 機密情報(APIキー・パスワード)をコードに含めない
- 修正3回失敗したら一度立ち止まる
- コミットは conventional commits(日本語)
読めなくても大丈夫。要点はこうだ。『AIの話し方』『セキュリティの最低線』『Git運用の型』 のような、プロジェクトが変わっても変わらないものだけを置く。
ポイントは 書き過ぎない こと。ここに技術スタックを書くと、全プロジェクトで毎回読まれる無駄が生じる。『普遍 or not』で迷ったら、『普遍じゃない』側に倒すのが推奨されている。各層に書く中身の設計パターン（1行1ルール・Why併記・実践テンプレート）は、CLAUDE.mdの書き方: 生産性を10倍にする設計パターンで具体例つきで公開している。
層2: プロジェクト (/CLAUDE.md)
ここには、このプロジェクトの設計図を置く。『現場の仕様書』のイメージ。
# Claude Works
## 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/配下のファイルを読み込む
読めなくても大丈夫。要点は 『このフォルダで過去にやらかした失敗』を書き残す ということ。書くタイミングは『同じ失敗を2回目に見た瞬間』がちょうどいい。1回目は偶然かもしれないが、2回目は構造的な罠だ。
この層の強みは、Claudeがそのフォルダで作業している時にだけ読み込まれる点にある。別のモジュールを触っている時には1文字もトークンを食わない。
ある個人運営者の事例
ひとりでメディアを運営している個人開発者の話だ。最初は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が自発的に回避してくれる。失敗の記録がそのまま再発防止の仕組みになる。人間のチームで言えば、ヒヤリハット報告が自動で全新人に引き継がれる状態だ。
トークン効率を上げる書き方
3階層に分けるだけでも効くが、書き方の工夫でさらに効率が上がる。推奨されているのはこの3点だ。
- 箇条書き — 文章ではなくリストにする
- 命令形 — 『〜すること』『〜しない』と端的に
- 1行1ルール — 複数の指示を1行に詰めない
つまり、小説ではなく チェックリスト として書く。AIは自然言語も読めるが、箇条書きの方が同じ情報量でトークンが少なく済み、誤解も減る。
実際に海外の公開リポジトリがどう書いているかは、海外のCLAUDE.md事例ギャラリーで目的別に分類して紹介している。上手い実物を3つ読むほうが、理屈を10個覚えるより早い。
どの層に書くか迷ったときの判断フロー
実際に書き始めると、『これはどの層？』と迷うルールが必ず出てくる。判断は3つの質問で機械的に済ませられる。
- 全プロジェクトで常に真か？ — Yesならグローバル層。『日本語で応答』『機密情報を書かない』の類
- このリポジトリ固有の事情か？ — Yesならプロジェクト層。技術スタック、ディレクトリ構成、コマンド
- 特定フォルダでしか起きないか？ — Yesならモジュール層。『このAPIはリトライ必須』のような現場の罠
3つとも迷うなら、下の層に置く。下の層ほど読み込まれる場面が限定されるので、間違えたときの被害（無駄なトークン消費・関係ない場面での誤適用）が小さい。逆に『とりあえずグローバルへ』は最悪手で、全プロジェクトが巻き添えになる。この判断を機械的に処理できるようになると、CLAUDE.mdの手入れは1回5分の習慣に変わる。
なお、ここまでやってもAIがルールを破る場合の最終手段として、ルールをテキストではなく仕組みで強制する方法もある。post-tool-use hookで品質ゲートを物理的に強制する設計パターンが、その実装例だ。
エンジニアじゃない方へ
ここまで読んで『自分には難しそう』と感じた方へ。
CLAUDE.mdは、AIに渡すただのテキストファイルだ。プログラミング言語でもなければ、特殊な文法もない。メモ帳で開いて、日本語で箇条書きを書けば、それがそのままルールになる。
大事なのは**『AIに何を守ってほしいか』を言葉にする**ことで、コードを書くスキルではない。むしろ非エンジニアの方が、日常業務の『暗黙知』を言語化するのが上手いケースも多い。
個人事業を立ち上げたい人にとって、Claude CodeとCLAUDE.mdは 『自分専用の新入社員に就業規則を渡す』 という作業に近い。最初の1週間だけ頑張って規則を整えれば、その後はずっとその社員が一貫した仕事をしてくれる、そういう選択肢がある。Claude Code自体をこれから始める方は、Claude Code 使い方 完全ガイド2026が入り口として最短だ。
設定ファイル一式を無料配布している
本記事の3階層設計とセットで使える、エージェント運用の設定ファイル一式をClaude Code 6レイヤー構成 設定ファイル一式（zip）として無料配布している。エージェント定義ファイル8本、自動実行スクリプト、コスト管理フック、スケジューラー設定を同梱。あなたの事業内容に合わせて日本語部分を書き換えるだけで使える。
