CLAUDE.md の書き方と置き場所、AGENTS.md との関係
先に結論
- CLAUDE.md は、Claude Code が毎回のセッションの最初に読む Markdown ファイルです。毎回説明し直している内容を書いておく場所です。
- プロジェクト用は
./CLAUDE.mdか./.claude/CLAUDE.mdに置いて、Git にコミットします。全プロジェクト共通の決まりは~/.claude/CLAUDE.mdに書きます。 - 短く保ちます（公式は1ファイル200行未満を目安にしています）。Claude が推測できないコマンド、チームの決まり、ハマりどころを書きます。
- リポジトリに
AGENTS.mdがあって CLAUDE.md が無ければ、Claude Code v2.1.277 以降はAGENTS.mdを読みます。両方あると CLAUDE.md だけを読みます。@AGENTS.mdで取り込むか、設定を変えれば両方使えます。
CLAUDE.md の置き場所
CLAUDE.md は何か所かに置けます。読み込みは、範囲の広いものから狭いものの順です。
| 範囲 | 場所 | 用途 | 共有される相手 |
|---|---|---|---|
| 組織（管理者が配る） | Linux/WSL: /etc/claude-code/CLAUDE.md、macOS: /Library/Application Support/ClaudeCode/CLAUDE.md、Windows: C:\Program Files\ClaudeCode\CLAUDE.md | 会社全体の決まり | そのマシンの全員 |
| ユーザー | ~/.claude/CLAUDE.md | 自分の好み（全プロジェクト共通） | 自分だけ |
| プロジェクト | ./CLAUDE.md または ./.claude/CLAUDE.md | このリポジトリのチームの決まり | チーム（Git 経由） |
| ローカル | ./CLAUDE.local.md（.gitignore に追加） | このプロジェクトでの自分用メモ（試験環境の URL など） | 自分だけ |
読み込みのしくみ:
- 起動したフォルダと、その上にあるすべてのフォルダから CLAUDE.md と CLAUDE.local.md を読みます。
- 上書きはされません。全部つなげて読まれます。起動したフォルダに近いファイルほど後に読まれます。
- サブフォルダの CLAUDE.md は起動時には読まれません。Claude がそのサブフォルダのファイルを読んだり編集したりしたときに読まれます。
- 実際に読まれたファイルは
/contextの Memory files で確認できます。
大きなプロジェクトでは .claude/rules/ にファイルを分けられます。paths を指定したルールは、合うファイルを扱うときだけ読まれます。
書くこと
公式の方針は「毎回のセッションで必要な事実だけを書く」です。ビルドやテストのコマンド、決まりごと、構成、「いつも X する」というルールなどです。書くとよいもの:
- Claude が推測できない Bash コマンド
- 標準と違うコードの書き方
- テストの実行方法と、使うテストツール
- ブランチ名やプルリクエストの決まり
- このプロジェクト特有の設計判断
- 開発環境のクセ（必要な環境変数など）
- コードを見ても分からない落とし穴
ルールは確かめられる形で書きます。「きれいに整形する」より「インデントは2スペース」のほうが守られます。見出しと箇条書きでまとめます。
小さな例:
# コマンド
- ビルド: `npm run build`
- 1ファイルだけテスト: `npm test -- path/to/file.test.ts`
# コードの書き方
- ES modules（import/export）を使う。CommonJS（require）は使わない
- API ハンドラーは `src/api/handlers/` に置く
# 作業の流れ
- コミット前に `npm test` を実行する
- ブランチ名は `feature/<短い名前>`@path/to/file で別のファイルを取り込めます。たとえば CLAUDE.md に次の1行を書きます。
概要は @README を参照。@ の参照はそのまま書きます。バッククォートで囲んだ @パス は取り込まれません。相対パスは、取り込みを書いたファイルの場所が起点です。取り込みの入れ子は4段までです。取り込んだファイルも起動時に読まれるので、整理には役立ちますが読み込む量は減りません。
最初の下書きは /init で作れます。Claude がコードを見て CLAUDE.md のたたき台を書きます。すでにある場合は上書きせず、改善案を出します。
書かないこと
- 長い文書。 長いほど読み込む量が増え、守られにくくなります。詳しい API の説明は貼らずにリンクにします。
- コードを読めば分かること。 ファイルごとの説明や、言語の一般的な決まりなど。
- よく変わる情報。
- あいまいな心がけ。 「きれいなコードを書く」など。
- 手順の長い作業や、一部のコードだけの決まり。 スキルや
paths付きのルールに移します。 - 秘密情報（これは私たちのすすめです）。 プロジェクトの CLAUDE.md は Git で共有されるので、リポジトリを読める人は全員読めます。値は書かず、環境変数の名前や保管場所だけを書きます。
1行ごとに「これを消したら Claude は間違えるか？」と考え、間違えないなら消します。また、CLAUDE.md は「お願い」であって強制ではありません。毎回必ず実行したいことはフックにします。
AGENTS.md との関係
AGENTS.md は、ほかのコーディングエージェントが使う指示ファイルです。Claude Code の公式ドキュメントによると（直接読むには v2.1.277 以降が必要）:
| リポジトリの状態 | Claude が読むもの |
|---|---|
AGENTS.md があり、起動フォルダとその上に CLAUDE.md も CLAUDE.local.md も無い | AGENTS.md |
AGENTS.md と CLAUDE.md（または CLAUDE.local.md）の両方がある | CLAUDE.md だけ |
CLAUDE.md の中で @AGENTS.md を取り込んでいる | CLAUDE.md（AGENTS.md も取り込まれる） |
~/.claude/CLAUDE.md はこの判定に数えません。CLAUDE.local.md は数えるので、追加すると（初期設定では）AGENTS.md は読まれなくなります。
ツール間で1つのファイルを共有したいときは、AGENTS.md の隣に次の CLAUDE.md を置き、Claude 専用の指示はその下に書きます。
@AGENTS.md
## Claude Code
`src/billing/` の変更は plan mode で行う。読むファイルは /config の Project instructions でも変えられます（たとえば claude-md-and-agents-md で両方を読む）。
あとから直す
- セッション中に
/memoryを実行します。ユーザーとプロジェクトの CLAUDE.md、CLAUDE.local.md などが一覧で出ます。ユーザーとプロジェクトの CLAUDE.md は、まだ無くても一覧に出ます。選ぶとエディタで開き、無いファイルはその場で作られます。 - 全体用（グローバル）の CLAUDE.md を直すときは、
/memoryでユーザーのものを選ぶか、~/.claude/CLAUDE.mdを直接開きます。 - 「これを CLAUDE.md に追加して」と Claude に頼むこともできます。
/doctor prompt-audit（Claude Code v2.1.283 以降）で、古い指示や食い違う指示を探せます。直すよう頼むまでファイルは変わりません。- コードと同じように扱います。うまくいかないときに見直し、こまめに削ります。
- スマホなら、github.com でファイルを開き、鉛筆のマークから直してコミットすることもできます。
スマホやブラウザから直す（PlainHub）
プロジェクトの CLAUDE.md は Git リポジトリにある普通の Markdown ファイルです。ルールを直すのに、パソコンを開く必要はありません。PlainHub は、自分の GitHub リポジトリにある Markdown ファイルをブラウザで編集できるエディタです。スマホのブラウザでも使えます。保存するたびに Git のコミットになるので、履歴が残ります。ファイルは GitHub とブラウザの間でやり取りされ、PlainHub には保存されません。Claude Code を使っているなら、npm パッケージ plainhub の MCP サーバー（claude mcp add plainhub -- plainhub-mcp）で、Claude にファイルを PlainHub のエディタで開かせられます。
よくある質問
./CLAUDE.md と ./.claude/CLAUDE.md はどちらがよい？
どちらもプロジェクト用として使えます。どちらかに決めてコミットします。
CLAUDE.local.md はまだ使える？
使えます。現在の公式ドキュメントにも、自分用のプロジェクトメモとして ./CLAUDE.local.md が載っています。.gitignore に追加します。同じフォルダの CLAUDE.md の後に読まれます。
CLAUDE.md を書いたのに守ってくれない。何を確認する？
まず /context で読み込まれているか確認します。ルールを具体的にし、食い違うルールを消し、ファイルを短くします。サブフォルダの CLAUDE.md は、そのサブフォルダで作業するときだけ読まれます。
出典（Sources）
- https://code.claude.com/docs/en/memory
- https://code.claude.com/docs/en/best-practices
- https://code.claude.com/docs/en/mcp
Checked: 2026-10-20