CLAUDE.md と AGENTS.md：Claude Code に毎回読ませる指示ファイル

ハンズオンでは、最初に「ベース名を AGENTS.md に記録して、CLAUDE.md からは AGENTS.md を読み込むようにして」と頼む。こうしてできる AGENTS.md と CLAUDE.md は、Claude Code がセッションを始めるたびに読む指示ファイル。会話が長くなっても、セッションを開き直しても、書いたことを毎回読み直す。

指示ファイルにはもう1つ、すべてのプロジェクトに効く ~/.claude/CLAUDE.md がある。この記事では、3つの違いと使い分けをまとめる。

1. 3つの指示ファイル

• プロジェクトの CLAUDE.md：そのフォルダでの作業に効く。Claude Code が読む。git に乗るので、clone すれば別のマシンにも付いてくる
• AGENTS.md：そのフォルダでの作業に効く。Codex などが読み、Claude Code も条件つきで読む（→ §3）。git に乗るので、clone すれば別のマシンにも付いてくる
• ~/.claude/CLAUDE.md：すべてのプロジェクトに効く。Claude Code が読む。git に乗らないので、マシンごとに置く

3つとも、セッションを始めるときにまるごと読み込まれる。書いたことが毎回効く代わりに、書いた分だけ毎回読む量が増える。指示ファイルは短く保ち、調べたことや判断の経緯は別のファイルに置く（→ IRN）。

2. プロジェクトの CLAUDE.md

作業フォルダ直下に CLAUDE.md を置いておくと、そのフォルダで始めたセッションに自動で読み込まれる。そのプロジェクトだけのルールを残せる。

例：

# このプロジェクトについて

- 公開ファイルは public/ 配下に置く
- デプロイは npx wrangler deploy を使う（設定は wrangler.jsonc）
- スタイルは Tailwind ではなく素のCSSで書く
- コメントは日本語、コードは英語の変数名

セッションをまたいでも同じルールが適用されるので、毎回同じ指示を書かずに済む。

ハンズオンで、最初にベース名やアプリの仕様を指示ファイルに書かせているのも同じ理由。以降のプロンプトでは「仕様のとおりに」と言うだけで、Claude が指示ファイルを見て作業する。書き先を CLAUDE.md ではなく AGENTS.md にしている理由は §3 にある。

/init コマンドを使うと、作業フォルダの中身から CLAUDE.md のひな形を作ってくれる。作ったあとは、自分の好みに合わせて書き直す。

3. AGENTS.md と CLAUDE.md

3-1. Claude Code が AGENTS.md を読む条件

AGENTS.md は、Codex など多くのコーディングエージェントが読む指示ファイル。Claude Code も v2.1.277（2026年9月）から読むようになった。

ただし既定で読むのは、作業フォルダとその上の階層に CLAUDE.md や CLAUDE.local.md などが無いときだけ。どちらかがあれば、CLAUDE.md のほうだけを読む。

AGENTS.md だけのフォルダなら、そのまま読まれる（公式ドキュメントも、CLAUDE.md も import も設定も要らないと書いている）。困るのは、あとから CLAUDE.md ができたとき。「仕様を CLAUDE.md に書いて」と頼んで新しく作られると、その時点から AGENTS.md は読まれなくなる。エラーも出ないので、そうなったことに気づきにくい。

3-2. AGENTS.md を実体にして CLAUDE.md から読み込む

そこで、ルールの実体は AGENTS.md に置き、CLAUDE.md には次の1行だけを書いておく。

@AGENTS.md

@ に続けてファイル名を書くと、Claude Code は起動時にそのファイルを読み込む（import）。Claude Code は CLAUDE.md を通して、Codex などは直接、同じ AGENTS.md を読む。CLAUDE.md が先にあるので、あとから「CLAUDE.md に書いて」と頼んでも、AGENTS.md が読まれなくなることはない。Claude Code だけに読ませたい指示があれば、この1行の後ろに足せる。

すでに CLAUDE.md にルールを書いているなら、頼めば移してくれる。

プロンプト

CLAUDE.md の中身を AGENTS.md に移して、CLAUDE.md からはそれを読み込むようにして

3-3. シンボリックリンクは使わない

2つのファイルをシンボリックリンク（symlink）でつなぐ方法もあるが、このサイトでは使わない。理由は2つ。

• Claude Code の編集機能はリンクを通しては書き込まないので、ルールを直すときはリンク先のファイルを直すことになる
• Windows ではリンクを作るのに管理者権限か開発者モードが要る。Git の設定によっては、clone した側で中身がリンク先の名前1行だけのファイルになる

公式ドキュメントも、Windows の人と共有するなら import を使うよう書いている（→ CLAUDE.md のドキュメント）。

4. ~/.claude/CLAUDE.md

4-1. すべてのプロジェクトに効く

~ はホームフォルダのこと。~/.claude/CLAUDE.md に書いたことは、どのフォルダで始めたセッションにも読み込まれる。作業フォルダに AGENTS.md しか無い場合も、これは一緒に読まれる。

便利な反面、気をつけることが3つある。

• リポジトリの外にあるので git に乗らない。別のマシンには付いてこないので、マシンごとに書くことになる
• 名前が . で始まるフォルダは、Finder では普段表示されない。目に入らないので、何を書いたか忘れやすい
• すべてのプロジェクトに効くので、あるプロジェクトのつもりで書いたルールが、別のプロジェクトの作業にも混ざる

4-2. 中身を確かめる

テキストエディットで開いて見るのが早い。

プロンプト

~/.claude/CLAUDE.md をテキストエディットで開いて

自分でターミナルに打つならこう。

open -e ~/.claude/CLAUDE.md

-e は「テキストエディットで開く」という指定。付けないと、.md に割り当たっている別のアプリが起動することがある。

ファイルが無いと「存在しない」という意味のエラーになる。その場合は、何も書かれていない。

Windows の場合

Windows では、スタートメニューから コマンドプロンプト を開き、次の1行を打つとメモ帳で開く。

notepad %USERPROFILE%\.claude\CLAUDE.md

自分で開いたコマンドプロンプトで打つこと。Claude Code の中のターミナルでは、使われるシェルが PowerShell だったり Git Bash だったりして、%USERPROFILE% が展開されないことがある。

4-3. 安全ルールを書くと、プロンプトでは消せないことがある

~/.claude/CLAUDE.md に安全に関わるルール（「〜は絶対にしない」の類）を書くと、あとで「この部分を消して」と頼んでも、Claude が断ることがある。守るよう指示されている安全ルールを消せ、という依頼に見えて止まるようだ。

2026年8月のハンズオンの会でこれが起きた。コミュニティで配られていた安全ルール（「〜は絶対にしない」のような文のまとまり）を ~/.claude/CLAUDE.md に入れていた参加者に、外してもらおうとしたところ、その場の全員が、頼んでも消せなかった。同じ月の初めには「消す」ではなく「別のルールに置き換える」という頼み方で通っていたが、それも通らなくなっていた。結局、テキストエディットで開いて手で消した。

プロンプトで消せないことがあるので、ここに安全ルールを入れたら、外すときはテキストエディタで手で消す前提にしておく。開き方は §4-2 と同じ（Windows は §4-2 の注記）で、開いたら該当する部分を選んで削除し、保存する。次のセッションから外れる。

4-4. 書いてよいもの

向いているのは、どのプロジェクトでも同じでよい自分の好み。

• 返事は日本語で書く
• git push は、指示があるまで待つ
• コマンドを実行する前に、何をするのかを一言説明する

そのプロジェクトだけのルールは、プロジェクトの指示ファイルに書く。

5. 何をどこに書くか

• このプロジェクトのルール・仕様・名前：AGENTS.md に書き、CLAUDE.md は @AGENTS.md の1行（→ §3）。Claude Code しか使わないなら CLAUDE.md に直接書いてもよい
• どのプロジェクトでも同じでよい自分の好み：~/.claude/CLAUDE.md（→ §4）
• 安全に関わるルール：~/.claude/CLAUDE.md に入れると、外すときに手作業になる（→ §4-3）。公開したアプリの点検は CHK
• 調べたこと・判断の経緯：notes/（→ IRN）