studioenough

CLAUDE.mdでプロジェクトのルールを教える

本記事はClaude Code CLI v2.1.150時点の情報に基づいています。公式ドキュメントの記載は最新版基準のため、手元の挙動と細部が異なる場合はclaude --versionで自分のバージョンを確認してください。

この記事でわかること

  • そもそも「Claude Code」が何をするツールなのか
  • プロジェクトのルールを教えるCLAUDE.mdというファイルの役割
  • Claude CodeがどのCLAUDE.mdを読み込むかの仕組み(読んでおけば「あれ、ルールが効いてない？」を自分で調査できるようになる)
  • 個人用のルールだけを別枠にするCLAUDE.local.mdの使い分け

読み終わると、自分のプロジェクトにCLAUDE.mdを置いて「毎回同じ説明をしなくても、Claudeが自動でルールを守ってくれる」状態を作れるようになります。

そもそもClaude Codeとは

は、AnthropicのAI「Claude」をの中から使うための公式ツールです。ChatGPTのようなチャット画面で会話するのとは違い、Claude Codeは実際にファイルを読んだり、書いたり、コマンドを実行したりしながら、頼んだ作業を代わりに進めてくれます。いわば「の中に住んでいる、手を動かせるアシスタント」です。

Claude Codeは(コマンドラインインターフェース)というタイプのソフトなので、マウスでアイコンをクリックするのではなく、claudeと打ち込んで起動します。起動してから終わるまでのひとまとまりの会話・作業を「」と呼びます。

「毎回同じ説明をするのが面倒」という問題

Claude Codeを使い始めると、すぐにこんな場面に出会います。

  • 「このプロジェクトではPHPのインデントは4スペース」
  • 「テストは必ずnpm run testで確認してからコミットして」
  • 「本番サーバーの設定ファイルは絶対に書き換えないで」

こうしたルールを、を始めるたびに文章で説明するのは現実的ではありません。しかも、口頭で説明したルールはそのセッションが終われば消えてしまい、次回また同じ説明を繰り返すことになります。そこで使うのがという名前のファイルです。プロジェクトのフォルダに置いておくだけで、Claude Codeがセッション開始時に自動で読み込み、それ以降その内容を踏まえて作業してくれます。一度書けば、以後起動するすべてのセッションに引き継がれる「恒久的なメモ」だとイメージすると理解しやすいです。

たとえば、次のようなCLAUDE.mdをプロジェクト直下に置いてみます。

# CLAUDE.md

## コーディング規約
- インデントはスペース2つ(タブは使わない)
- 変数名・関数名はキャメルケース(例: `getUserName`)

## やってはいけないこと
- `.env`ファイルの中身を表示・編集しない
- 本番用データベースへ直接書き込むコマンドを実行しない
- テストが通らない状態でコミットしない

これを置いておくだけで、以降Claude Codeにこのプロジェクトの作業を頼むたびに、上記のルールを踏まえて動いてくれるようになります。「インデントはスペース2つで」と毎回言わなくてよくなる、というのが一番わかりやすいメリットです。書く内容は自由なMarkdownなので、箇条書きに限らず、表や見出しを使って整理してもかまいません。

CLAUDE.mdはどこに置けばいいか

一番シンプルな疑問はこれです。「たくさんのプロジェクトを~/devのようなフォルダにまとめて置いていて、その都度違うをエディタで開いてClaude Codeを呼び出している場合、~/dev/CLAUDE.mdのような共通ルールファイルは読まれるのか？」

具体的に、こんなフォルダ構成を考えてみます。

~/dev/
├── CLAUDE.md              ← 全プロジェクト共通のルール
├── blog-app/
│   ├── CLAUDE.md          ← blog-app固有のルール
│   └── src/
│       └── components/
│           └── CLAUDE.md  ← componentsフォルダだけの細かいルール
└── shop-app/
    └── CLAUDE.md          ← shop-app固有のルール

~/dev/blog-app/src/componentsをエディタで開いてClaude Codeを起動した場合、~/dev/CLAUDE.md(一番上の共通ルール)は読まれるのでしょうか。結論は「読まれる」です。Claude Codeは(起動した場所)から上位ディレクトリへ再帰的にCLAUDE.mdを探す仕様になっています。公式ドキュメントには次のように書かれています。

Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files. This means if you run Claude Code in foo/bar/, it loads instructions from foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.

(日本語訳: Claude Codeは現在の作業ディレクトリからディレクトリツリーを遡りながら、通過する各ディレクトリでCLAUDE.mdとCLAUDE.local.mdファイルを確認することでCLAUDE.mdファイルを読み込む。つまりfoo/bar/でClaude Codeを実行した場合、foo/bar/CLAUDE.md・foo/CLAUDE.md、およびそれらと同じ場所にあるCLAUDE.local.mdファイルから指示を読み込む。) — code.claude.com/docs/en/memory

先ほどの例で言うと、~/dev/blog-app/src/componentsを起動場所にした場合、~/dev/blog-app/src/components→~/dev/blog-app/src→~/dev/blog-app→~/devと、起動場所から上へ順番にフォルダを辿りながらCLAUDE.mdを探し、見つかったものを全部読み込みます。この例では~/dev/blog-app/CLAUDE.mdと~/dev/CLAUDE.mdの2つが該当します。エディタでどこをルート(一番上の階層)にするかは、CLAUDE.mdが読まれるかどうかにはほとんど関係ありません。「共通ルールを上のフォルダに置いたのに、下のフォルダから開いたら読まれないのでは」と心配する必要はないということです。

複数見つかった時の順序

複数のCLAUDE.mdが見つかった場合、どちらかが上書きされて消えるわけではなく、すべて連結されて渡されます。ただし順序には意味があります。

All discovered files are concatenated into context rather than overriding each other. Across the directory tree, content is ordered from the filesystem root down to your working directory... instructions closer to where you launched Claude are read last.

(日本語訳: 発見された全てのファイルは、互いを上書きするのではなくコンテキストへ連結される。ディレクトリツリー全体にわたって、内容はファイルシステムのルートから作業ディレクトリへ向かう順序で並ぶ……Claudeを起動した場所に近い指示ほど、最後に読み込まれる。) — code.claude.com/docs/en/memory

先ほどの例だと、~/dev/CLAUDE.md(共通ルール)が先、~/dev/blog-app/CLAUDE.md(blog-app固有のルール)が後に読み込まれます。AIのモデルは一般に「後から読んだ指示」を優先しやすい傾向があるため、この順序は「起動地点に近いほど具体的なルールが強く効く」という直感とちょうど一致しています。

実際にルールが衝突するケースで考えてみます。共通ルールの~/dev/CLAUDE.mdに「インデントはスペース2つ」と書いてあっても、blog-app側の~/dev/blog-app/CLAUDE.mdに次のように書いておけば、

# CLAUDE.md (blog-app)

## このプロジェクトだけの例外
- インデントはタブを使う(社内の他プロジェクトとは逆なので注意)

後から読まれるblog-app側の指示が優先されやすくなります。全社共通のルールを上のフォルダに、プロジェクト固有の細かいルールを下のフォルダに置く、という置き方が自然に噛み合う設計になっています。

サブフォルダのCLAUDE.mdは「必要になった時だけ」読まれる

ここまでは「起動した場所より上のフォルダ」の話でした。逆に下のサブフォルダ(先ほどの例で言う~/dev/blog-app/src/components/CLAUDE.md)にあるCLAUDE.mdは、扱いが少し異なります。

Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.

(日本語訳: Claudeは現在の作業ディレクトリ配下のサブディレクトリにあるCLAUDE.md・CLAUDE.local.mdファイルも検出する。起動時に読み込む代わりに、Claudeがそのサブディレクトリ内のファイルを読んだ時点でコンテキストに含まれる。) — code.claude.com/docs/en/memory

つまり~/dev/blog-appを起動場所にした場合、~/dev/blog-app/src/components/CLAUDE.mdは起動した瞬間には読み込まれません。Claudeが実際にsrc/componentsフォルダの中のファイルを開いたタイミングで、初めて読み込まれます。「起動時に全部読み込む上位フォルダ」と「必要になった時だけ読み込むサブフォルダ」という非対称な構造です。この仕組みのおかげで、巨大なリポジトリの隅々にまで細かいCLAUDE.mdを置いても、起動時のコンテキストが無駄に膨らむことはありません。モノレポ(1つのリポジトリに複数プロジェクトが入っている構成)向けの公式ガイドでも同じ説明があります。

Claude Code loads every CLAUDE.md file from your working directory and every parent directory at launch, then loads each subdirectory's file on demand when it reads files there.

(日本語訳: Claude Codeは起動時に、作業ディレクトリとすべての親ディレクトリにあるCLAUDE.mdファイルを全て読み込み、その後各サブディレクトリのファイルは、そこにあるファイルを読んだ時点でオンデマンドに読み込む。) — code.claude.com/docs/en/large-codebases

個人用のルールだけを分けるCLAUDE.local.md

ここまでの例に何度か登場したCLAUDE.local.mdは、CLAUDE.mdと全く同じ場所・同じタイミングで読み込まれる、もう1つのメモリファイルです。違いは「誰のためのファイルか」という点にあります。CLAUDE.mdはチーム全員に共有する前提でリポジトリにコミットするのに対し、CLAUDE.local.mdは自分のPCだけに置いておく個人的なメモという位置づけで使われます。たとえば「自分はいつもデバッグ用に詳細ログを出したい」「自分のローカル環境だけAPIのモックサーバーを使っている」といった、チーム全員には関係のない個人的な事情を書くのに向いています。.gitignoreに追加してコミット対象から外しておけば、他のメンバーのCLAUDE.mdと混ざり合うことなく、自分のセッションにだけ静かに効き続けます。

本当に読み込まれているか確認する方法

「ルールを書いたはずなのに効いていない気がする」という時、推測で済ませず確認する方法が用意されています。セッション中に/contextというを実行すると、実際に読み込まれたファイルの一覧が表示されます。

To confirm which files loaded, run /context and check the list under Memory files.

(日本語訳: どのファイルが読み込まれたかを確認するには、/contextを実行し、Memory filesの一覧を確認する。) — code.claude.com/docs/en/memory

先ほどの例で言えば、~/dev/blog-appで起動して/contextを実行すると、Memory filesの欄に~/dev/CLAUDE.mdと~/dev/blog-app/CLAUDE.mdの2つが表示されているはずです。もし片方しか表示されていなければ、ファイルの置き場所やファイル名(CLAUDE.mdの綴りミスなど)を疑う、という具合に切り分けられます。「効いているはずなのに効かない」という時は、まずここを見るのが手早い確認方法です。

まとめ

CLAUDE.mdCLAUDE.local.md
想定する読者チーム全員(コミットする)自分だけ(.gitignore対象)
読み込み方向作業ディレクトリから上位へ再帰的に探索同左
上位ディレクトリの扱い起動時に全読み込み同左
サブディレクトリの扱いファイルを読んだ時にオンデマンド同左
複数見つかった場合上書きではなく連結。起動場所に近いものが後(＝優先されやすい)同左
確認手段/context実行 → Memory filesを見る同左

CLAUDE.mdは「プロジェクトのルールを一度書いておけば、あとはClaudeが自動で守ってくれる」ための一番手軽な入り口です。まずはプロジェクト直下に1個、簡単なものを置いてみるところから試してみてください。権限やコマンドの許可・禁止といった、もう少し技術的な設定は「settings.json」の記事で扱っています。

参考