夜明けの山々を映す静かな湖面

解説！フォルダ階層別CLAUDE.mdの役割【基礎編】

2026年8月16日 ・ 約11分 ・ AI活用

Claude Codeを日常的に使っていると、「毎回同じ指示を繰り返している」「プロジェクトごとにルールを説明し直すのが面倒」と感じる場面が出てきます。この壁を越える鍵は、Claudeのフォルダ階層とCLAUDE.mdという仕組みを理解し、設計することにあります。この記事は基礎編として、階層の仕組みそのものと、書くべき内容の判断基準を3つのTIPSに整理してお届けします。実際の運用方法は、後半の応用編で扱います。

TIP1：Claude Codeのフォルダ階層とCLAUDE.mdの役割

Claude Codeを使いこなす上で最初に理解すべきは、CLAUDE.mdが「どこか1箇所に置く設定ファイル」ではないという点です。Claude Codeは作業フォルダから上の階層へとフォルダをたどりながら、行く先々にある同じ名前のファイル――CLAUDE.md――をすべて連結して読み込みます。つまり、同じファイル名でありながら、置かれた場所（階層）によって役割が異なる、複数のCLAUDE.mdが同時に存在しうるということです。

公式には次の4つのスコープが用意されています。

スコープ 配置パス 共有範囲
組織ポリシー OS依存の管理用パス 組織全体（管理者が配布）
ユーザー個人 ~/.claude/CLAUDE.md 自分のすべてのプロジェクト
プロジェクト ./CLAUDE.md チームで共有可
ローカル個人 ./CLAUDE.local.md 自分のみ（Git管理外が推奨）

出典：suwash「Claude Codeの指示をどこに書くか」

具体的にどのパスにどんな内容を置くのか、実例は後半の応用編で詳しく見ていきます。ここではまず、階層という考え方そのものを掴んでおきましょう。

読み込みの優先順位は「広いスコープが先」で、作業ディレクトリから見つかったCLAUDE.mdは上位に向かって連結され、すべて同時にコンテキストへ注入されます。つまり1つを選ぶのではなく、複数階層が同時に効いているという理解が実務では重要です。文章だけだとイメージしづらいので、起動時の流れを図にまとめました。

CLAUDE.md読み込みの順序を示すフロー図。あなたのセッション開始から、組織ポリシー・ユーザー個人・プロジェクト・ローカル個人の4階層を経て、コンテキストへ連結されるまでの流れと、各階層の読み込み条件を示す

広いスコープほど先に読み込まれ、作業ディレクトリに近い設定ほど後から連結される。rules/配下も同じ仕組みに乗っており、paths:の指定有無で「毎回無条件」か「該当ファイルを開いた時だけ」かが分かれます（詳しくはTIP2で扱います）。

実務でこの階層をどう使い分けるかが、TIPの核心です。

  • ユーザー個人の階層：自分のすべてのプロジェクトに適用したい、仕事の進め方そのもの。口調、確認の基準、報告のスタイルなど。
  • 中間の階層：複数プロジェクトをジャンルごとにまとめるための共通ルール。これは公式仕様ではなく、利用者が独自に運用しているケースが多い工夫ですが、プロジェクト数が増えるほど効いてきます。
  • プロジェクト固有の階層：そのプロジェクトだけのビルドコマンド、ディレクトリ構成、命名規則など。

なぜわざわざ分けるのでしょうか。すべてを1つのファイルに混在させると、無関係な作業をしているときにも過去の注意書きが毎回読み込まれてしまいます。この状態は「コンテキスト負債」と呼ばれ、放置するとトークン消費（AIが一度に処理できる情報量の消費）が増え、指示に従う精度が下がる現象が指摘されています。同じ失敗を2回以上訂正した、Claude Codeが以前の指示に従わなくなった、といった兆候が出たら黄色信号です。階層を分けることは、単なる整理整頓ではなく、AIの応答品質を保つための設計そのものだと言えます。

TIP2：CLAUDE.mdとは何か、Claude Codeの構造

CLAUDE.mdは、Claude Codeが起動するたびに自動で読み込む常時適用の指示書です。TIP1で見た通り複数の階層に置けますが、ここではまず1つのCLAUDE.mdが持つ基本的な性質を確認します。同じくClaude Codeを制御する仕組みに「SKILL」がありますが、両者の役割は明確に分かれています。

SKILLは特定タスクの呼び出し型指示書です。では、プロジェクト全体に常に適用したいルールはどこに書けばいいのでしょうか。その答えがCLAUDE.mdです。 ―― pekopugu「CLAUDE.mdでプロジェクトを育てる」

つまり、「呼び出したときだけ使う専門知識」はSKILL、「常に効かせておきたいルール」はCLAUDE.md、という住み分けです。

CLAUDE.mdに書く内容としてもう1つ重要な視点があります。ある実践記録では、次のように述べられています。

ポイントは「AIに何をさせたいか」ではなく「自分がどう仕事を進めたいか」を書くことです。 ―― nogataka「CLAUDE.mdを設計するとClaude Codeの生産性が別物になる」

タスクの手順書ではなく、進め方の流儀を書く場所として捉えると、TIP1で見た階層設計の意図もより理解しやすくなります。

なお、Claude Codeの挙動を制御する手段はCLAUDE.mdだけではありません。技術記事では「7つの指示面」として整理されています。

手段 一言要約
CLAUDE.md 毎セッション自動で読み込まれる、常駐知識の置き場
Rules CLAUDE.mdを補完するモジュール型の制約。パスを指定しない限りCLAUDE.mdと同じく毎回無条件で全文読み込まれる。ファイルパスを指定した場合だけ、該当ファイルを開いた時に限定される
Skills 呼び出したときだけ読み込まれる手順書
Subagents 独立した作業領域で動き、結果の要約だけを返す
Hooks 決まったタイミングで確定的に発火する自動処理

出典：suwash、前掲記事

この中でCLAUDE.mdと、パス指定のないRulesは「毎セッション、無条件に全文読み込まれる」という特別な性格を持っています。読み込まれる量が多いほど処理コストが上がるため、何を書き何を書かないかの判断が、そのまま使い勝手に直結します（応用編で実測データとともに掘り下げます）。

TIP3：カテゴリ・サブフォルダ設計の原則

ルールは書き足すほど増えていきます。増加にどう対応するかにも、確立されたコツがあります。

1つは、同じカテゴリのルールが複数集まった時点でサブフォルダに切り出し、索引としてのREADME.mdを必ず置くという運用です。命名も規則的にしておくと、後から見返したときに迷いません。ただし、このREADME.mdも中身がある限り毎回全文読み込まれます。索引だからコストがかからない、というわけではない点には注意が必要です（この点は応用編で実測データとともに詳しく見ます）。

もう1つは、そもそも何を書き残すかの判断基準です。この点はAnthropic公式のベストプラクティスガイドでも明言されています。

Keep it concise. For each line, ask: “Would removing this cause Claude to make mistakes?” If not, cut it. （簡潔に保ちましょう。各行について「これを削除したらClaudeが間違えるようになるか」を自問してください。答えがNoなら削ります。） ―― Anthropic公式「Best practices for Claude Code」

具体的な行数の目安は、公式ドキュメントの別ページで「CLAUDE.mdは1ファイル200行未満を目安に」と明記されています。suwashの記事が挙げていた200行という数字も、実はこの公式の目安と一致していたわけです。コミュニティ側でもおおむね同水準（300行未満が目安、という声もあります）で、Claude Code運用のノウハウ発信で知られるHumanLayer社のブログでは、ルートのCLAUDE.mdを60行未満に抑えている実例も紹介されています。

出典：How Claude remembers your project、Writing a good CLAUDE.md（HumanLayer）

参考までに、私の~/.claude/rules/にある開発ルール用ファイル（development.md）を実測すると223行でした。公式の目安（200行未満）をわずかに超えており、私自身「体感的に大きい」と感じていた印象は、実測でも裏付けられた形です。棚卸しの余地がありそうです。

この基準は、ルールを増やすときだけでなく、既存のルールを棚卸しするときにも使えます。実際、ファイルをテーマ別に分けただけでは総量は減らないという指摘もあります。

rules/はファイルを分けても総量は変わりません。ただし、ドメイン別にファイルを分けることで追記時の判断コストは下がります。 ―― pepabo「CLAUDE.mdの肥大化を3層構造で83%軽くした」

つまりサブフォルダ化の効果は「軽量化」そのものより、「どこに何を足すか迷わなくなる」という運用上の速さにあります。増えたら整理する、という当たり前の習慣が、AIとの協働では読み込みコストと直結している点が、通常のファイル整理と少し違うところです。

どこに置くか迷ったときの判断フロー

新しいルールを思いついたとき、置き場所は次の順番で決めます。

新しいルールを追加したい
 ├─ 全プロジェクトに共通する自分の流儀か？
 │    → ユーザー個人の階層（~/.claude/CLAUDE.md）
 ├─ 特定ジャンルの複数プロジェクトに共通する制約か？
 │    → 中間階層（ジャンル共通のCLAUDE.md）
 ├─ そのプロジェクトだけの詳細か？
 │    → プロジェクト固有階層
 └─ 明示的に呼び出したときだけ使う手順書か？
      → SKILL（別ファイルに切り出す）

TIP2で触れたCLAUDE.mdとSKILLの住み分け（常時適用か、呼び出し型か）を最初の判断軸に加えることで、「とりあえずCLAUDE.mdに書く」という肥大化の入口を防げます。参考：pepabo、前掲記事の切り分けフローを、階層設計向けに再構成したものです。

まとめ

CLAUDE.mdは単なる設定ファイルではなく、AIとの仕事の進め方を書き記す場所です。ここまで、フォルダ階層の仕組み・CLAUDE.mdとSKILLの住み分け・増えたときの整理原則という3つの基礎を見てきました。次は、この基礎を実際にどう運用するかです。

次回：応用編

応用編では、階層ごとに実際どんな内容を書けばいいのかの具体例、ルールを“育てる”運用サイクル、そして複数ジャンルを1つの作業フォルダに同居させる私自身の実践構成を紹介します。