CLAUDE.md は Claude Code が毎回のセッションの最初に読む指示ファイルです。ビルドコマンドや独自の規約など「コードを読んでもわからないこと」だけを 200 行以内で書きます。Codex などが読む AGENTS.md とは、v2.1.277 以降の Claude Code なら AGENTS.md だけで済ませるか、CLAUDE.md に @AGENTS.md と書いて共有できます。
SNSでシェアして、他のエンジニアにも教えてあげましょう
CLAUDE.md は、Claude Code が毎回のセッションの最初に読み込む指示ファイルです。ビルドやテストのコマンド、チーム独自の規約、ハマりやすい点など「コードを読んでもわからないこと」だけを、1 ファイル 200 行以内で書くのが公式の目安です12。Codex などが読む AGENTS.md とは、2026 年 10 月時点の Claude Code（v2.1.277 以降）なら AGENTS.md だけで済ませることも、CLAUDE.md に @AGENTS.md と書いて 1 つのファイルを共有することもできます1。この記事では、CLAUDE.md の置き場所と読み込まれる順番、書くこと・書かないこと、良い例と悪い例、AGENTS.md との違いと併用方法を、実際に Claude Code v2.1.289 で動かした結果とともにまとめます。
CLAUDE.md は、プロジェクトや自分の作業のやり方を Claude に覚えておいてもらうための Markdown ファイルです。Claude Code のセッションは毎回まっさらなコンテキストから始まるので、毎回伝えたいことをここに書きます1。
大事な前提が 1 つあります。CLAUDE.md は「指示」であって、強制される設定ではありません。CLAUDE.md の中身はシステムプロンプトのあとにユーザーメッセージとして渡され、Claude はそれを読んで従おうとします。ただし、必ず守られる保証はありません1。「コミット前に必ず lint する」のように絶対に実行させたいことは hooks に、特定のコマンドを禁止したいことは権限設定（permissions.deny）に書きます1。
Claude Code には、CLAUDE.md とは別に「自動メモリ」もあります。違いは次のとおりです1。
| CLAUDE.md | 自動メモリ | |
|---|---|---|
| 書く人 | 自分 | Claude |
| 中身 | 指示とルール | 学んだことや好み |
| 範囲 | プロジェクト・ユーザー・組織 | リポジトリごと（worktree で共有） |
| 読み込み | 毎回のセッション | 毎回（MEMORY.md の先頭 200 行か 25KB まで） |
「pnpm を使って」と会話で頼むと、Claude はそれを自動メモリに保存します。チームで共有したいルールなら「CLAUDE.md に追加して」と頼むか、自分で書きます1。
2026 年 9 月 18 日公開の Claude Code v2.1.277 で、AGENTS.md を直接読めるようになりました。CLAUDE.md の無いプロジェクトでは、AGENTS.md がプロジェクトの指示として読み込まれます3。続く v2.1.281（2026 年 9 月 23 日公開）で、Amazon Bedrock や Google Vertex AI、テレメトリを切ったセッションでも使えるようになりました3。
AGENTS.md は、OpenAI Codex・Google Jules・Cursor・Factory などが共同で整えた、コーディングエージェント向けの共通の指示ファイルです。公式サイトによると 6 万以上のオープンソースプロジェクトで使われ、いまは Linux Foundation の Agentic AI Foundation が管理しています4。Claude Code と Codex を同じリポジトリで使い分けるチームが増えたいま、「同じことを 2 つのファイルに書く」状態を解消できるようになったわけです。
検索の関心も、Claude Code と Codex の両方に向いています。Google トレンド（日本・過去 90 日）で同じ回に取得した相対値を比べると、直近 4 週は Codex が 35.3、Claude Code が 22.2 でした5。
| 期間 | Claude Code | Codex |
|---|---|---|
| その前 8 週の平均 | 32.8 | 41.9 |
| 直近 4 週の平均 | 22.2 | 35.3 |
どちらも前の 8 週よりは下がっていますが、Codex の関心は Claude Code より高い水準にあります。同じ期間に「claude code モデル 変更」（+140%）や「claude code リモート」（+120%）が急上昇の関連キーワードに入っていました5。ツールやモデルを切り替えながら使う人が多いほど、指示ファイルを 1 つにまとめる意味は大きくなります。
CLAUDE.md は、置く場所で範囲が変わります。下の表は、広い範囲から順に、読み込まれる順番で並べています1。
| 範囲 | 場所 | 用途 | 共有相手 |
|---|---|---|---|
| 組織の管理ポリシー | macOS: /、Linux: / | 会社のコーディング規約やセキュリティ方針 | 組織の全員 |
| ユーザー | ~/ | 全プロジェクト共通の自分の好み | 自分だけ |
| プロジェクト | ./ か ./ | 構成、規約、よく使う手順 | git でチーム全員 |
| ローカル | ./（.gitignore に入れる） | 自分用のサンドボックスの URL など | 自分だけ |
読み込みには 3 つの決まりがあります1。
foo/ で起動すると、foo/ と foo/ の両方が読まれます。上書きではなく連結されますCLAUDE.local.md が CLAUDE.md の後です読み込まれたかどうかは、セッション中に / を実行し、Memory files の一覧で確かめます1。
公式のベストプラクティスには、書くべきことと書かないことの表があります2。判断の基準は 1 つで、各行について「これを消したら Claude は間違えるか？」と問うことです。間違えないなら消します2。
| 書く | 書かない |
|---|---|
| Claude が推測できない Bash コマンド | コードを読めばわかること |
| 既定と違うコードスタイル | 言語の標準的な書き方 |
| テストの手順と使うテストランナー | 詳しい API ドキュメント（リンクにする） |
| ブランチ名や PR の決まりごと | 頻繁に変わる情報 |
| そのプロジェクト特有の設計判断 | 長い説明やチュートリアル |
| 必要な環境変数などの開発環境の癖 | ファイルごとの説明 |
| ハマりやすい点、直感に反する挙動 | 「きれいなコードを書く」のような当たり前のこと |
指示は、確かめられるくらい具体的に書きます。公式の例では、「コードを整形する」ではなく「インデントは 2 スペース」、「変更をテストする」ではなく「コミット前に npm test を実行する」と書くよう勧めています1。
公式の目安は、CLAUDE.md 1 ファイルあたり 200 行以内です。長いほどコンテキストを使い、守られにくくなります1。ベストプラクティスでも「CLAUDE.md が長すぎると、Claude は半分を無視する」と書かれています2。4 MiB を超えるファイルは読み込まれません1。
長くなってきたら、次の 3 つで減らします。
.claude/ に paths 付きで移す（後述）/ で、コードから導ける内容の削除案を出してもらえる1強調は使いすぎないことも大切です。どうしても守られない 1 行にだけ「IMPORTANT」を付け、多くの行に付けないよう公式は勧めています2。
CLAUDE.md の中に @パス と書くと、そのファイルが起動時に展開されて読み込まれます1。
プロジェクトの概要は @README.md、使える npm コマンドは @package.json を参照。
# 追加の指示
- git の運用ルール @docs/git-instructions.md
インポートの決まりは次のとおりです1。
`@README` やコードブロックの中は、インポートされない@~/ など）を初めて読むときは、承認のダイアログが出る注意点として、インポートは整理には役立ちますが、コンテキストは減りません。インポートしたファイルも起動時にすべて読み込まれるからです1。
大きなプロジェクトでは、.claude/ にテーマごとの Markdown を置けます。paths を付けたルールは、Claude がそのパターンに合うファイルを読み書きしたときだけ読み込まれます1。
---
paths:
- "src/api/**/*.ts"
---
# API 開発のルール
- すべてのエンドポイントで入力を検証する
- エラーは共通のレスポンス形式で返す
悪い例は、誰でも知っていることや、コードを読めばわかることが並んでいる CLAUDE.md です。
# プロジェクトについて
このプロジェクトは Next.js で作られた Web アプリです。
src/ にソースコードがあり、components/ にコンポーネントがあります。
# ルール
- きれいなコードを書くこと
- テストを書くこと
- IMPORTANT: セキュリティに気をつけること
- IMPORTANT: パフォーマンスに気をつけること
ディレクトリの説明はコードから読み取れます。「きれいなコード」「気をつける」は確かめようがありません。IMPORTANT も多すぎて、どれも目立ちません。
良い例は、推測できないコマンドと、守れたか確かめられるルールだけを短く書いたものです。
# コマンド
- 型チェック: `pnpm tsc --noEmit`（変更をまとめたら必ず実行）
- テスト: `pnpm vitest run <ファイル>`（全体実行は CI に任せる）
- DB のマイグレーション: `pnpm db:migrate`（本番には実行しない）
# 規約
- API のハンドラは `src/api/handlers/` に置く
- 日付は UTC で保存し、表示するときに JST に変換する
- 依存の追加は pnpm を使う（npm と yarn は使わない）
# ハマりやすい点
- `.env.local` が無いと E2E テストがタイムアウトする。`.env.example` を写して作る
最初の CLAUDE.md は、/ で作るのが早道です。Claude がコードベースを調べて、ビルドコマンドやテストの手順を書き出します。すでに CLAUDE.md があれば、上書きせずに改善案を出します1。
AGENTS.md は「エージェントのための README」です。決まった項目は無く、ただの Markdown です4。CLAUDE.md と考え方は同じですが、読むツールと細かい決まりが違います。
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| 主に読むツール | Claude Code | Codex、Jules、Cursor、Gemini CLI、GitHub Copilot のコーディングエージェントなど4 |
| 個人用の全体設定 | ~/ | Codex は ~/7 |
| 個人用のローカル版 | CLAUDE.local.md | 仕様には無い。Codex は AGENTS.override.md で上書き7 |
| サブディレクトリ | 下の階層は必要になったときに追加 | 編集するファイルに最も近いものが優先4 |
| 別ファイルの取り込み | @パス で展開される | 仕様には無い |
| 大きさの目安 | 1 ファイル 200 行以内を推奨1 | Codex は合計 32 KiB で読み込みを止める（既定）7 |
Claude Code が AGENTS.md を読むときは、AGENTS.local.md・AGENTS.override.md・.agents/ 以下は読みません1。Codex 向けに AGENTS.override.md で上書きしていても、Claude Code には伝わらない点に注意してください。
公式ドキュメントで確認できた方法は 3 つです1。
いちばん簡単なのは、CLAUDE.md を置かず AGENTS.md だけにする方法です。作業ディレクトリとその上に CLAUDE.md・.claude/・CLAUDE.local.md が無ければ、Claude Code は AGENTS.md をプロジェクトの指示として読みます1。
ここで落とし穴があります。CLAUDE.local.md も「CLAUDE.md がある」と数えられます。自分用のメモのつもりで CLAUDE.local.md を作ると、AGENTS.md が読まれなくなります1。~/ や .claude/ は数えられないので、こちらは一緒に読まれます。
Claude Code だけに伝えたい指示があるなら、AGENTS.md の隣に CLAUDE.md を置き、1 行目で取り込みます。Claude は取り込んだ AGENTS.md を先に読み、そのあとの Claude 向けの指示を読みます1。
@AGENTS.md
## Claude Code
- `src/billing/` を変えるときはプランモードで計画を見せてから編集する
下の GIF は、AGENTS.md だけのリポジトリと、上の CLAUDE.md を足したあとで、指示の中身を質問した結果です（実際の出力）。後半では、テストのコマンドは AGENTS.md から、billing のルールは CLAUDE.md から読んだと答えています。
この方法は、AGENTS.md を直接読めないセッション（v2.1.277 より前など）でも動きます。取り込みと直接の読み込みが重なっても、AGENTS.md が 2 回読まれることはありません1。
Claude 向けの追加の指示が要らないなら、シンボリックリンクでも構いません1。
ln -s AGENTS.md CLAUDE.md
成功しても何も表示されません。ただし公式は 2 つの注意点を挙げています1。
AGENTS.md を編集するよう促されるcore.symlinks が無効だと、Git はリンクを 1 行のテキストファイルとして取り出す。Windows の人がいるなら方法 2 にするAGENTS.md の公式サイトも、既存のファイルを AGENTS.md に移してリンクを張る方法を紹介しています4。
CLAUDE.md と AGENTS.md の両方を常に読ませたいときは、/ の Project instructions を claude-md-and-agents-md にします1。設定ファイルに書く場合は、ユーザー設定（~/）か管理設定に次のように書きます。プロジェクトの設定ファイルに書いても無視されます1。
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
逆向きに、Codex に既存のファイルを読ませる設定もあります。Codex の ~/ の project_doc_fallback_filenames にファイル名を足すと、AGENTS.md が無いディレクトリでそのファイルを指示として扱います7。ただし、Codex は 1 つのディレクトリから 1 ファイルしか読みません7。両方のツールで同じ内容を使うなら、AGENTS.md を正本にして、Claude Code 側で取り込むほうが管理しやすいでしょう。Codex と Claude Code の違いは「Codex CLI と Claude Code の比較」でも整理しています。
公式は、次の順に確かめるよう勧めています1。
/ の Memory files に、そのファイルが出ているか/ を実行すると、古いモデル向けの書き方や存在しないファイルへの参照、ファイル間の矛盾を Claude が探して報告します（v2.1.283 以降）1。
原因の多くは、作業ディレクトリかその上にある CLAUDE.md（CLAUDE.local.md を含む）です。それでも直らなければ、claude --version で v2.1.277 以降か確かめます。さらに / で Project instructions が claude-md や managed-only になっていないかを見ます1。
プロジェクトのルートの CLAUDE.md は、圧縮のあとにディスクから読み直されます。消えたように見える指示は、会話の中でだけ伝えたものか、まだ読み直されていないサブディレクトリの CLAUDE.md や paths 付きのルールです1。残したい指示は CLAUDE.md に書きます。
複数の手順からなる作業や、一部でしか使わない知識は、スキルやサブエージェントに移します。使い分けは「Claude Code スキルの作り方」と「Claude Code サブエージェントの作り方と使い分け」で解説しています。
@パス で分けられるが、コンテキストは減らない。減らすなら paths 付きの rules かスキル@AGENTS.md と書くのが、Windows でも動いて確実次にやることとして、いまの CLAUDE.md を開き、各行に「消したら Claude は間違えるか？」と問いかけて削ってみてください。
Claude Code しか使わないなら CLAUDE.md だけで十分です。Codex などほかのエージェントも使うなら、AGENTS.md を正本にします。そのうえで、Claude 向けの指示がある場合だけ CLAUDE.md に @AGENTS.md と書くのがおすすめです1。
公式の目安は 1 ファイルあたり 200 行以内です1。超えると起動時や / で警告が出ます。長くなったら、一部のファイルにしか関係しない指示を .claude/ に、手順をスキルに移します。
/ を実行すると、Claude がコードベースを調べてビルドコマンドやテストの手順を含む CLAUDE.md を作ります1。Cursor のルールや .github/ があれば、その内容も取り込みます。
プロジェクトのルートに CLAUDE.local.md を作り、.gitignore に追加します1。全プロジェクト共通の好みなら ~/ に書きます。AGENTS.md だけで運用しているリポジトリで CLAUDE.local.md を作ると、AGENTS.md が読まれなくなる点に注意してください。
AGENTS.md の仕様には、決まった項目もインポートの書き方もありません4。ただし Claude Code が AGENTS.md を読むときは、その中の @パス を CLAUDE.md と同じように展開します1。ほかのツールでも同じように展開されるとは限りません。
How Claude remembers your project — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18 ↩19 ↩20 ↩21 ↩22 ↩23 ↩24 ↩25 ↩26 ↩27 ↩28 ↩29 ↩30 ↩31 ↩32 ↩33 ↩34 ↩35 ↩36 ↩37 ↩38 ↩39
Best practices for Claude Code（Write an effective CLAUDE.md） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5
Claude Code CHANGELOG（2.1.277・2.1.281） — Anthropic, GitHub（公開日は npm レジストリの記録: v2.1.277 が 2026-09-18、v2.1.281 が 2026-09-23）（2026-10-05 参照） ↩ ↩2
AGENTS.md — AGENTS.md（Agentic AI Foundation / Linux Foundation）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6
Google トレンド「Claude Code」「Codex」（日本・過去 90 日） — Google, 2026-10-05 取得（2026-10-05 参照） ↩ ↩2
Extend Claude Code（CLAUDE.md vs Skill） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩
Custom instructions with AGENTS.md — OpenAI（Codex ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5