Claude Code CLAUDE.md AI エージェント ベストプラクティス

Claude CodeのCLAUDE.md書き方ガイド — 階層と反映範囲を実機検証でまとめた

2026-04-14
目次

前回のClaude Code入門ではインストールから初回実行までを扱いました。本格的に使い始めると、誰もがぶつかるのが「CLAUDE.mdに指示を書いたのに守ってくれない」問題です。筆者もチームのコーディング規約をCLAUDE.mdに書き並べたところ、半分程度しか守られず、「このファイルは本当に読まれているのか」と疑うところから始まりました。

この問題を突き詰めると、そもそもCLAUDE.mdがどの範囲まで反映されるのかが曖昧だと気付きます。プロジェクトルートに置いたファイルがメインセッションで効くことは、多くの利用者が知っています。しかし、サブエージェントには効くのか。git worktree で並列起動したセッションでは。claude --agent でカスタムエージェントを起動したときは。公式ドキュメントには断片的にしか書かれておらず、Web上の情報も食い違っていました。

そこで、各階層のCLAUDE.md系ファイルにユニークなマーカー文字列を埋め込み、起動モードごとに「どのマーカーが見えているか」を尋ねるという力技の実機検証を行いました。この記事では、検証結果のマトリクスと、そこから導かれる「CLAUDE.mdに何を書くべきか」の指針をまとめます。扱うトピックは次のとおりです。

  • CLAUDE.mdの配置場所と階層構造
  • 実機で確認した反映範囲マトリクス（サブエージェント・ワークツリー・--agent 含む）
  • 書くべき内容・書くべきでない内容
  • .claude/rules/ や Skills との使い分け

公式ドキュメントの焼き直しではなく、手元で動かして分かったことを中心に書いていきます。

CLAUDE.mdとは — Claude Codeの設定ファイル

CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込む設定ファイルです。Markdown形式で指示や文脈を書いておくと、その内容がLLMに渡るコンテキストに含まれ、ツールが挙動の指針として参照します。

ここで押さえておきたい事実が一つあります。CLAUDE.mdはシステムプロンプトではなく、ユーザーメッセージとして注入されるという点です。Claude Codeの仕様上、システムプロンプトはツールの動作定義や安全ポリシーに使われ、ユーザー側のCLAUDE.mdは「ユーザーからの追加指示」として扱われます。

この違いは、日々の挙動をうまく説明してくれます。

  • 100%遵守されるわけではない：公式ドキュメントでも「strict compliance is not guaranteed」と明記されており、強く指示しても破られることがある
  • 会話中の指示で上書きできる：ユーザーが対話中に「今回はこれを無視して」と言えば、通常はそちらが優先される
  • 長すぎると埋もれる：会話履歴の先頭に長大なテキストが積まれると、後半のメッセージに意識が奪われる

つまりCLAUDE.mdは「法律」ではなく「強めのお願い」です。この前提で書き方を設計すると、期待値がずれません。

CLAUDE.mdの配置場所と階層構造

Claude Codeは起動時に、複数の場所からCLAUDE.md系ファイルを探して読み込みます。主な配置場所は次のとおりです。

レベル配置場所用途Git管理
管理者ポリシー/etc/claude-code/CLAUDE.md（Linux/WSL）、/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）、C:\Program Files\ClaudeCode\CLAUDE.md（Windows）組織全体のポリシーN/A
ユーザーグローバル~/.claude/CLAUDE.md個人の全プロジェクト共通対象外
ユーザールール~/.claude/rules/*.md個人のルール（関心事別）対象外
プロジェクト./CLAUDE.md または ./.claude/CLAUDE.mdチーム共有対象
プロジェクトルール./.claude/rules/*.mdモジュール化されたルール対象
プロジェクトローカル./CLAUDE.local.md個人のプロジェクト固有設定対象外
サブディレクトリ./subdir/CLAUDE.mdサブディレクトリ固有対象
自動メモリ~/.claude/projects/<project>/memory/（MEMORY.md ほか）Claudeによる自動記憶（v2.1.59以降）対象外

重要なのは、これらが上書きではなく加算的に結合される点です。ユーザーグローバルの設定とプロジェクト設定は両方とも読み込まれ、両方の内容がコンテキストに入ります。「より具体的な設定が優先される」という原則もありますが、基本は共存すると考えて問題ありません。

CLAUDE.mdの反映範囲を実機検証した

ここからがこの記事の本題です。「どの階層が、どの起動モードで効くのか」は、Webで調べても確信が持てなかったため、実際に計測してみました。

検証のアイデア

各CLAUDE.md系ファイルに、ユニークな「マーカー文字列」を埋め込みます。普通のドキュメントには絶対に出現しない、ランダムな英数字の列です。そして各起動モードで「今、あなたのコンテキストに見えているマーカーを列挙してください」と尋ねます。

この方式のポイントは次の2点です。

  • 見えているかどうかを直接確認できる：「遵守されているか」ではなく「コンテキストに載っているか」という一次情報が取れる
  • 偽マーカーで推測を排除できる：リストに存在しないマーカーを混ぜておき、それを回答に含めたら「推測している」と判定できる

擬似プロジェクトのセットアップ

検証用のディレクトリ構造は次のように組みました。

ディレクトリ構造
~/.claude/test-claude-md-scope/           # 擬似プロジェクトルート
  CLAUDE.md                               # MARKER_PROJECT_ROOT_2H5J7
  CLAUDE.local.md                         # MARKER_LOCAL_MD_6T3N8
  .claude/
    rules/
      test-marker-rule.md                 # MARKER_PROJECT_RULE_9W1Q5
    agents/
      test-agent.md                       # MARKER_CUSTOM_AGENT_5F7B3
  subdir/
    CLAUDE.md                             # MARKER_SUBDIR_MD_3R6V4
    dummy.txt


~/.claude/CLAUDE.md                       # MARKER_GLOBAL_CLAUDE_7X9K2（追記）
~/.claude/rules/test-scope-marker.md      # MARKER_USER_RULE_4M8P1

各ファイルにはマーカー文字列1つだけを書き、他の内容は入れません。これで「マーカーが見えている＝そのファイルが読み込まれている」とみなせます。

検証コマンド

メインセッションでの確認は次のコマンドで行いました。

marker-check.sh
cd ~/.claude/test-claude-md-scope && echo '以下のマーカー文字列のうち、あなたが現在のコンテキストで認識しているものをすべて列挙してください。推測しないでください。


- MARKER_GLOBAL_CLAUDE_7X9K2
- MARKER_USER_RULE_4M8P1
- MARKER_PROJECT_ROOT_2H5J7
- MARKER_LOCAL_MD_6T3N8
- MARKER_PROJECT_RULE_9W1Q5
- MARKER_SUBDIR_MD_3R6V4
- MARKER_FAKE_DECOY_0A0A0' | claude -p --output-format json

他の起動モードも同じ質問を投げるだけです。サブエージェントはAgentツール経由、ワークツリーは git worktree add で別ディレクトリに展開してから起動、--agent は事前に定義したエージェント名を指定、--bare は最小モードで起動しました。

偽マーカーで信頼性を担保する

MARKER_FAKE_DECOY_0A0A0 はどのファイルにも書いていない偽マーカーです。これが回答に含まれたら、モデルが「たぶん見えているはず」と推測で答えている証拠になります。

結果として、全検証を通じて偽マーカーは一度も検出されませんでした。つまりモデルは自分のコンテキストに本当に載っているマーカーだけを返しており、以降のマトリクスは信頼できる測定結果とみなせます。

なお、マーカー埋め込みではなく公式の InstructionsLoaded フックを使えば、どのCLAUDE.md系ファイルが読み込まれたかを直接ログに残せます。本格的にデバッグしたい場合はこちらの方法が推奨ですが、今回は「起動モード横断で同じ条件で比較する」目的に合わせて、力技のマーカー方式を採用しました。

検証結果マトリクス

6つの起動コンテキスト × 6種類のファイルで、見えているかどうかを実測した結果が次の表です。

コンテキスト~/.claude/CLAUDE.mdプロジェクトCLAUDE.md.claude/rules/~/.claude/rules/CLAUDE.local.mdサブディレクトリCLAUDE.md
メインセッション（ルート）○○○○○×
メインセッション（subdir cwd）○○○○○○
サブエージェント（Agentツール）○○○○○×
ワークツリーエージェント○○○○○×
claude --agent○○○○○×
claude -p --bare××××××

自動メモリ（MEMORY.md）は今回の検証対象外です。仕様上はユーザーホーム配下に保存されるため、プロジェクトのスコープとは独立して扱われます。

主要な発見

このマトリクスから、Web情報では曖昧だった点がいくつもはっきりしました。

  1. サブエージェント・ワークツリーも全層を継承する：Agentツール経由のサブエージェントや、git worktree で並列起動したセッションでも、デフォルト設定ではユーザーグローバルからプロジェクトルール、CLAUDE.local.md まで通常どおり読み込まれます。Web上で「サブエージェントには反映されない」といった説明を見かけましたが、少なくとも現在の実装では反映されます。ただしサブエージェント定義の memory フロントマター（user / project / local）でスコープを絞ることは可能です。サブエージェントがどのようにコンテキストを分離しているかは、opencodeのソースから読み解くAIエージェント処理フローで別のOSS実装を題材に掘り下げています。
  2. サブディレクトリのCLAUDE.mdはcwdベース：プロジェクトルートで起動するとサブディレクトリの CLAUDE.md は読まれませんが、cd subdir してから起動すると読まれます。Claude Codeはcwdから上方向にスキャンしており、subdir 側にcwdを置くとそこから上（subdir/CLAUDE.md とプロジェクトルートの CLAUDE.md）をすべて拾います。
  3. --agent でもCLAUDE.mdは通常どおり反映される：カスタムエージェントはエージェント固有のシステムプロンプトを持ちますが、CLAUDE.mdは別経路で注入されるため引き続き効きます。「カスタムエージェントにはプロジェクト文脈が渡らないのでは」という懸念は杞憂でした。
  4. --bare モードは全スキップ：最小構成で起動する --bare は認証キーチェーンの読み込みまでスキップするため、そもそも通常のログインができません。当然CLAUDE.mdも一切読まれません。スクリプトから軽く呼ぶ用途に絞ったモードなので、通常利用では意識しなくてよいでしょう。

実用上の結論はシンプルです。--bare 以外のあらゆる起動モードで、CLAUDE.md系ファイルは素直に反映されると考えて設計して構いません。

CLAUDE.mdに書くべき内容

反映範囲が分かったら、次は「何を書くか」です。筆者が実務で効果を感じたセクションを、推奨順に並べます。

  1. プロジェクト概要（1〜2文）：何を作っているプロジェクトなのか。最初の一文がコンテキスト全体の解釈方向を決めるので、端的に書く
  2. 開発コマンド：npm run dev npm run test など、よく使うコマンドをコピペできる形で並べる。Claudeはコマンド名を推測するより、ここを読んだほうが正確
  3. コードスタイル（デフォルトと異なるもののみ）：言語標準と同じものは書かない。「当プロジェクトではセミコロンを省略する」など、逸脱している点だけ書く
  4. アーキテクチャ（ディレクトリ構造）：src/components/ と src/features/ の使い分け、レイヤー境界など、ディレクトリを見ても分からない意図を書く
  5. テスト指示：テストコマンド、テスト対象から外すもの、スナップショットの扱いなど
  6. ワークフロー・Git規約：ブランチ命名、コミットメッセージ、PRのベースブランチ
  7. 落とし穴・Gotchas：「一見問題なさそうだが実は動かないパターン」。ここが一番価値が高い
  8. DO / DONT リスト：短いDO/DONTの箇条書きは遵守率が高い
  9. 環境変数・開発環境の癖：ANTHROPIC_API_KEY の扱いなど、罠になりやすい環境依存の項目
  10. 用語・ドメインコンテキスト：プロジェクト固有の略語、業務用語

このサイトのCLAUDE.mdも、だいたいこの順序で構成しています。冒頭にプロジェクト概要、次に開発コマンド、その後にアーキテクチャとブランチ運用を置き、最後に注意事項を並べるレイアウトです。

CLAUDE.mdに書くべきでない内容（アンチパターン）

逆に、書いても効かない、あるいは邪魔になる内容もあります。

  • 200行を超える長さ：長くなればなるほど遵守率が下がる。特に後半は埋もれやすい
  • コードスニペットの直接埋め込み：コードはソースに置くべきで、CLAUDE.mdに貼るとコンテキストを圧迫する
  • 「きれいなコードを書く」など自明な指示：モデルがすでに知っている一般論はノイズにしかならない
  • 「〜しないでください」という否定形中心：LLMは否定より肯定に強い。「どうしてほしいか」をポジティブに書く
  • リンターやフォーマッターで対応できるルール：機械的に矯正できるものはツールに任せる
  • 機密情報：APIキー、社内URL、顧客名などは絶対に書かない。CLAUDE.mdはGit管理されるケースが多いため特に危険。secretlintでシークレット漏洩を防ぐ ような仕組みと併用する

筆者が最初に書いたCLAUDE.mdは300行を超えており、遵守率は目に見えて低いものでした。容赦なく削って150行まで圧縮したら、かえって指示が通るようになった経験があります。短いCLAUDE.mdのほうがよく効くのは覚えておいて損のないヒューリスティクスです。

CLAUDE.mdと.claude/rules・Skillsの使い分け

プロジェクトが大きくなると、CLAUDE.md 1枚では収まらなくなります。Claude Codeには他にも、.claude/rules/ や .claude/skills/ といった仕組みがあり、それぞれ役割が違います。

CLAUDE.md.claude/rules/.claude/skills/
用途プロジェクト全体のコンテキスト関心事別のルール再利用可能なワークフロー
読み込み毎セッション常時条件なし：常時 / 条件あり：マッチ時オンデマンド（明示呼び出し）
代表例概要・コマンド・アーキテクチャ言語別スタイル・テスト規約コミット・レビュー・デプロイ手順
分割単位1ファイル関心事ごとタスクごと

ざっくりした使い分けの指針は次のとおりです。

  • CLAUDE.md：どのタスクでも常に必要な「プロジェクトの顔」だけを書く。概要・コマンド・ディレクトリ構成・最重要ルール
  • .claude/rules/：言語別（TypeScript、Markdown）、関心事別（Git運用、テスト規約）に分割する。YAMLの paths フロントマターで特定ファイル種別にだけ適用するルールも書ける
  • .claude/skills/：「コミットする」「PRを作る」など、明示的に起動したいワークフローを1つのファイルにまとめる

実務で運用してみた感覚としては、「CLAUDE.mdが150行を超えそうになったら .claude/rules/ に切り出す」という閾値が使いやすいです。CLAUDE.mdはプロジェクト全体の地図、rulesは地図に書ききれない詳細、という住み分けになります。

モノレポで他チームのCLAUDE.mdまで読み込まれてしまう場合は、settings.json の claudeMdExcludes でパターン指定して除外できます。「読み込まない」を積極的に設計する手段として覚えておくと、肥大化したリポジトリでも快適に動かせます。

CLAUDE.md運用のコツとベストプラクティス

CLAUDE.mdは書いて終わりではなく、育てるものです。運用していて効いたプラクティスを紹介します。

間違えるたびに追記する（Boris Cherny方式）

Claude Codeの作者Boris Chernyが勧めているのが、「Claudeが間違えたら、その場で『この内容をCLAUDE.mdに追記して』と頼む」運用です。Claudeは自分向けのルールを書くのが得意で、任せておくと適切な粒度で追記してくれます。これを繰り返すと、自分のプロジェクトで間違えやすいポイントだけが蓄積されたCLAUDE.mdが育ちます。

/init は起点として使う

/init スラッシュコマンドはプロジェクトをスキャンしてCLAUDE.mdのたたき台を生成してくれます。便利ではありますが、生成結果は冗長で自明な内容が多いので、必ず読み直して半分以下に削ることを前提にしてください。自動生成のたたき台に人手の精査を重ねる、という使い方がちょうどよいです。

強い言語で書く

「Prefer async/await」よりも「MUST use async/await, NEVER use .then()」のほうが遵守率が明確に上がります。重要なルールは、強い英単語（MUST、NEVER、REQUIRED）で書くか、日本語なら「必ず」「禁止」のような語を使うと効きます。口調を迷ったら強めに書くのがコツです。

200行以下を維持する

経験則として、200行を超えたら分割のサインです。.claude/rules/ か Skills に移して、CLAUDE.md本体はプロジェクトの目次のような役割に戻します。短く保つこと自体がメンテナンスの動機になるので、行数制限は自分に課しておくと運用が続きます。

@import で外部ファイルを取り込む

CLAUDE.md内で @path/to/file と書くと、そのファイルの内容がインポートされます。最大5階層までネスト可能で、@README.md や @docs/architecture.md のように既存ドキュメントを流用できます。他のAIエージェント用の AGENTS.md がある場合は @AGENTS.md で取り込めば、1箇所をメンテすれば両方で効くようになります。CLAUDE.md本体を短く保ちつつ、詳細は別ファイルに逃がしたいときに便利です。

まとめ

  • CLAUDE.mdはシステムプロンプトではなくユーザーメッセージとして注入される「強めのお願い」
  • ユーザーグローバル、プロジェクト、.claude/rules/、CLAUDE.local.md、サブディレクトリなど複数の階層が加算的に結合される
  • 実機検証の結果、--bare 以外のほぼすべての起動モードで全階層が反映される（サブエージェント・ワークツリー・--agent 含む）
  • サブディレクトリの CLAUDE.md だけはcwdベースで、起動時のディレクトリに注意が必要
  • 書くべきはプロジェクト概要・コマンド・アーキテクチャ・落とし穴。自明な指示や長大なスニペットは逆効果
  • 200行を超えたら .claude/rules/ や Skills に切り出すのがちょうどよい分割閾値

次回予告

次回はClaude Codeの許可モードを扱います。デフォルトの確認モード、--dangerously-skip-permissions、allow/deny/ask の設定、Skillsから呼ばれたときの権限継承など、安全性とスピードのトレードオフをどう設計するかを整理する予定です。CLAUDE.mdで「どう振る舞ってほしいか」を決めたら、次は「どこまで任せるか」の話になります。

ヒヨリヒヨリ

CLAUDE.mdはね、システムプロンプトじゃなくて「強めのお願い」として効くファイルなんだよ！実機で測ってみたら、サブエージェントもワークツリーも --agent も、全部ちゃんと読んでくれてるって分かったんだ。だから「うちのサブエージェントに効かないかも」って心配は、ほとんどの場合いらないよ！書き方のコツは短く・具体的に・強い言葉での3つ。まずは自分のCLAUDE.mdを開いて、200行を超えてたら半分に削ってみよう！Claude Code自体のおさらいがしたい人はClaude Code入門も見てね。さあ、あたしと一緒に試してみよう！