AI 活用記事AIコーディングツール

CLAUDE.mdの書き方と置き場所|AGENTS.mdは読まれる?Claude Codeで49回試した結果

CLAUDE.mdは、Claude Codeが毎回最初に読む指示ファイルです。置き場所と読まれる順番、AGENTS.mdとの関係、/initでの作り方、効く書き方とテンプレートを、Claude Code 2.1.321で49回試した結果(AGENTS.mdは読まれる・CLAUDE.local.mdを足すと読まれなくなる・HTMLコメントは消える等)とあわせて解説します。

AIコーディングツール、、読了時間:19分

Claudeのロゴ(シンボルと文字)
ロゴ:Anthropic(商標は各社に帰属) — 出典

CLAUDE.mdは、プロジェクトのルートに置き、/init で作った下書きに「コードを読んでも分からない決まり」だけを足すのが基本です。編集部が2026年11月16日にClaude Code 2.1.321で12条件を3回ずつ試したところ、読み込まれたファイルは36回とも公式ドキュメントの説明どおりでした。CLAUDE.mdがなければAGENTS.mdも読まれます。ただし、自分用の CLAUDE.local.md を1つ足しただけで、AGENTS.md は3回とも読まれなくなりました。

CLAUDE.mdとは、Claude Code(Anthropicのコーディング用AI)が作業を始めるたびに読み込む、Markdown形式の指示ファイルです。ビルドやテストのコマンド、フォルダの役割、チームの決まりなど、毎回口で説明し直していることを書いておく場所です。

本記事の検証は計49回です。読み込みのテスト36回、その直し方の確認3回、書き方を変えて同じ作業を頼むテスト9回、/init 1回。仕様の説明は Claude Code の公式ドキュメント(2026年11月16日確認)にもとづきます。

結論:CLAUDE.mdの早見表

知りたいこと 答え 編集部の実測
どこに置く? プロジェクトのルートの CLAUDE.md(または .claude/CLAUDE.md) ルートのCLAUDE.mdは3回とも起動時に読まれた
自分だけのメモは? CLAUDE.local.md(Gitに入れない) 3回とも読まれた
親フォルダのCLAUDE.mdは? 起動したフォルダより上の階層はすべて読まれる 親とサブフォルダの2つとも3回読まれた
サブフォルダのCLAUDE.mdは? そのフォルダのファイルを開いたときに追加で読まれる 起動直後は0/3、ファイルを開いた後は3/3
AGENTS.mdは読まれる? CLAUDE.md・CLAUDE.local.mdがなければ読まれる(v2.1.277以降) AGENTS.mdだけなら3/3、CLAUDE.mdと並べると0/3
両方読ませたい CLAUDE.mdに @AGENTS.md と1行書く 両方とも3/3
人間向けのメモ <!-- --> のHTMLコメントに書くとAIには渡らない コメント内の文は0/3
長くなったら .claude/rules/ に分け、paths: で対象ファイルを絞る 対象のファイルを開くまで読まれない(0/3→3/3)
12通りの置き方で、どの指示ファイルが読み込まれたかを並べた表。CLAUDE.mdだけ、AGENTS.mdだけはそれぞれ読まれた。CLAUDE.mdとAGENTS.mdの両方を置くとCLAUDE.mdだけ。CLAUDE.mdに@AGENTS.mdと書くと両方。CLAUDE.local.mdとAGENTS.mdではCLAUDE.local.mdだけ。親フォルダとapp/のCLAUDE.mdは両方。HTMLコメントの中は読まれない。docs/のCLAUDE.mdは起動直後は読まれず、docs/のファイルを開いた後に追加。paths付きのルールはsrc/a.tsを開いた後に追加。バッククォートで囲んだ@NOTES.mdは取り込まれない。12条件とも3回とも同じ結果
どの指示ファイルが読み込まれたか(12条件×3回)。出典: 編集部の検証(2026年11月16日、Claude Code 2.1.321)

CLAUDE.mdとは(1分で)

Claude Codeは、会話のたびに記憶がない状態から始まります。前回「テストは npm test で」と教えても、次の会話では知りません。CLAUDE.mdは、この「毎回の説明」を文書にしておく仕組みです。

公式ドキュメントは、CLAUDE.mdを「強制される設定ではなく、文脈(コンテキスト)として扱われる」と説明しています。つまり、書いたことは守られやすくなるだけで、必ず守られる保証はありません。「main に直接 push させない」のように絶対に止めたいことは、CLAUDE.mdではなく、フック(PreToolUse)や権限の設定(permissions.deny)で止めます。権限の設定の書き方と、deny で止まるもの・止まらないものはClaude Codeのsettings.jsonの書き方と権限設定で実測しました。

CLAUDE.mdに書くべきタイミングとして、公式は次の4つを挙げています。

  • Claudeが同じ間違いを2回した
  • コードレビューで「このコードベースなら知っておくべきこと」を指摘された
  • 前の会話で入力したのと同じ訂正を、また入力している
  • 新しいメンバーが同じ説明を必要とする

検証した環境と方法

  • Claude Code 2.1.321(claude -p、モデルは haiku の指定で claude-haiku-5-5)。ユーザー用の ~/.claude/CLAUDE.md やルールがない、検証専用のホームフォルダで実行しました。
  • 読み込みのテスト:条件ごとに小さなフォルダを作り、各ファイルに「合言葉: CL-ROOT-7」のような行を1つずつ入れました。ツールを使えない状態で起動し、「いま見えている指示の合言葉をすべて挙げて」と頼みます。判定は、AIの答えではなく、セッションの記録(~/.claude/projects の jsonl)に実際に入った指示の本文で行いました。
  • 書き方のテスト:架空の小さなNode.jsのプロジェクトで「税込金額を返す関数を追加して」と頼み、CLAUDE.mdなし・あいまいに書いた・具体的に書いたの3条件を3回ずつ実行しました。
  • プロジェクトや合言葉はすべて検証用に作ったものです。claude -p が表示した参考の料金換算は、49回の合計で約0.04ドルでした(ログインはサブスクリプションのため、実際の請求額ではありません)。

AIの答えだけで判定しなかったのには理由があります。CLAUDE.local.md を置いた3回のうち1回は、記録には合言葉が入っていたのに、AIは「なし」と答えました。AIに「読んだ?」と聞くだけでは確かめになりません。読み込みを確かめるなら、後で紹介する /context all を使ってください。

Claude CodeはAGENTS.mdを読む?:12条件×3回の結果

AGENTS.mdは、CodexやCursorなど、いろいろなコーディングAIが共通で読む指示ファイルです(詳しくはAGENTS.mdとは?書き方・置き場所とCLAUDE.mdとの違い)。

結論から言うと、Claude Code 2.1.321 は、CLAUDE.mdがないフォルダならAGENTS.mdをそのまま読みました。公式のCHANGELOGでは v2.1.277 で「CLAUDE.mdがないプロジェクトでは、代わりにAGENTS.mdを読む」機能が追加されています。検索結果の1ページ目には、2026年6月時点の情報として「Claude CodeはAGENTS.mdを読まない」とする解説も残っています。古いバージョンを使っている場合はその説明が当てはまるので、claude --version で確かめてください。

置いたファイル 起動時に読み込まれたもの(3回)
AGENTS.md だけ AGENTS.md(3/3)
CLAUDE.md と AGENTS.md CLAUDE.md だけ(AGENTS.md は 0/3)
CLAUDE.md の先頭近くに @AGENTS.md と書き、AGENTS.md も置く 両方(3/3)
CLAUDE.local.md と AGENTS.md CLAUDE.local.md だけ(AGENTS.md は 0/3)
上の条件に、設定 claude-md-and-agents-md を足す 両方(3/3)

落とし穴:CLAUDE.local.md を足すと AGENTS.md が読まれなくなる

チームがAGENTS.mdで指示を共有しているリポジトリで、自分用のメモとして CLAUDE.local.md を作ると、その時点からAGENTS.mdは読まれなくなります。公式ドキュメントにも「CLAUDE.local.md も CLAUDE.md の扱いに数えられる」と注意書きがあり、実測でも3回とも同じでした。エラーや警告は出ないので、気づきにくい点です。

直し方は2つあります。

  1. CLAUDE.local.md(または CLAUDE.md)の中に @AGENTS.md と1行書いて取り込む
  2. Claude Codeの中で /config を開き、「Project instructions」を claude-md-and-agents-md にする

2つ目を設定ファイルで書く場合は、~/.claude/settings.json に次のように書きます(プロジェクトの設定ファイルに書いても無視されます)。編集部は同じ内容を --settings で渡して3回試し、CLAUDE.local.md と AGENTS.md の両方が読まれることを確かめました。

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

CLAUDE.mdの置き場所と読まれる順番

CLAUDE.mdは、置く場所によって効く範囲が変わります。公式ドキュメントの表を、使う人の目線でまとめるとこうなります。

置き場所 効く範囲 共有 向いている内容
~/.claude/CLAUDE.md 自分のすべてのプロジェクト 自分だけ 好みの書き方、いつも使う道具
./CLAUDE.md または ./.claude/CLAUDE.md このプロジェクト Gitでチームと共有 コマンド、フォルダの役割、チームの決まり
./CLAUDE.local.md このプロジェクト 自分だけ(.gitignoreに追加) 自分の検証用URL、テスト用のデータ
組織の管理用(Linuxなら /etc/claude-code/CLAUDE.md) そのパソコンの全員 管理者が配る 会社のセキュリティの決まり

読まれる順番は「広い範囲から狭い範囲へ」です。起動したフォルダとその上の階層のCLAUDE.mdは、すべてつなげて読み込まれます。上書きではなく足し算で、起動したフォルダに近いものほど後に読まれます。編集部が app/ の中で起動したときも、親フォルダと app/ の CLAUDE.md が3回とも両方読まれました。

一方、起動したフォルダより下(サブフォルダ)の CLAUDE.md は、起動時には読まれません。docs/CLAUDE.md は起動直後は3回とも入っておらず、Claudeが docs/guide.md を開いた後に3回とも追加されました。

CLAUDE.mdの作り方(5ステップ)

1. /init で下書きを作る

プロジェクトのフォルダで Claude Code を起動し、/init と入力します。Claudeがコードを読んで、コマンドや構成を書いた CLAUDE.md を作ります。編集部の小さなプロジェクトでは約11秒で、23行・1,141字の CLAUDE.md ができました。テストの実行方法(1ファイルだけ・1件だけの実行方法まで)や、CHANGELOG.md の「## Unreleased」に追記する決まりも、ファイルから読み取って書かれていました。文章は英語でした。

2. コードを読んでも分からないことだけを足す

/init が書けるのは、コードやファイルから分かることだけです。そこに「レビューは誰が見るか」「本番のデータに触れてはいけない」「お客様向けの文言は敬語」など、コードのどこにも書かれていない決まりを足します。コードから分かることを長々と書き直す必要はありません。

3. 確かめられる形で書く

公式ドキュメントは「コードをきちんと整形する」ではなく「インデントはスペース2つ」、「変更をテストする」ではなく「コミット前に npm test を実行する」のように、確かめられる形で書くよう勧めています。見出しと箇条書きで分け、1ファイル200行未満を目安にします。

4. 長くなったら .claude/rules に分ける

特定のファイルにだけ関係する決まりは、.claude/rules/ の下に1テーマ1ファイルで置きます。ファイルの先頭に paths: を書くと、そのファイルを扱うときだけ読み込まれます。編集部の実測では、paths: "src/**/*.ts" のルールは起動直後は0/3で、Claudeが src/a.ts を開いた後に3/3で読み込まれました。paths: のないルールは、起動時に毎回読まれました。

5. /context all で読み込まれたかを確かめる

Claude Codeの中で /context all を実行し、「Memory files」の一覧に自分のファイルが出ているかを見ます。書いたのに効かないときは、まずここで「読み込まれていない」のか「読まれたのに守られていない」のかを分けます。v2.1.283 以降は /doctor prompt-audit で、古い指示や食い違う指示を点検することもできます(ファイルは自動では書き換わりません)。

書き方で結果は変わる?:なし・あいまい・具体で9回試した結果

同じ依頼「税込金額(10%、1円未満切り捨て)を返す関数 withTax を追加して」を、CLAUDE.mdの書き方だけ変えて3回ずつ頼みました。プロジェクトには、テストのフォルダと CHANGELOG.md が最初からあります。

結果(3回中) CLAUDE.mdなし あいまいに書いた 具体的に書いた
関数が正しい(100円→110円、999円→1,098円など) 3/3 3/3 3/3
テストを追加した 1/3 3/3 3/3
npm test を実行して確かめた 1/3 3/3 3/3
CHANGELOG.md に1行追記した 0/3 3/3 3/3
かかった時間(3回の範囲) 7.0〜8.9秒 11.0〜16.2秒 8.9〜12.5秒

書いた内容は次のとおりです。

  • あいまい:「テストはちゃんと書く」「変更内容は記録しておく」「コードはきれいに保つ」の3行
  • 具体的:「関数を追加したら test/price.test.js に node:test のテストを1件以上追加する」「作業の最後に必ず npm test を実行し、成功を確認してから終える」「CHANGELOG.md の『## Unreleased』の下に、日本語で1行追記する」の3行

CLAUDE.mdがないと、関数は正しく書けても、テストの追加と変更履歴は抜けました。決まりを書いておく効果ははっきり出ています。

予想と違った結果:あいまいでも差が出なかった

編集部は「具体的に書いたほうが守られる」と予想していましたが、今回の課題ではあいまいな3行でも具体的な3行と同じ結果になりました。あいまいな3回は、作業の途中で CHANGELOG.md とテストのフォルダを自分で開き、「記録する」を「CHANGELOG.md に書く」と読み替えていました。手がかりになるファイルがすでにある小さなプロジェクトだったため、あいまいな指示でも迷わなかったと考えられます。

以前 Codex CLI で同じような比較をしたAGENTS.mdの検証では、あいまいに書いた場合は書かない場合と結果が変わりませんでした。ツールもモデルも課題も違うため、どちらが一般的とは言えません。記録の書き場所が複数ある、テストのコマンドが特殊、といった実際のプロジェクトでは、具体的に書いておくほうが安全です。

そのまま使えるCLAUDE.mdのテンプレート

/init の下書きに足す形を想定した、短いテンプレートです。〈〉の部分を自分のプロジェクトに合わせて書き換えてください。

# プロジェクトの指示

## コマンド
- テスト: `npm test`(1ファイルだけなら `node --test test/〈ファイル名〉`)
- 確認: 作業の最後に必ず `npm test` を実行し、成功を確認してから終える

## 決まり
- 関数を追加・変更したら、test/ にテストを1件以上追加する
- CHANGELOG.md の「## Unreleased」の下に、日本語で1行追記する
- 〈触ってはいけないフォルダ〉は変更しない。必要なら変更せずに報告する

## 構成
- 〈フォルダ名〉: 〈そのフォルダの役割を1行で〉

<!-- 人間向けのメモ:この行はClaudeには渡らない -->

最後の行のような <!-- --> のHTMLコメントは、Claudeに渡す前に取り除かれます。編集部の実測でも、コメントの中に入れた合言葉は3回とも記録に入っていませんでした。人間の担当者向けの補足を、AIの文脈を使わずに残せます。

AGENTS.mdと併用するときの3つの書き方

CodexやCursorとClaude Codeを同じリポジトリで使うなら、指示の本体はAGENTS.mdに1つだけ書き、Claude Codeからはそれを読ませるのが楽です。

方法 書き方 向いている場面 注意
CLAUDE.mdを置かない AGENTS.md だけを置く Claude専用の指示がない v2.1.277以降が必要。CLAUDE.local.md を作ると読まれなくなる
CLAUDE.mdから取り込む CLAUDE.mdに @AGENTS.md と書き、下にClaude専用の指示 Claude専用の指示もある 取り込んだ分も文脈を使う
シンボリックリンク ln -s AGENTS.md CLAUDE.md Claude専用の指示がなく、Windowsを使う人がいない 公式は、Windowsでは管理者権限か開発者モードが必要で、Gitの設定によっては1行のテキストになるとしている

@ の取り込みには細かい決まりがあります。パスはそのCLAUDE.mdから見た位置で、取り込みの中の取り込みは4段まで。バッククォートで囲んだ `@NOTES.md` は取り込まれず、文字のまま残ります(編集部の実測でも NOTES.md の中身は3回とも入りませんでした)。プロジェクトの外のファイルを取り込むと、最初に承認の画面が出ます。

CLAUDE.mdで気をつけること

  • 秘密の情報を書かない。 CLAUDE.mdはGitでチームと共有するファイルです。APIキーやパスワードは書かず、環境変数で渡します(MCPの設定での渡し方はClaude CodeのMCP設定方法)。
  • 他人のCLAUDE.mdをそのまま信用しない。 CLAUDE.mdやAGENTS.mdはAIへの指示そのものなので、悪意のある指示を混ぜることもできます。ダウンロードしたリポジトリでは、中身を読んでから作業させてください(実例はAGENTS.md攻撃とは、考え方はプロンプトインジェクションの対策)。
  • 長くしすぎない。 長いファイルは文脈を多く使い、守られにくくなると公式は説明しています。@ で分けても、取り込んだ分は一緒に読み込まれるので節約にはなりません。節約したいなら paths: 付きのルールか、必要なときだけ読まれるスキルに移します。
  • 矛盾を残さない。 2つの指示が食い違うと、Claudeはどちらかを選びます。ルートとサブフォルダのCLAUDE.md、.claude/rules/ を時々見直します。

まだ確かめていないこと

  • 今回の実行はすべて claude -p(画面を使わない実行)とhaikuのモデルです。対話の画面や、Sonnet・Opusでは試していません。
  • 書き方のテストは、ファイルが4つの小さなプロジェクトで1つの課題だけです。大きなリポジトリや、指示が200行を超える場合の守られ方は測っていません。
  • /compact(会話の圧縮)の後に指示が残るか、Windowsでのシンボリックリンクの動きは、公式ドキュメントの記載で、今回は実行していません。

Claude Codeの料金やプランの選び方はClaude Codeの料金、Codexとの違いはCodexとClaude Codeの比較にまとめています。社内でAIコーディングツールを入れるか、どの業務から試すかで迷っている場合は、AI活用診断で今の業務に合う使い方を確かめられます。

よくある質問

Q. CLAUDE.mdはどこに置けばいいですか?

プロジェクトのルートに CLAUDE.md(または .claude/CLAUDE.md)として置きます。自分だけの指示は CLAUDE.local.md にして .gitignore に入れ、すべてのプロジェクトに効かせたい好みは ~/.claude/CLAUDE.md に書きます。起動したフォルダより上の階層のCLAUDE.mdはすべて読まれ、下の階層のものはそのフォルダのファイルを開いたときに読まれます。

Q. Claude CodeはAGENTS.mdを読みますか?

v2.1.277以降は、CLAUDE.mdとCLAUDE.local.mdがないフォルダならAGENTS.mdを読みます。編集部の実測(Claude Code 2.1.321)では、AGENTS.mdだけのフォルダで3回とも読まれ、CLAUDE.mdかCLAUDE.local.mdを並べると3回とも読まれませんでした。両方読ませたいときは、CLAUDE.mdに @AGENTS.md と書くか、/config の Project instructions を claude-md-and-agents-md にします。

Q. CLAUDE.mdには何を書けばいいですか?

テストやビルドのコマンド、フォルダの役割、チームの決まりなど、毎回説明し直していることです。まず /init で下書きを作り、コードを読んでも分からない決まりだけを足します。「テストはちゃんと」ではなく「最後に npm test を実行する」のように、確かめられる形で書きます。

Q. CLAUDE.mdを書いたのに守られません。

まず /context all で、ファイルが「Memory files」に出ているかを確かめます。出ていなければ置き場所の問題です。出ているのに守られないなら、書き方をより具体的にするか、長いファイルを分けます。CLAUDE.mdは強制ではないため、絶対に止めたい操作はフックや権限の設定で止めます。

Q. CLAUDE.mdは何行くらいがいいですか?

公式ドキュメントは1ファイル200行未満を目安にしています。長いほど文脈を使い、守られにくくなるためです。一部のファイルにだけ関係する決まりは .claude/rules/ に paths: 付きで分けると、関係するファイルを扱うときだけ読み込まれます。

Q. CLAUDE.mdに人間向けのメモを書いてもいいですか?

<!-- --> のHTMLコメントに書けば、Claudeに渡す前に取り除かれます。編集部の実測でも、コメント内の文は3回とも読み込まれませんでした。ただし、コードブロックの中のコメントは残ります。

確認元(2026-11-16 確認)

仕様は変わることがあるため、最新情報は公式で確認してください。取得日はいずれも2026年11月16日(日本時間)です。

自社の業務にどのAIツールの使い方が合うか、約3分で確かめる

全8問に答えると、AI 導入の準備度と、最初に試す活用アイデアがわかります。無料・登録不要です。

関連記事

すべてを表示