CLAUDE.md 3階層と「なぜ」契約

私は複数のリポジトリを回しています。ブログ用の Astro サイト、Zenn の原稿、業務自動化の harness-ops。それぞれ技術スタックも規約も違います。

CLAUDE.md を1枚で運用していた頃、これで詰みました。~/.claude/CLAUDE.md にブログ側の内部リンク規約を書き足したら、Zenn の原稿を書く Claude が同じ規約を Zenn 記事に持ち込もうとしたのです。

問題は「1枚だと足りない」ことではありません。「1枚だと、そのルールがなぜそこにあるか」が消えることです。私は公式仕様の4スコープに沿って CLAUDE.md を分けました。分ける以上に大事な運用が1つある、と分けたあとに気づきました。ルールの隣に「なぜ」を対で残すことです。

Anthropic 公式は4スコープ

Anthropic の公式ドキュメント (2026-09 現在) は、CLAUDE.md の置き場所を4つに整理しています。

Managed policy は macOS だと /Library/Application Support/ClaudeCode/CLAUDE.md、Windows だと C:\Program Files\ClaudeCode\CLAUDE.md にパスが変わります。IT/DevOps 部門が MDM や Group Policy でデプロイする前提のスコープです。

私は個人事業主で従業員はゼロなので、自分に自分の policy を強制する意味がありません。実務では User/Project/Local の3階層で足ります。「4スコープの読解 → 3階層の運用」という段が要る、と言い換えてもいい。

4ファイルは「上書き」ではなく「積み重ね」

ここは仕様の勘違いが多い箇所なので、公式の表現をそのまま引用します。

All discovered files are concatenated into context rather than overriding each other.

つまり4つの CLAUDE.md は、上位が下位を上書きするのではなく、全部連結された状態で Claude に渡ります。読み込み順は「広いスコープが先、狭いスコープが後」。同一ディレクトリ内では CLAUDE.local.md が CLAUDE.md の後に読まれます。

作業ディレクトリの祖先に CLAUDE.md があれば、それも全部積まれます。矛盾するルールを別スコープに書くと、Claude がどちらを採るかは公式に「arbitrarily」と書かれています。実質、保証されません。だから「積み重なる前提で書き分ける」ことになります。

なぜ「なぜ」を対で残すのか

ここが本記事の中心です。

CLAUDE.md に書くルールは、書いた瞬間は自分にとって自明です。3ヶ月後には自明でなくなります。半年後には、私自身がそのルールを疑い始めます。「これ、外していいんじゃないか」と。理由を残していないと、そのときの自分は勘で判断します。

私の kenimoto-dev リポジトリの CLAUDE.md には、実際こう書いてあります。

### 絵文字アイコン禁止 (2026-08-01 制定)

- 根拠: 見出しやリスト項目の頭に絵文字を置く装飾は
  AI 生成コンテンツの兆候として明文化されている
  (WP:AIEMOJI、Washington Post 2025-11 の
  ChatGPT ログ大規模分析が典拠)

「絵文字禁止」だけでは、私は3ヶ月後に忘れます。だから根拠 (WP:AIEMOJI と Washington Post 調査) と制定日 (2026-08-01) を、ルールの隣に埋めています。これが「なぜ」契約です。ルールと、そのルールが生まれた理由の対をセットで残す。理由まで残すと、条件が変わったときに「今も成立しているか」を判定できます。

私の harness-ops リポジトリの CLAUDE.md にも同じパターンが並んでいます。

過去に claude -p heredoc 内のコードフェンスが
command substitution として誤評価されたり、
date -d "X +30 minutes" が日本語 locale で失敗して
カレンダー登録 Phase が set -e で死んだりした。

これは「シェルスクリプトを push 前に shellcheck に通す」というルールに対する「なぜ」の記録です。ルールと事故の対で書いてあるので、3ヶ月後にこの記述を見ても「まだ必要」と判断できます。

User scope に置くのはマシン固有だけ

~/.claude/CLAUDE.md に置いてよいのは、私のマシン全体で真であることだけです。

私はここに、ローカルで動かしているヘッドレスブラウザのポートとトークン取得コマンドを書いています。これは私のマシンでしか成立しない事実で、プロジェクトごとに変わりません。

逆に置いてはいけないのは、特定リポジトリ用のコーディング規約や文体ルールです。あるプロジェクトの規約を User scope に書くと、別のプロジェクトで作業中にも Claude がそのルールを守ろうとします。技術スタックが違うリポで無関係な規約を守ろうとする Claude を見た瞬間、scope 分割の必要性が刺さります。滑稽な失敗は、たいてい scope の混同から来ます。

Project scope は未来の自分と共有する契約

./CLAUDE.md または ./.claude/CLAUDE.md は、そのリポジトリに触るすべての人と共有するファイルです。個人事業主でも、未来の自分は他人です。

kenimoto-dev の CLAUDE.md には、絵文字禁止のほかに「<aside> callout の開閉タグの後に空行を入れる」というルールがあります。理由も一緒に書いてあります。「2026-09-03、sudoers 記事で検証状態とコラムが隣接して読めなくなった」。3ヶ月後の私が「この空行、要らなくないか」と思っても、この一行があるので手が止まります。

AGENTS.md と CLAUDE.md の使い分けを整理した 先の記事 にも通じるところがあります。AI に読ませる規約は「なぜ」を無くすと壊れる、という共通点です。

Local scope は実験と、Git に乗せないもの

./CLAUDE.local.md は、そのリポジトリ固有で、かつ Git に乗せたくないものを置く場所です。.gitignore に追加してから使います。

私は日常的にはあまり使いません。唯一の contributor が私なので、Project scope に書いても実質同じだからです。使うのは、実験中のルールを試しに追加してしばらく回し、有効なら Project scope に昇格させるとき。あるいは、外部に見せたくないローカル検証の手順を書き置くときです。

契約が壊れるパターン

3階層に分けても、「なぜ」を書き忘れれば同じ問題に戻ります。

例えば Project CLAUDE.md に「<aside> callout の開閉タグ後に空行」とだけ書いたとします。理由を書いていないので、半年後の自分が読み返して「これ、単に見た目の話かな」と誤解する。勢いで空行を詰める。翌週、Markdown が処理されない記事を自分で見つけて慌てて戻す。契約書に判子だけ残して、条項が消えているようなものです。

だから今は、ルールを書くたびに「なぜ」を対で書きます。書けないルールは、そのルール自体を疑います。

まとめ

• 公式仕様の CLAUDE.md は4スコープ (Managed / User / Project / Local)
• 4ファイルは上書きではなく、全部連結して Claude に渡される
• 個人事業主に Managed は実務上不要、User/Project/Local の3階層で回る
• User scope はマシン固有だけ、Project scope は未来の自分との契約、Local scope は実験と Git 外
• ルールだけ書くと3ヶ月後の自分が理由を推測して緩める。「なぜ」を隣に書くのが契約

CLAUDE.md は、未来の自分と過去の Claude への手紙です。理由を書き忘れると、未来の自分から先に読めなくなります。

参考

• Anthropic 公式: How Claude remembers your project
• 関連: CLAUDE.md は結局 Context Engineering を1ファイルに凝縮したものだった
• 関連: AGENTS.md と CLAUDE.md の違いは「専用機か汎用機か」ではない

CLAUDE.md の設計、Plan Mode、チーム展開まで含めた実践は Claude Code Mastery にまとめています。