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

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

2026年8月17日 ・ 約15分

前回の基礎編では、Claude Codeのフォルダ階層とCLAUDE.mdの仕組み、そして増えたときの整理原則を見てきました。この応用編では、その基礎を実際の運用にどう落とし込むかを、3つのTIPSで具体的に見ていきます。

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

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

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

~/Work/
├── CLAUDE.md                     ← 作業フォルダ全体の索引
├── AppDev/
│   ├── CLAUDE.md                 ← このジャンル共通のルール
│   └── chain-timer/
│       └── CLAUDE.md             ← 個別プロジェクトの固有設定
└── Blog/
    └── CLAUDE.md                 ← 執筆ルールと開発ルールを併用するジャンル

実際に比較してみると、プロジェクトがまだ1件しかないAppDevは19行、執筆と開発が同居するBlogは22行と、扱う内容の複雑さに応じて自然と厚みが変わっています。Blogのように性質の異なる作業が一つのジャンルに同居する場合でも、「development.mdとwriting.mdの両方を併用する」と冒頭で明記するだけで内容自体は薄く保てます。最初から全ジャンルに同じ厚みを求めず、必要になったところから育てていけばよいということです。

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

グローバル設定にプロジェクト固有の情報（ディレクトリ構造やビルドコマンド等）を書かないでください。全プロジェクトに影響します。 ―― nogataka「CLAUDE.mdを設計するとClaude Codeの生産性が別物になる」

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

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

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

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

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

階層ごとの記述例

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

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

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

中間階層（ジャンル共通のCLAUDE.md）は、そのジャンル特有の技術的な制約を書きます。たとえば次のような形です。

## このジャンル共通の制約
このジャンルのプロジェクトは全て同じ外部ライブラリに依存しています。
更新する際は、ジャンル内の全プロジェクトで動作確認してから反映してください。

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

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

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

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

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

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

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

# 文章作成 指示書
...

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

---
paths:
  - "**/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:側が理にかなっていることになります。

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

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

CLAUDE.mdは最初から完璧に書く必要はありません。使いながら育てるものです。 ―― pekopugu「CLAUDE.mdでプロジェクトを育てる」

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

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

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

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

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

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

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

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

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

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

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

まとめ

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

次回予告

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