CLAUDE.mdとは？Claude Codeが毎セッション読み込むプロジェクト指示ファイル
CLAUDE.md とは、Claude Code がセッションの開始時に毎回読み込む、プロジェクト専用の指示ファイルです。Markdown 形式のテキストで、ビルドやテストのコマンド、ファイル構成、命名規則といった「毎回説明せずに済ませたい前提」を書いておきます。
Claude Code は会話ごとに新しいコンテキストで起動するため、前のセッションでのやり取りは引き継がれません。CLAUDE.md はその断絶を埋める仕組みで、ファイルに書いた内容が次のセッションでも読まれます。以下の仕様は Anthropic が公開する Claude Code の公式ドキュメント（2026年9月時点）に基づきます。
関連記事：Claude Codeとは？できること・料金・使い方と社内導入の判断軸
CLAUDE.mdに書くのは「毎回説明し直していること」
何を書くかで迷ったときの目安は、同じ説明を二度入力したかどうかです。公式ドキュメントは、CLAUDE.md に追記するタイミングとして次の4つを挙げています。
- 同じ間違いが二度目に起きたとき: 一度直した指摘が再発するなら、会話ではなくファイルに書く
- コードレビューで指摘が出たとき: そのリポジトリの事情を知っていれば防げた指摘は、前提が渡っていない証拠
- 前のセッションと同じ訂正を打ったとき: 入力の重複は、そのまま CLAUDE.md の項目になる
- 新しく入った人に同じ説明が必要なとき: 人に説明する前提は、AI にも必要な前提
逆に、複数ステップにわたる手順や、リポジトリの一部でしか関係しない内容は置かない方が扱いやすくなります。公式ドキュメントはこうした内容をスキル、またはパスごとに読み込むルールへ切り出すことを推奨しています。
関連記事：Claude Skillsとは？できること・作り方と無料で使える範囲を整理
設定ファイルではなく「文脈」として渡される
つまずきやすいのが、これが設定ファイルではないという点です。公式ドキュメントは、CLAUDE.md の内容がシステムプロンプトの一部ではなく、その後に続くユーザーメッセージとして渡されると明記しています。Claude はそれを読んで従おうとしますが、厳密な遵守が保証される仕組みではありません。曖昧な書き方や矛盾する指示が入っていると、従われる確率はそのぶん下がります。
Claude の判断に関係なく必ず止めたい操作がある場合は、CLAUDE.md ではなく hook（特定のタイミングでシェルコマンドを実行する仕組み）を使います。コミット前に必ずテストを走らせる、特定のファイルへの書き込みを禁止する、といった要件は hook や権限設定の側で担保します。
CLAUDE.mdを置ける4つの場所と、読み込まれる仕組み
CLAUDE.md は1箇所に置くものではなく、影響範囲の違う4つの場所を使い分けます。公式ドキュメントは、読み込まれる順に（影響範囲の広いものから狭いものへ）次のように規定しています。
| 置き場所 | パス | 共有範囲 | 向いている内容 |
|---|---|---|---|
| 組織のポリシー | macOS は `/Library/Application Support/ClaudeCode/CLAUDE.md`、Linux と WSL は `/etc/claude-code/CLAUDE.md`、Windows は `C:\Program Files\ClaudeCode\CLAUDE.md` | その端末を使う全員 | 全社共通の規約、セキュリティ要件 |
| 個人の設定 | `~/.claude/CLAUDE.md` | 自分だけ（すべてのプロジェクト） | 書き方の好み、よく使う手順 |
| プロジェクトの設定 | `./CLAUDE.md` または `./.claude/CLAUDE.md` | Git 経由でチーム全員 | 構成、ビルド・テストの手順、命名規則 |
| 個人のプロジェクト設定 | `./CLAUDE.local.md` | 自分だけ（そのプロジェクト） | 検証用の URL、手元のテストデータ |
使い分けは「誰に効かせたいか」で決まります。チームで揃えたい前提はプロジェクトの設定に置いて Git で共有し、書き方の好みは個人の設定へ寄せます。CLAUDE.local.md は Git に含めない前提なので .gitignore へ追加します。組織のポリシーは個人の設定では除外できないため、ここに書く内容は全社で外せないものに絞ります。
複数のCLAUDE.mdは上書きされず、すべて連結される
ここが誤解の多い部分です。複数の CLAUDE.md が見つかったとき、より具体的なファイルが広いファイルを上書きするわけではありません。公式ドキュメントは、見つかったファイルはすべてコンテキストに連結されると明記しています。
順序はルート側から作業ディレクトリへ向かう方向です。foo/bar/ で起動した場合、foo/CLAUDE.md が先に入り、foo/bar/CLAUDE.md が後に入ります。同じディレクトリ内では CLAUDE.md の後に CLAUDE.local.md が続きます。
上の階層に書いた指示は消えないため、下の階層で方針を変えたいときは矛盾する記述そのものを整理します。公式ドキュメントも、2つのルールが矛盾する場合は Claude がどちらかを任意に選ぶ可能性があるとして、定期的な棚卸しを挙げています。
サブディレクトリのCLAUDE.mdは必要になった時点で読まれる
起動時に読まれるのは、作業ディレクトリとその上位にあるファイルです。下にある CLAUDE.md は起動時には読まれず、Claude がそのディレクトリのファイルを読んだ時点で読み込まれます。
モノレポのように他チームのディレクトリが上位に連なる環境では、関係のない指示が入ってくることがあります。この場合は claudeMdExcludes 設定でパスやグロブパターンを指定し、読み込み対象から外せます。
CLAUDE.mdの書き方｜指示が守られる3つの条件
同じ内容でも、書き方によって従われる度合いが変わります。公式ドキュメントが挙げる条件のうち、効き方を左右するのは具体性・構造・一貫性の3つです。
AIエージェントを「どう作り、どう育てるか」を、GiftX記事制作エージェントの実物で解説。
条件1: 検証できる粒度まで具体的に書く
抽象的な指示は解釈の幅が広いぶん、期待した結果から外れます。公式ドキュメントは、同じ意図でも次のように書き分けることを例示しています。
- インデント: 「コードを整形する」ではなく「インデントは半角スペース2つ」
- テスト: 「変更をテストする」ではなく「コミット前に
npm testを実行する」 - ファイル配置: 「ファイルを整理する」ではなく「API ハンドラは
src/api/handlers/に置く」
目安は、書いた内容が満たされているかを後から検証できるかです。検証できない書き方は、守られたかどうかも確かめられません。
条件2: 見出しと箇条書きで構造を与える
CLAUDE.md は Markdown として読まれます。関係する指示は見出しでまとめ、箇条書きで並べます。公式ドキュメントは、Claude も読者と同じように構造を手がかりに読むため、整理された節のほうが密な文章より追いやすいと説明しています。
条件3: 矛盾する記述を残さない
矛盾した指示が複数ある状態は、従われない原因になります。プロジェクトの CLAUDE.md、サブディレクトリの CLAUDE.md、パスごとのルールを定期的に見直し、古くなった記述を削ります。どの業務から書き起こすか決めかねるときは、職種ごとに最初に任せる1業務を整理した職種別AI活用事例集にまとめています。
長くなったCLAUDE.mdの分割方法｜importと.claude/rulesの使い方
CLAUDE.md は毎セッション読み込まれるため、長くなるほどコンテキストを消費し、守られる度合いも下がります。公式ドキュメントは1ファイルあたり200行以下を目標として挙げています。
@importで別ファイルを読み込む
@path/to/import の記法で、別のファイルを CLAUDE.md に取り込めます。相対パスと絶対パスのどちらも使えて、相対パスは作業ディレクトリではなく記述したファイルの位置から解決されます。取り込んだ先からさらに取り込むこともできますが、深さは4ホップまでです。
注意点は2つあります。1つは、import したファイルも起動時にコンテキストへ入るため、分割してもトークンの消費は減らないことです。整理の手段であって、軽量化の手段ではありません。もう1つは、パスを文章中で言及したいだけのときはバッククォートで囲む必要がある点です。囲まない @README は import として解釈されます。
.claude/rules/でファイルの種類ごとに出し分ける
コンテキストの消費そのものを抑えたい場合は、.claude/rules/ に置くルールを使います。ディレクトリ内の Markdown ファイルは再帰的に読み込まれ、トピックごとに分けられます。
ここで効くのが paths の指定です。ファイルの先頭に paths を書いてグロブパターンを指定すると、そのパターンに一致するファイルを Claude が読んだときだけルールが読み込まれます。API のコーディング規約を src/api/**/*.ts に紐づけておけば、フロントエンドの作業中はコンテキストに入りません。paths を書かないルールは常に読み込まれます。
CLAUDE.mdとAGENTS.md・auto memoryの違い
似た役割のファイルや仕組みが複数あり、どれに何を書くかで迷いやすい領域です。3つの違いを整理します。
| CLAUDE.md | auto memory | AGENTS.md | |
|---|---|---|---|
| 書く人 | 自分（チーム） | Claude | 自分（他ツール向け） |
| 中身 | 指示とルール | 訂正や好みから学んだ傾向 | 他のコーディングエージェント向けの指示 |
| 読み込み | 毎セッション | 毎セッション（`MEMORY.md` の先頭200行または25KBまで） | Claude Code は読み込まない |
| 置き場所 | プロジェクト / 個人 / 組織 | `~/.claude/projects/<project>/memory/` | リポジトリのルート |
AGENTS.mdはimportで共通化する
Claude Code が読むのは CLAUDE.md で、AGENTS.md は読み込みません。他のコーディングエージェント向けに AGENTS.md を運用している場合は、CLAUDE.md の先頭に @AGENTS.md と書いて取り込むと、内容を二重に持たずに済みます。取り込んだ下に Claude Code 固有の指示を書き足せます。シンボリックリンクでも同じ結果になりますが、Claude 固有の記述を足せません。
関連記事：AGENTS.mdとは？Codexにプロジェクト規約を守らせる設定と書き方
auto memoryはClaudeが自分で書くメモ
auto memory は、訂正や好みを Claude 自身が記録していく仕組みです。既定で有効で、索引にあたる MEMORY.md の先頭200行、または25KBまでが毎セッション読み込まれます。
書き手が違うだけでなく、書く内容も分かれます。公式ドキュメントによれば、Claude はコードから読み取れる内容や、CLAUDE.md に既に書かれている内容は保存しません。CLAUDE.md を整えておくほど、auto memory 側には「コードからは分からない判断の経緯」が残ります。
GiftXの自社事例｜CLAUDE.mdで共有する前提と個人の好みを分ける
GiftX では、このメディアを運用しているリポジトリで CLAUDE.md を次のように運用しています。
共有するルールはAGENTS.mdに集約する
プロジェクト側の CLAUDE.md は1行目で @AGENTS.md を取り込み、共通の運用ルールは AGENTS.md に集約しています。Claude Code と他のコーディングエージェントの両方で同じリポジトリを触るため、ルールの正本を1つにしておかないと、どちらかの側だけが古い前提で動くことになります。CLAUDE.md に直接書くのは、使用するサブエージェントの名前や権限設定の置き場所といった Claude Code 固有の事柄だけです。
個人の設定には品質を左右する内容を書かない
個人の設定（~/.claude/CLAUDE.md）には、使うモデルの選び方と対話の進め方だけを置いています。ここに成果物の品質を左右する内容を書くと、同じ手順を動かしても担当者によって結果が変わってしまうためです。品質に効く内容は、必ずリポジトリ側の共有ファイルに書きます。
この線引きは一度決めて終わりにはなりませんでした。個人の設定が増えていった時期に、レビュー結果へ成果物と無関係な運用ルールが混ざる状態が続き、個人の設定から運用ルールを共有側へ移す作業が必要になりました。どちらに書くかの基準を決めておくと、こうした混ざり方を避けやすくなります。
全国8,000人調査で、AIの活用方法によって生産性向上に約3.8倍の差が生まれることが判明。
そのまま使えるCLAUDE.mdのテンプレート
最小構成は5つの節で足ります。いずれも公式ドキュメントが挙げる「毎セッション必要な前提」に対応する内容です。
| 節 | 書く内容 | 書き方の例 |
|---|---|---|
| プロジェクトの概要 | 何を作っているか、使っている技術 | 社内向けの在庫管理 Web アプリ。Next.js と PostgreSQL で構成 |
| コマンド | ビルド・テスト・リントの実行方法 | テストは `npm test`、リントは `npm run lint` |
| 構成 | どのディレクトリが何を担当するか | API ハンドラは `src/api/handlers/` に置く |
| 書き方の決まり | インデント、命名、禁止事項 | インデントは半角スペース2つ。`any` 型を使わない |
| 必ず守ること | 例外を作らない運用ルール | コミット前に `npm test` を実行する |
この5節を埋めたうえで、運用しながら追記していく形が扱いやすくなります。ゼロから書き始める場合は /init コマンドでリポジトリを解析させ、ビルドコマンドやテスト手順を含む下書きを作らせてから、コードを読んでも分からない事柄を足していけます。既に CLAUDE.md がある状態で実行した場合は、上書きではなく改善案の提示になります。
なお人間向けのメモは、ブロックレベルの HTML コメントで残せます。コメントはコンテキストへ注入される前に除去されるため、トークンを消費しません。
CLAUDE.mdの指示が効かないときに確認する3つのこと
書いたのに効いていないと感じたときは、内容を書き直す前に読み込み状況から確認します。
- 読み込まれているかを確認する:
/contextを実行し、Memory files の一覧に対象のファイルがあるかを見ます。一覧に無ければ Claude はそのファイルを見ていません - 具体性を上げる: 「コードを整形する」のような指示は解釈の幅が広く、従われたかどうかも検証できません。検証できる粒度まで書き換えます
- 矛盾を探す: 上位ディレクトリの CLAUDE.md やパスごとのルールに、反対の指示が残っていないかを見ます。連結される仕様のため、上の階層の記述は消えていません
それでも守らせたい操作がある場合は、CLAUDE.md ではなく hook で実装します。公式ドキュメントも、コミット前やファイル編集後のように決まったタイミングで必ず実行したい内容は hook に書くよう案内しています。/compact でコンテキストを圧縮した後もプロジェクト直下の CLAUDE.md は読み直されるため、圧縮後に指示が消えたと感じる場合は、会話の中だけで伝えた内容だった可能性があります。
CLAUDE.mdのよくある質問
CLAUDE.mdのファイル名は変えられますか
読み込まれるファイル名は決まっており、CLAUDE.md と CLAUDE.local.md、.claude/CLAUDE.md が対象です。AGENTS.md のような別名は読み込まれないため、@AGENTS.md の記法で取り込むか、シンボリックリンクを張る形で対応します。
CLAUDE.mdに文字数制限はありますか
明示的な文字数制限はありませんが、公式ドキュメントは1ファイルあたり200行以下を目標として挙げています。4 MiB を超えるファイルは読み込み自体がスキップされます。
CLAUDE.mdとAGENTS.mdはどちらを使えばよいですか
Claude Code だけを使うなら CLAUDE.md で足ります。他のコーディングエージェントも併用しているなら、AGENTS.md を正本にして CLAUDE.md から取り込む形が二重管理を避けられます。
サブディレクトリに置いたCLAUDE.mdは読まれますか
作業ディレクトリより下にあるファイルは、起動時ではなく、Claude がそのディレクトリのファイルを読んだ時点で読み込まれます。起動直後に /context で確認しても一覧に出ないことがあるのは、この仕様によるものです。
CLAUDE.mdをチームで共有するとき気をつけることはありますか
プロジェクトの CLAUDE.md は Git 経由で全員に渡るため、検証用の URL のような個人の事情は CLAUDE.local.md に分け、.gitignore へ追加します。複数の worktree で作業する場合、CLAUDE.local.md は作成した worktree にしか存在しない点に注意が必要です。
AIエージェントに業務を任せるときに陥りがちな3つの落とし穴
CLAUDE.md を整えると、AI に任せられる範囲が目に見えて広がります。一方で、そこから業務そのものを任せる段階に進むときは、つまずき方に共通の型があります。
落とし穴1｜いきなり全ての業務を任せようとする
複数の工程をまとめて任せると、どこで判断が外れたのか分からなくなります。前提を渡しても結果が安定しないのは、工程の数が多すぎて1つずつ検証できていないことが原因であることが多いです。まずは工程を切り出して、外れた箇所を特定できる状態にします。
落とし穴2｜完璧なルールを書き切ろうとして手が止まる
起こりうる例外をすべて書こうとすると、書き終わらないまま運用が始まりません。実際に動かして外れた箇所を足していく方が、結果的に短い記述で済みます。
落とし穴3｜既製のチャット型AIツールで済ませようとする
既製のチャット型 AI ツールは自社の前提を渡す経路が限られるため、業務フローに組み込める質まで届きません。自社の判断基準と手順を渡せる形にしておくことが前提になります。
スモールスタートで1業務をAIエージェントに任せる
この3つはいずれも、対象を小さく切れていないことから生じます。まず1業務を選び、その業務の前提だけを書き切って、結果を検証しながら範囲を広げる進め方がポイントです。GiftX では、こうしたスモールスタート前提の進め方を1業務単位から伴走支援しています。詳細はAIエージェント構築支援サービスをご覧ください。
まとめ
CLAUDE.md は、Claude Code が毎セッション読み込むプロジェクト専用の指示ファイルです。置き場所は組織・個人・プロジェクト・個人のプロジェクト設定の4種類で、見つかったファイルは上書きではなくすべて連結されます。指示が守られるかどうかは、検証できる具体性、見出しによる構造、矛盾のない記述の3点で決まります。
200行を超えたら @import での整理か、パスごとに読み込む .claude/rules/ への切り出しを検討します。AGENTS.md を併用している場合は取り込む形にして正本を1つに保ち、効いていないと感じたときは /context で読み込み状況から確認します。そのうえで業務そのものを任せる段階に進むときは、対象を1業務に絞って始めるのが着実です。
AI活用の伴走支援をご検討の方へ
本記事で紹介したAIエージェントの活用に向けて、自社の業務でも具体的に進めたい・相談したいとお考えの方は、ぜひGiftX AIエージェント構築支援までお問い合わせください。
GiftX AIエージェント構築支援では、貴社の業務に合わせて1業務単位のスモールスタートから本番運用まで、AIエージェント構築をワンストップで支援します。ユースケースの洗い出しから、PoC、本番運用、社内ナレッジ化まで伴走します。
AI活用にご関心のある方は、ぜひ一度ご相談ください。
▶ GiftX AIエージェント構築支援の詳細・お問い合わせはこちら
