Claude CodeのCLAUDE.md書き方｜配置場所・読み込み順・運用手順

Claude CodeのCLAUDE.mdは、プロジェクトや個人のワークフロー、組織全体に対してClaude Codeへ渡す永続的な指示を書き込むMarkdownファイルです。Anthropic公式ドキュメントによれば、配置場所は管理ポリシー・ユーザー・プロジェクト・ローカルの4段階に分かれており、広いスコープから狭いスコープへ向かって読み込み順が決まっています。結論から言うと、まずプロジェクト直下にCLAUDE.mdを1つ置き、ビルドコマンドや規約など「毎回のセッションで守ってほしい事実」だけを200行以内にまとめる、これが公式の推奨に沿った、つまずきにくい始め方です。

この記事では、CLAUDE.mdファイル自体の書き方・配置場所・読み込まれる順番・記載すべき項目と避けるべき項目・チーム運用・肥大化したときの分割方法を、公式ページの記述に基づいて解説します。hooksやサブエージェント、MCPといった周辺機能の詳しい設定手順は既存記事に譲り、本記事ではCLAUDE.mdそのものに絞ります。Claude Code使い方の基礎をまだ読んでいない場合は、先にそちらでインストールと基本機能を確認しておくと理解がスムーズです。

CLAUDE.mdとは何か

CLAUDE.mdとは、プロジェクトや個人のワークフロー、組織全体に対してClaudeに永続的な指示を与えるために書くMarkdown形式のファイルのことです。

公式ドキュメントは「CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session.」と説明しています。同ページによれば、プレーンテキストで書いたCLAUDE.mdは毎回のセッション開始時に読み込まれ、会話の外側で永続する指示として機能します。

Claude Codeにはもう1つ、Claudeが自分で書き足す「自動メモリ」という仕組みもあります。CLAUDE.mdはユーザーが書く指示とルール、自動メモリはClaudeが学習した内容とパターンという役割分担です。両者の違いを整理すると次の表のようになります。

公式ページは「Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration.」とも述べています。CLAUDE.mdも自動メモリも「文脈」として渡されるだけで、強制設定ではありません。Anthropic公式ドキュメントは、Claudeの判断に関わらず行動をブロックしたい場合はCLAUDE.mdではなくPreToolUseフックを使うよう案内しています。フックの具体的な書き方は後述の「書くべきでない内容」の章でリンクを紹介します。

CLAUDE.mdの配置場所は4種類ある

CLAUDE.mdの配置場所とは、管理ポリシー・ユーザー・プロジェクト・ローカルという4段階のスコープに沿って、それぞれ異なる目的でファイルを置ける場所のことです。

公式ドキュメントの「Choose where to put CLAUDE.md files」の章は、4つの置き場所を読み込み順(広いスコープから狭いスコープへ)で一覧にしています。具体的なパスと用途は下表の通りです。

管理ポリシーはIT/DevOpsが配布する組織共通ルールで、企業のコーディング標準やセキュリティポリシーに使われます。ユーザー指示の~/.claude/CLAUDE.mdは自分の全プロジェクトに効く個人設定、プロジェクト指示の./CLAUDE.mdまたは./.claude/CLAUDE.mdはソース管理を通じてチームに共有される指示です。ローカル指示の./CLAUDE.local.mdは.gitignoreへ追加する前提の、自分だけのサンドボックス設定やテストデータ置き場として使うものです。公式ページは「CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand when Claude reads files in those directories.」と説明しており、起動時に読み込まれるファイルとオンデマンドで読み込まれるファイルが分かれている点に注意が必要です。

CLAUDE.mdの読み込み順序とコンテキストへの連結ルール

CLAUDE.mdの読み込み順序とは、複数のCLAUDE.mdファイルが見つかったときに、どの内容がどの順番でコンテキストへ並べられるかを決めるルールのことです。

公式ドキュメントは「Claude Code loads CLAUDE.md and CLAUDE.local.md from your current working directory and every directory above it. Run Claude Code in foo/bar/ and it loads instructions from foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.」と説明しています。作業ディレクトリより上の階層にある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 … so instructions closer to where you launched Claude are read last.」と述べています。つまりファイルシステムのルートに近いCLAUDE.mdから順にコンテキストへ並び、Claudeを起動したディレクトリに近い指示ほど後から読まれます。各ディレクトリ内では、CLAUDE.local.mdはCLAUDE.mdの後に追加されるため、個人的なメモはそのレベルで最後に読まれる内容になります。

さらに、作業ディレクトリの下のサブディレクトリにあるCLAUDE.mdやCLAUDE.local.mdは、起動時ではなくClaudeがそのサブディレクトリ内のファイルを実際に読み込んだタイミングで、オンデマンドに読み込まれます。公式ページによれば、CLAUDE.md内のブロックレベルのHTMLコメント(<!-- maintainer notes -->)は、コンテンツがコンテキストへ注入される前に取り除かれます。人間の保守担当者向けのメモをコンテキストのトークンを消費せずに残せる仕組みです。

プロジェクト用CLAUDE.mdを/initコマンドで作る

/initコマンドとは、Claude Codeがコードベースを解析し、ビルドコマンドやテスト手順、プロジェクトの規約を含んだCLAUDE.mdのたたき台を自動生成する機能のことです。

公式ドキュメントは「Run /init to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.」と案内しています。すでにCLAUDE.mdがある場合は上書きではなく改善提案になる点が、安心して繰り返し実行できるポイントです。

プロジェクト用のCLAUDE.mdは./CLAUDE.mdと./.claude/CLAUDE.mdのどちらにも置けます。公式ページは、プロジェクトで作業する全員に適用される指示(ビルド・テストコマンド、コーディング標準、アーキテクチャ上の決定、命名規約、共通ワークフローなど)をここに書き、バージョン管理を通じてチームと共有する運用を勧めています。ファイルが実際に読み込まれたかどうかは、セッション内で/contextを実行し、「Memory files」欄のリストを確認することで判定できます。

仮の例として、Node.js製のAPIプロジェクトで/initを実行すると、次のような叩き台が生成されるイメージです(あくまで仮の例であり、実際の出力はプロジェクトごとに異なります)。

## ビルドとテスト
- npm run build でビルド
- npm test でテスト実行(コミット前に必須)

## ディレクトリ構成
- src/api/ にAPIハンドラー
- src/lib/ に共通ロジック

生成された叩き台をそのまま使うのではなく、Claudeがコードから自動で導き出せない情報(チームの暗黙ルールや過去の失敗から得た教訓など)を書き足していくのが、次の章で説明する「書くべき内容」の考え方です。

CLAUDE.mdに書くべき内容

CLAUDE.mdに書くべき内容とは、毎回のセッションでClaudeが保持しておくべき事実、たとえばビルドコマンドや規約、プロジェクトのレイアウト、「常にXをする」というルールのことです。

公式ドキュメントは、CLAUDE.mdを「そうでなければ何度も説明し直すことになる内容を書く場所」として扱うよう勧めています。具体的には次のようなタイミングで追記します。

公式ページはさらに「Specificity: write instructions that are concrete enough to verify.」として、検証できるほど具体的な指示を書くことを求めています。例として「Use 2-space indentation」の方が「Format code properly」より機能する、「Run npm test before committing」の方が「Test your changes」より機能する、「API handlers live in src/api/handlers/」の方が「Keep files organized」より機能する、という3つの言い換え例が挙げられています。プロンプト全般の具体性を高めるコツはClaudeのプロンプトのコツでも扱っているので、CLAUDE.mdの文面作りにも応用できます。

構造化についても言及があり、「Structure: use markdown headers and bullets to group related instructions. Claude scans structure the same way readers do: organized sections are easier to follow than dense paragraphs.」とされています。見出しと箇条書きで関連する指示をグループ化すると、Claude自身も人間の読者と同じように構造を手がかりに読み取りやすくなるということです。

CLAUDE.mdに書くべきでない内容

CLAUDE.mdに書くべきでない内容とは、複数ステップの手順やコードベースの一部分にしか関わらない情報など、毎回のセッションで保持する必要のない項目のことです。

公式ドキュメントは「If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.」と述べています。手順が長い作業や、特定のディレクトリ・ファイル種別にしか関係しない指示は、CLAUDE.mdではなくスキルやパススコープ付きルールへ切り出すべきだという整理です。パススコープ付きルールについては後述の「長くなったときの分割・整理手順」で扱います。

もう1つの注意点は、CLAUDE.mdが「強制設定ではない」ということです。公式ページは「Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.」と明言しています。「このコマンドは実行しない」といった強制したいルールをCLAUDE.mdだけに書いても、Claudeの判断次第で従われない可能性が残ります。コミット前に毎回実行したい処理やファイル編集後に毎回走らせたい処理は、CLAUDE.mdの箇条書きではなくフックとして書くべきだと公式ページも案内しています。フックのイベント一覧や設定ファイルの書き方はClaude Codeのフック(hooks)の使い方で解説しています。

また「My CLAUDE.md is too large」の章で示されているように、ディレクトリレイアウトや依存関係リスト、アーキテクチャ概要など、Claudeがコードベースから自力で導き出せる内容も、書き込む優先度は低いとされています。落とし穴や設計判断の理由、ツールの既定値と異なる独自ルールなど、コードから読み取れない情報を優先するのが実務的な線引きです。

CLAUDE.mdの行数目安とサイズ上限

CLAUDE.mdの行数目安とサイズ上限とは、CLAUDE.mdが問題なく機能するために推奨される長さと、Claude Codeが読み込みを打ち切る技術的な上限のことです。

公式ドキュメントは「Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.」としています。1つのCLAUDE.mdファイルは200行を下回ることを目安にし、それより長いファイルはより多くのコンテキストを消費し、指示への遵守度を下げる可能性があるという説明です。

行数の目安とは別に、技術的な読み込み上限も明記されています。同ページは「Claude Code loads a CLAUDE.md file of up to 4 MiB in full and skips a larger file. Shorter files produce better adherence.」と述べており、4 MiBを超えるCLAUDE.mdファイルはスキップされる仕様です。200行という目安はあくまで遵守度を保つための推奨値であり、4 MiBという上限は超えると読み込まれなくなる技術的な境界線という、性質の異なる2つの数字です。

肥大化を防ぐ具体的な分割方法は、後述の「CLAUDE.mdが長くなったときの分割・整理手順」で扱います。なお自動メモリの索引ファイルであるMEMORY.mdには別の上限(先頭200行または25KBのいずれか早い方)が設定されていますが、これはCLAUDE.mdとは別のファイルに対するルールです。公式ページは「This limit applies only to MEMORY.md.」と明記しており、CLAUDE.md自体の4 MiB上限とは区別して理解する必要があります。

CLAUDE.mdで@import構文を使う方法

@import構文とは、CLAUDE.mdファイルの中から他のファイルを読み込んでコンテキストへ展開できる、@path/to/importという記法のことです。

公式ドキュメントは「CLAUDE.md files can import additional files using @path/to/import syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.」と説明しています。相対パスと絶対パスの両方が使え、相対パスは作業ディレクトリではなく、importを書いたファイル自身を基準に解決されます。インポートされたファイルはさらに他のファイルを再帰的にインポートできますが、同ページによれば「with a maximum depth of four hops」、つまり最大4階層までという制限があります。

パスをインポートせずに単に文中で言及したいだけの場合は、バッククォートで囲みます。公式ページは「Import parsing skips Markdown code spans and fenced code blocks. … writing `@README` keeps the text literal, while @README outside backticks imports the file.」と述べており、コードスパンやコードブロックの中の@パス表記はインポートとして解釈されません。README、package.json、ワークフローガイドをまとめて読み込みたい場合は、公式ページの例のように本文中に並べて書けます。

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

チェックインしたくない個人的な設定はCLAUDE.local.mdとして切り出し、.gitignoreに追加します。複数のgit worktreeをまたいで個人設定を共有したい場合は、ホームディレクトリのファイルを@~/.claude/my-project-instructions.mdのようにインポートする方法が案内されています。なお、作業ディレクトリの外を指すインポート(ホームディレクトリからのインポートなど)は「外部インポート」として扱われ、プロジェクトで最初に検出された際に承認ダイアログが表示される仕様です。

CLAUDE.mdとAGENTS.mdの違いと共存方法

CLAUDE.mdとAGENTS.mdの違いとは、Claude CodeがCLAUDE.md系のファイルを優先して読み込み、作業ディレクトリとその上位にCLAUDE.md系が1つも無いときだけAGENTS.mdをプロジェクト指示として読み込む、という読み込み対象の違いのことです。

公式ドキュメントは「Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting.」と説明しています。既定では、作業ディレクトリとその上位にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdのいずれも無い場合にかぎり、AGENTS.mdがそのままプロジェクト指示として読み込まれます。逆にCLAUDE.md系が1つでもあると、AGENTS.mdは既定では読まれません。同ページは「Reading AGENTS.md directly requires Claude Code v2.1.277 or later.」ともしており、この直接読み込みはバージョン依存です。Amazon Bedrock利用時やテレメトリ無効のセッションなど、AGENTS.mdを読めない環境もあるとされています。両方を読ませたい場合は/configのProject instructions設定をclaude-md-and-agents-mdへ変更します。直接読み込みができないセッションや、CLAUDE.mdを併用したい場合は、CLAUDE.mdを作って@AGENTS.mdという形でインポートすれば、内容を重複させずに同じ指示を読ませられます。Claude固有の指示を追加したい場合は、インポート行の下に書き足す運用です。

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Claude固有の内容を追加する必要がなければ、シンボリックリンクでも代用できます。公式ページは「If you don’t need Claude-specific content, a symlink also works:」としてln -s AGENTS.md CLAUDE.mdを挙げています。どちらの方法でも、次のセッションで/contextを実行し、CLAUDE.mdが「Memory files」欄に表示されることを確認できます。なお設定経由で直接読み込まれたAGENTS.mdは「Memory files」欄ではなく、セッション冒頭の「no CLAUDE.md found; AGENTS.md loaded:」という行で確認します。

チームでCLAUDE.mdを共有し矛盾を防ぐ運用

チームでの共有運用とは、プロジェクト指示のCLAUDE.mdをバージョン管理にコミットし、矛盾する指示を定期的に整理しながらチーム全体に一貫した内容を届ける進め方のことです。

プロジェクト指示のCLAUDE.md(./CLAUDE.mdまたは./.claude/CLAUDE.md)は公式の配置場所一覧で共有範囲が「Team members via source control」とされており、コミットすることでチーム全員に同じ指示が届きます。一方で個人的な好みはCLAUDE.local.mdに分けて.gitignoreへ入れる、という役割分担が公式に案内されています。

公式ドキュメントは「Consistency: if two rules contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions.」と注意を促しています。2つのルールが矛盾していると、Claudeはどちらか一方を任意に選んでしまう可能性があるため、階層をまたいだCLAUDE.mdどうしの矛盾がないか定期的に見直す運用が必要です。

モノレポでは、自分の作業に関係のない他チームのCLAUDE.mdまで読み込まれてしまう場合があります。公式ページは、その対策としてclaudeMdExcludes設定でパスやglobパターンを指定し、特定のCLAUDE.mdを個別にスキップできるとしています。さらに組織単位では、管理ポリシーの配置場所(前述の表を参照)にCLAUDE.mdを配布することで、個々のユーザー設定では除外できない組織共通の指示を全マシンへ適用できます。公式ページの配置場所一覧が「in load order, from broadest scope to most specific」と明記している通り、管理ポリシーのCLAUDE.mdはユーザー指示・プロジェクト指示より先にコンテキストへ入ります。

CLAUDE.mdが長くなったときの分割・整理手順

分割・整理手順とは、CLAUDE.mdが200行の目安を超えて長くなってきたときに、内容をスキルやパススコープ付きルールへ切り分けてコンテキスト消費を抑える進め方のことです。

公式ドキュメントは、大規模プロジェクト向けに.claude/rules/ディレクトリを使った整理方法を案内しています。「For larger projects, you can organize instructions into multiple files using the .claude/rules/ directory. … Place markdown files in your project’s .claude/rules/ directory. Each file should cover one topic, with a descriptive filename like testing.md or api-design.md.」とある通り、1ファイル1トピックの原則でmarkdownファイルを分割し、testing.mdやapi-design.mdのような説明的なファイル名を付けます。pathsフロントマターを持たないルールは、.claude/CLAUDE.mdと同じ優先度で起動時に読み込まれます。

さらにルールは特定のファイルパスにだけ適用範囲を絞れます。YAML フロントマターのpathsフィールドにglobパターンを書くと、そのパターンに一致するファイルをClaudeが読み込むときだけルールが有効になり、常時コンテキストへ載せずに済みます。タスク固有で常時読み込む必要のない指示は、ルールではなくスキルへ移す選択肢もあります。

ここで注意したいのは、@pathインポートによる分割は整理には役立つものの、コンテキスト消費そのものは減らないという点です。公式ページは「Splitting into @path imports helps organization but doesn’t reduce context, since imported files load at launch.」と明言しています。ファイルを見やすく分けたいだけならインポート、実際にコンテキスト消費を減らしたいならパススコープ付きルールという使い分けが必要です。あわせて/doctorチェックアップは、コミット済みのCLAUDE.mdに対してディレクトリレイアウトや依存関係リストなどコードから導出できる内容のトリミングを提案してくれます。大規模なClaude Code運用の考え方はClaude Code Dynamic Workflowsの大規模開発事例でも取り上げています。

よくある質問（FAQ）

Q1. CLAUDE.mdはどこに置けばまず動きますか。

プロジェクトのルートに./CLAUDE.mdを置けば、そのプロジェクトで作業するときに読み込まれます。公式ドキュメントはプロジェクト指示を「Team-shared instructions for the project」と位置づけており、まずはここにビルド・テストコマンドやコーディング標準を書くのが基本の始め方です。

Q2. CLAUDE.mdに書けば、指示は常に守られますか。

常に守られるとは限りません。公式ドキュメントは「Claude treats them as context, not enforced configuration.」と説明しており、CLAUDE.mdの内容はコンテキストとして渡されるだけで、強制的な設定にはなりません。動作を判断に関わらず止めたい場合はPreToolUseフックを使う必要があります。

Q3. CLAUDE.mdとAGENTS.mdは両方書く必要がありますか。

両方書く必要はありません。既定では、作業ディレクトリとその上位にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdのいずれも無ければ、AGENTS.mdがそのまま読み込まれます(Claude Code v2.1.277以降)。CLAUDE.md系を置くとAGENTS.mdは既定で読まれなくなるため、両方を読ませたい場合は/configのProject instructionsをclaude-md-and-agents-mdにするか、CLAUDE.mdから@AGENTS.mdでインポートします。

Q4. CLAUDE.mdを使うのに追加料金はかかりますか。

CLAUDE.mdを置くこと自体に専用の追加料金メニューはありません。ただし公式ドキュメントはCLAUDE.mdについて「loaded into the context window at the start of every session, consuming tokens alongside your conversation」と述べており、毎回のセッションでコンテキストのトークンを消費します。従量課金で利用している場合、その分は通常の利用量に含まれます。Claude Codeで使えるプランやモデルごとの料金体系はClaude料金プラン完全比較で確認できます。

Q5. サブディレクトリに置いたCLAUDE.mdはいつ読み込まれますか。

作業ディレクトリより上の階層にあるCLAUDE.mdは起動時にまとめて読み込まれますが、作業ディレクトリの下のサブディレクトリにあるCLAUDE.mdは、Claudeがそのサブディレクトリ内のファイルを実際に読み込んだタイミングでオンデマンドに読み込まれます。

Q6. 200行を超えたら、CLAUDE.mdはすぐ読み込まれなくなりますか。

いいえ。200行は遵守度を保つための推奨目安であり、これを超えても読み込み自体は続きます。読み込みが完全に止まるのは4 MiBを超えた場合で、その場合はファイル全体がスキップされます。

Q7. .claude/rules/とCLAUDE.mdはどう使い分けますか。

プロジェクト全体に常時効かせたい短い指示はCLAUDE.md、特定のファイルパスにだけ適用したい指示や、トピックごとに分割して管理したい指示は.claude/rules/のパススコープ付きルールに向いています。pathsフロントマターのないルールはCLAUDE.mdと同じ優先度で起動時に読み込まれます。

まとめ

CLAUDE.mdは、Claude Codeへ渡す永続的な指示をMarkdownで書くファイルで、管理ポリシー・ユーザー・プロジェクト・ローカルという4段階の配置場所ごとに読み込み順が決まっています。複数のCLAUDE.mdは上書きではなく連結され、ファイルシステムのルートに近いものから順にコンテキストへ並び、Claudeを起動した場所に近い指示ほど後から読まれます。書く内容は、ビルドコマンドや規約など毎回のセッションで保持すべき事実に絞り、複数ステップの手順や一部のコードにしか関係しない情報はスキルやパススコープ付きルールへ切り出すのが公式の推奨です。

目安として1ファイル200行未満を保ち、4 MiBの読み込み上限を超えないようにする、チームで共有する場合はプロジェクト指示をコミットしつつCLAUDE.local.mdで個人設定を分ける、肥大化したら.claude/rules/へ分割する、という運用サイクルを回せば、Claude Codeの指示遵守度を保ちながら長期的にCLAUDE.mdを育てていけます。Claude Codeそのものの使い方や料金はClaude活用の使い方、外部ツール連携はMCPとは、繰り返し使うワーカーの切り出し方はClaude Codeのサブエージェント使い方も参考にしてください。