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

解説！フォルダ階層別CLAUDE.mdの役割

2026年8月16日 ・ 約25分

Claude Codeを日常的に使っていると、「毎回同じ指示を繰り返している」「プロジェクトごとにルールを説明し直すのが面倒」と感じる場面が出てきます。この壁を越える鍵は、Claudeのフォルダ階層とCLAUDE.mdという仕組みを理解し、設計することにあります。この記事では、Claude Codeを効果的に使うための構造理解を、6つのTIPSに整理してお届けします。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ポイントは「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で実測データとともに掘り下げます）。

TIP3：階層別に書く内容を変える（実践編）

具体的なフォルダ構成の例を見てみます。私が実際に運用している構成を、簡略化して示します。

~/.claude/
├── CLAUDE.md              ← 個人の基本ルール（全プロジェクト共通）
└── rules/
    ├── development.md     ← 開発作業の上位ルール
    ├── writing.md          ← 文章作成の上位ルール
    └── tech/
        ├── README.md
        └── swift-ios.md    ← 技術別の詳細ルール

~/Work/
├── CLAUDE.md                     ← 作業フォルダ全体の索引
├── SillyTavern/
│   └── CLAUDE.md                 ← このジャンル共通のルール（拡張群のシンボリックリンク制約など）
├── AppDev/
│   ├── CLAUDE.md                 ← このジャンル共通のルール
│   └── chain-timer/
│       └── CLAUDE.md             ← 個別プロジェクトの固有設定
└── Blog/
    └── CLAUDE.md                 ← 執筆ルールと開発ルールを併用するジャンル

SillyTavernは、AIチャットツール向けに複数の拡張機能を自作しているジャンル名です。実際に比較してみると、この中間階層は全ジャンルが同じ厚みになるわけではありませんでした。拡張同士がシンボリックリンクで複雑に絡み合うSillyTavernのCLAUDE.mdは60行、プロジェクトがまだ1件しかないAppDevは19行、執筆と開発が同居するBlogは22行でした。Blogのように性質の異なる作業が一つのジャンルに同居する場合でも、「development.mdとwriting.mdの両方を併用する」と冒頭で明記するだけで内容自体は薄く保てます。最初から全ジャンルに同じ厚みを求めず、必要になったところから育てていけばよいということです。

ここでの失敗パターンとしてよく挙げられるのが、個人設定とプロジェクト固有情報の混在です。

グローバル設定にプロジェクト固有の情報（ディレクトリ構造やビルドコマンド等）を書かないでください。全プロジェクトに影響します。 ―― nogataka、前掲記事

逆の失敗もあります。すべてを一箇所に書き込み続けた結果、CLAUDE.mdが2,000行近くまで肥大化し、どんな小さな作業でも毎セッション全文を読み込ませていた、という実測記録があります。そこから3層構造（エントリーポイントとしてのCLAUDE.md／日常的に効かせるrules/／呼び出し時だけ読み込むskills/）へ分割した結果は次のとおりです。

状態 起動時に読み込まれるトークン数
分割前（全部読み込んだ場合） 114,847
分割後（CLAUDE.md＋rules/のみ） 19,232

出典：pepabo「CLAUDE.mdの肥大化を3層構造で83%軽くした」

約八割の削減です。「呼び出したときだけ使うもの」を分離するだけで、これだけの差が生まれます。表にまとめると、各階層に書くべき内容の判断基準は次のようになります。

階層 書くべきこと 書くべきでないこと
個人の基本ルール 口調、確認基準、報告スタイル 特定プロジェクトの技術詳細
中間（ジャンル共通） そのジャンルの技術的な制約、命名規約 個別プロジェクトの起動コマンド
プロジェクト固有 ビルド・起動コマンド、そのプロジェクト特有の注意点 全プロジェクトに影響する一般ルール

階層ごとの記述例

実際にどんな粒度で書き分けるのか、実例を示します。

個人の基本ルール（~/.claude/CLAUDE.md）は、進め方の姿勢を書きます。

## 基本姿勢
- 結論を先に述べる。前置きは最小限にする
- 三手順以上の作業は着手前に計画を提示する
- 不可逆な操作（削除・公開等）は必ず事前確認する

中間階層（SillyTavern/CLAUDE.md）は、そのジャンル固有の落とし穴を書きます。

## シンボリックリンク制約（最重要）
拡張群は、外部ツールの `extensions/third-party/<拡張名>` へ
シンボリックリンクされた実体です。ディレクトリを移動・改名する際は、
リンク先も必ず張り替えてください。

一方、プロジェクト固有のCLAUDE.md（chain-timer/CLAUDE.md）は、そのプロジェクトでしか通用しない具体情報を書きます。

# chain-timer
iOSタイマーアプリ（Swift / SwiftUI）。

## テスト実行
\`\`\`
xcodebuild test -scheme <Scheme> -destination 'platform=iOS Simulator,name=iPhone 16'
\`\`\`

個人の基本ルールをプロジェクト固有に書くと全プロジェクトが引きずられ、逆にプロジェクト固有の詳細を個人の基本ルールに書くと他プロジェクトでは意味を持たないノイズになります。「この内容は、他のプロジェクトを触っているときにも読まれて困らないか」が、階層を判断する簡便な基準になります。

階層×ファイル種類で見るコストの実態

ここまでは「階層」を軸に見てきましたが、実際には同じ階層内でも「ファイルの種類」によって読み込まれ方が変わります。公式ドキュメントを確認すると、次のように整理できました。

ファイル種類 読み込まれるタイミング
CLAUDE.md（作業ディレクトリの祖先にある場合） 起動時に全文
CLAUDE.md（作業ディレクトリより下の階層にある場合） そのフォルダのファイルを実際に開いた時だけ
rules（パス指定なし） CLAUDE.mdと同じく起動時に全文（無条件）
rules（パス指定あり） 該当パターンのファイルを開いた時だけ
README.md等の索引ファイル rulesフォルダの中にある限り、本文と同じ扱いで毎回全文
skill 呼び出された時だけ

出典：How Claude remembers your project

意外だったのは、人間向けの「目次」のつもりで置いたREADME.mdのようなファイルも、rulesフォルダの中にある限り毎回本文と同じコストで読み込まれるという点です。索引だから軽い、という思い込みは誤りでした。

もう一つの発見は、公式に名前が付いたスコープは実は「組織」「ユーザー」「プロジェクト」「ローカル」の4つしかなく、TIP1で紹介した「Work全体の索引」や「ジャンル共通のルール」という中間階層は、公式仕様というより「作業ディレクトリの祖先にあるCLAUDE.mdはすべて連結される」という仕組みを活用した、利用者側の運用の工夫だったという点です。だからこそ階層はいくつ増やしても壊れません。増やしすぎて読み込みコストが気になったときだけ、サブフォルダ化やskillへの切り出しを検討すればよいということです。

発展編：development.md・writing.mdをジャンルフォルダへ移すべきか

ここまでの設計に、こんな疑問が浮かぶかもしれません。「development.mdは開発作業のときしか使わないし、writing.mdは文章作成のときしか使わない。それなら~/.claude/rules/に置かず、開発ジャンルのCLAUDE.mdや執筆ジャンルのCLAUDE.mdに直接書けばいいのでは？」

結論から言うと、答えはルールによって変わります。 判断の分かれ目は「そのルールを使うジャンルが1つだけか、複数にまたがるか」です。

複数ジャンルにまたがるルール（development.mdのようなケース）：私の環境では、development.mdはSillyTavern・AppDev・Blog内のsite/という3つの異なるジャンルフォルダから参照されています。これをどこか1つのジャンルフォルダ（たとえばAppDev）へ物理的に移してしまうと、CLAUDE.mdは「作業ディレクトリの祖先にあるファイルだけ」が読み込まれる仕組みのため、残り2ジャンルで作業しているときはこのルールが一切効かなくなります。他のジャンルにも同じ内容をコピーすれば動きますが、それはTIP4で見る「同じルールの重複」そのものであり、更新のたびに複数箇所を直しに行く手間が発生します。

単一ジャンルでしか使わないルール（writing.mdのようなケース）：現時点で文章作成を行っているジャンルは1つだけです。この場合は移動しても重複の問題は起きません。ただし、それでもおすすめは物理的な移動ではなく、paths:（TIP2で紹介したもの）をルール自体に追加し、対象ジャンルのパスパターンを指定する方法です。

---
paths:
  - "**/Blog/about-work/**"
---

# 文章作成 指示書
...

こうすればファイルの置き場所は~/.claude/rules/のまま変えずに、そのジャンル以外で作業しているときはこのルールが読み込まれなくなります。ファイルを物理的に移動する場合と同じ効果（無関係な作業での読み込みコスト削減）を、一元管理を崩さずに得られるわけです。複数ジャンルにまたがるルールも、考え方は同じで、paths:に複数パターンを並べれば対応できます。

---
paths:
  - "**/SillyTavern/**"
  - "**/AppDev/**"
  - "**/Blog/site/**"
---

「物理的にどこに置くか」ではなく「paths:で読み込み条件を絞る」ほうが、複数ジャンルにまたがるルールでも重複を生まずに済む、というのがこのケースでの結論です。私自身もまだ実際には設定を変えていませんが、次に無関係な作業でのコンテキスト消費が気になったタイミングで試してみるつもりです。

実はこの2つの選び方、Anthropic公式ドキュメントでもほぼ同じ形に整理されていました。

方式 ファイルの置き場所 向いているケース
ジャンル別のCLAUDE.md そのジャンルフォルダの中 ジャンルの担当者が自分の流儀を管理し、コードと一緒にバージョン管理したい場合
paths:指定のrules ~/.claude/rules/（一元管理） 全部を一箇所にまとめたい場合、または同じルールが複数の離れたパスに適用される場合

出典：Set up Claude Code in a monorepo or large codebase

development.mdはまさに「同じルールが複数の離れたパスに適用される場合」に当てはまるため、公式の整理に照らしてもpaths:側が理にかなっていることになります。

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

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

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

もう一つは、そもそも何を書き残すかの判断基準です。この点は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）

参考までに、この記事でここまで例に挙げてきた私の環境のdevelopment.mdを実測すると223行でした。公式の目安（200行未満）をわずかに超えており、私自身「体感的に大きい」と感じていた印象は、実測でも裏付けられた形です。棚卸しの余地がありそうです。

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

rules/はファイルを分けても総量は変わりません。ただし、ドメイン別にファイルを分けることで追記時の判断コストは下がります。 ―― pepabo、前掲記事

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

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

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

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

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

TIP5：“自動で育つ”運用サイクルの回し方

CLAUDE.mdは最初から完成させる必要はありません。

CLAUDE.mdは最初から完璧に書く必要はありません。使いながら育てるものです。 ―― pekopugu、前掲記事

同記事では、追記のタイミングを次の3つに整理しています。

  1. 「毎回同じ注意をしてしまう」と気づいたとき
  2. Claude Codeが意図と違う動きをしたとき
  3. 新しい規約を決めたとき

この3つは言い換えると、「フィードバックが発生した瞬間に、ルールファイルへ即座に書き戻す」という運用サイクルです。個々の作業で得た気づきをその場限りで終わらせず、該当する階層のファイルに追記していくことで、プロジェクトに最適化された指示書が結果的に育っていきます。加えて、次の指摘も実践的です。

「禁止事項」セクションは最初から充実させておくと効果的です。一度でも起きると困る操作は早めに明記しておきましょう。 ―― pekopugu、前掲記事

育てる順序としては、まず「絶対に起きてはいけないこと」を先に固め、そのうえで「よく繰り返す指示」を都度拾い上げていく、という順番が理にかなっています。運用が回り始めると、ルールファイルはただの設定ではなく、これまでのやり取りから学んだことの記録そのものになっていきます。

TIP6：実践編――一つのWorkフォルダに複数ジャンルを同居させる

最後に、ここまでの階層設計を実際にどう運用しているかを紹介します。私の場合、一つの大きなWorkフォルダの中に、SillyTavern・AppDev・Blogといった「プロジェクト群（ジャンル）」フォルダを作り、その下に個々のプロジェクトを配置しています。各階層には、TIP3で見た通りその階層にふさわしいルールを書き、プロジェクトを進めながら気づいたことをその都度、該当する階層のCLAUDE.mdへ書き戻しています（TIP5の運用サイクルそのものです）。

メリット：この構成の一番の利点は、他プロジェクトのノウハウをWorkフォルダ全体で共有・参照しやすいことです。すべてのプロジェクトが一つのフォルダの下に集約されているため、あるプロジェクトで得た知見（たとえば「シンボリックリンクを扱う際の注意点」）を、ジャンルをまたいで別プロジェクトのCLAUDE.mdからも参照しやすくなります。Work全体の索引となるCLAUDE.mdを起点に、俯瞰しながら各プロジェクトへたどり着ける構造にもなっています。

デメリット：一方で、気をつけるべき点もいくつかあります。

  • Workフォルダ直下の索引（Work/CLAUDE.md）は、プロジェクトが増えるほど肥大化しがちです。索引は一覧に徹し、詳細は各ジャンル・各プロジェクトのCLAUDE.mdに任せる意識が必要です
  • 新しいプロジェクトをどのジャンルに置くか迷う場面があります。既存のどのジャンルにも当てはまらない場合は、無理に押し込めず、新しいジャンルフォルダを切ることをためらわないほうがよいと感じています
  • TIP3で見た通り、作業ディレクトリより下の階層にあるCLAUDE.mdはオンデマンドでしか読み込まれません。つまりWorkフォルダ直下で作業を始めた場合、個別プロジェクトのCLAUDE.mdはまだ読み込まれていない、という状態が起こりえます。深い階層の設定を確実に効かせたいときは、そのプロジェクトのフォルダの中で作業を始めるようにしています

一つのWorkフォルダにすべてを集約するか、プロジェクトごとに独立させるかは好みが分かれるところだと思いますが、複数プロジェクトを横断しながら開発する機会が多い方には、この構成は参考になるはずです。

まとめ

CLAUDE.mdは単なる設定ファイルではなく、AIとの仕事の進め方を書き記す場所です。つまり、階層を分けて書く内容を整理し、増えたらサブフォルダ化し、気づきをその都度書き戻す。この3つを回し続けることが、Claude Codeを長く使いこなすための土台になります。一つの大きな作業フォルダの下にジャンルとプロジェクトを積み重ねていく構成にすれば、プロジェクトを横断した知見の共有もしやすくなります。もちろんこれは一つの型であり、プロジェクトの規模や好みによって最適な分け方は変わります。あくまで一つの参考として、ご自身の環境に合わせて調整してみてください。

次回予告

次回は、会話をまたいで記憶を引き継ぐ仕組み――いわゆる「メモリ」について書く予定です。CLAUDE.mdが「常に読み込まれる指示書」だとすれば、メモリは「必要なときに思い出す記録」です。この二つがどう役割分担しているのかを、次の記事で掘り下げます。