CLAUDE.mdの書き方【2026年】例・置き場所・効かない原因

1. CLAUDE.mdとは

CLAUDE.mdは、Claude Codeに毎回伝えたいことを書いておくMarkdownファイルだ。Claude Codeのセッションは毎回まっさらな状態で始まるため、前回伝えたことは覚えていない。公式ドキュメントは、セッションをまたいで知識を引き継ぐ仕組みとして「CLAUDE.md」と「自動メモリ（auto memory）」の2つを挙げている（How Claude remembers your project）。

	CLAUDE.md	自動メモリ
書く人	利用者	Claude
中身	指示とルール	学んだことや傾向
範囲	プロジェクト・ユーザー・組織	リポジトリごと（ワークツリー間で共有）
読み込み	毎セッション（全文）	毎セッション（MEMORY.mdの先頭200行か25KBまで）
向いている内容	コードの書き方の決まり、作業の流れ、構成	利用者の好み、受けた指摘、コードからはわからない事情

押さえておきたいのは、CLAUDE.mdは「強制される設定」ではないという点だ。公式ドキュメントによると、CLAUDE.mdの中身はシステムプロンプトの一部ではなく、その後に「ユーザーメッセージ」として渡される。Claudeは読んで従おうとするが、あいまいな指示や矛盾した指示では、厳密に守られる保証はない。どんな判断をしても止めたい操作は、権限設定のdenyルールか、PreToolUseフックで止めるよう案内されている。権限設定の書き方はClaude Codeの権限設定【2026年】許可ルールとモードの決め方で扱う。

2. 置き場所と読み込まれる順番

CLAUDE.mdの置き場所は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	そのプロジェクトでの自分だけの設定（.gitignoreに追加）	自分だけ（このプロジェクト）

読み込みのルールは次のとおりだ（同ページ）。

• 起動時に読むのは、作業フォルダとその上の階層すべて。たとえば foo/bar/ で起動すると、foo/bar/CLAUDE.md と foo/CLAUDE.md、それぞれの横にあるCLAUDE.local.mdが読まれる。
• 順番は「広い範囲 → 狭い範囲」。組織、ユーザーの順に読まれ、ディレクトリはファイルシステムのルートから作業フォルダへ向かって並ぶ。起動した場所に近い指示ほど後に読まれる。同じフォルダでは、CLAUDE.mdの後にCLAUDE.local.mdが続く。
• サブフォルダのCLAUDE.mdは、必要になったときに読む。起動時には読まれず、Claudeがそのサブフォルダのファイルを読む・書く・編集したときに1回読み込まれる。
• HTMLコメントは渡されない。ブロック単位の <!-- メモ --> は、Claudeに渡す前に取り除かれる。人間向けのメモを、コンテキストを使わずに残せる（コードブロック内のコメントは残る）。

3. 作り方の手順（/initから始める）

最初の1本は、/initコマンドで下書きを作らせてから直すのが早い。公式ドキュメントによると、/initはコードベースを調べて、ビルドコマンド・テストの手順・見つけた決まりを書いたCLAUDE.mdを作る。すでにCLAUDE.mdがある場合は、上書きせずに改善案を出す。

1. プロジェクトのフォルダでClaude Codeを起動する。ターミナルでフォルダに移動し、claude と入力する（インストールがまだならClaude Codeのインストール方法を参照）。
2. /init を実行する。下書きのCLAUDE.mdが作られる。環境変数 CLAUDE_CODE_NEW_INIT を 1 にしてから実行すると、CLAUDE.md・スキル・フックのどれを用意するかを聞かれ、質問に答えながら提案を確認できる対話式の流れになる。
3. 下書きを読んで、コードを見ればわかることを削る。公式の /doctor の点検でも、ディレクトリ構成や依存関係の一覧、構成の概要のように「Claudeがコードから読み取れる内容」は削る候補とされ、落とし穴・理由・ツールの初期値と違う決まりは残すとされている。
4. Claudeが自分では見つけられないことを足す。「本番の設定ファイルには触らない」「コミット前に必ずこのコマンドを通す」のような、コードに書かれていない決まりだ。
5. 読み込まれたかを確かめる。セッションで /context all を実行し、「Memory files」の一覧にファイルが出ているかを見る。/memory からは、各CLAUDE.mdを開いて編集できる。
6. プロジェクトのCLAUDE.mdをGitにコミットする。チーム全員が同じ指示で動くようになる。自分だけの設定はCLAUDE.local.mdに書き、.gitignoreに追加する。

4. 書き方の原則（公式ドキュメントより）

守られるCLAUDE.mdにするコツは、「確かめられるほど具体的に、短く、矛盾なく」書くことだ。公式ドキュメントが挙げている言い換えの例は次のとおり。

あいまいな書き方	確かめられる書き方
コードをきれいに整形する	インデントはスペース2つ
変更をテストする	コミット前に npm test を実行する
ファイルを整理しておく	APIのハンドラーは src/api/handlers/ に置く

• 長さ：1ファイル200行未満が目安。長いほどコンテキストを使い、守られにくくなるとされる。一部のファイルにしか関係しない指示は、後述のパス指定ルールに移す。
• 構造：関連する指示を見出しと箇条書きでまとめる。詰め込んだ段落より従いやすいとされる。
• 一貫性：2つの指示が矛盾すると、Claudeはどちらかを任意に選ぶことがある。サブフォルダのCLAUDE.mdや.claude/rules/も含めて、古い指示・矛盾する指示を定期的に消す。
• 点検を任せる：/doctor prompt-audit を実行すると、古いモデル向けの指示、存在しないファイルやコマンドへの言及、ファイル同士の矛盾を探し、修正案を出す。指示しない限りファイルは変更されない（Claude Code v2.1.283以降）。
• 入れないもの：複数の段階がある手順や、コードベースの一部でしか使わない内容は、スキルかパス指定ルールに移すよう案内されている。また、プロジェクトのCLAUDE.mdはGitで共有される前提なので、APIキーやパスワードは書かない（これは公式の記載ではなく、共有されるファイルである以上の一般的な注意）。

5. CLAUDE.mdの書き方の例（記入例）

ここからは、上の原則に沿って作った記入例を4つ載せる。社名・パス・コマンドは自分の環境に置き換えて使う。

例1：Webアプリ開発のプロジェクト用（./CLAUDE.md）

# プロジェクトの決まり

## コマンド
- 開発サーバー：npm run dev
- テスト：npm test（コミット前に必ず実行し、失敗したらコミットしない）
- 型チェック：npm run typecheck

## コードの書き方
- TypeScriptで書く。インデントはスペース2つ
- APIのハンドラーは src/api/handlers/ に置く
- 新しい画面を作るときは src/components/ の既存部品を先に探す

## 触らないもの
- .env と config/production.* は読まない・書き換えない
- データベースのマイグレーションは、作成までにして実行はしない

## 作業の進め方
- 仕様があいまいなときは、作業を始める前に質問する
- 変更が終わったら、変えたファイルと確かめた方法を3行で報告する

例2：記事制作・マーケティング業務用（./CLAUDE.md）

Claude Codeはコードを書かない業務にも使える。その場合も、決まりと「やらないこと」を書く形は同じだ。

# 記事制作の決まり

## 書き方
- だ・である調。一人称は使わない
- 冒頭に結論を書き、各見出しの直後に答えを1〜2文で言い切る
- 比較は表にする

## 事実の扱い
- 料金・仕様・提供状況は公式サイトで確認できたものだけ書き、出典URLと確認日を付ける
- 確認できないことは「公式に記載なし」と書く。推測で数字を作らない

## やらないこと
- CMSへの投稿・公開はしない（下書きのファイルを作るところまで）
- 問い合わせフォームの送信はしない

## 納品
- 記事ごとに {slug}.html を作り、メモは 00_メモ.md にまとめる

例3：全プロジェクト共通の個人用（~/.claude/CLAUDE.md）

# 自分の好み（全プロジェクト共通）
- 返答と報告は日本語で書く
- パッケージ管理は npm ではなく pnpm を使う
- 長い作業は、始める前に手順を箇条書きで見せる

例4：自分だけのプロジェクト設定（./CLAUDE.local.md）

# ローカル用（Gitに入れない）
- 検証用のURLは http://localhost:3000 を使う
- テストデータは fixtures/sample-users.json を使う

例4のCLAUDE.local.mdは、同じリポジトリでもワークツリーごとに別ファイルになる点に注意したい。複数のワークツリーで同じ個人設定を使いたい場合、公式ドキュメントは、ホームフォルダに置いたファイルを @~/.claude/my-project-instructions.md のようにインポートする方法を紹介している。

6. 長くなったときの分け方

CLAUDE.mdが長くなったら、「毎回必要か」「一部のファイルだけか」「手順か」で置き場所を分ける。公式ドキュメントが用意している仕組みは次の4つだ。

@インポート：別のファイルを読み込ませる

CLAUDE.mdの中に @path/to/file と書くと、そのファイルが展開されて一緒に読み込まれる。相対パスは「作業フォルダ」ではなく「インポートを書いたファイル」からの位置になる。インポートしたファイルがさらにインポートすることもでき、深さは最大4段までだ。

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

注意点は3つある。1つ目に、インポートは整理には役立つが、コンテキストの節約にはならない。読み込んだ側と一緒に全部読まれるからだ。2つ目に、パスに空白がある場合は空白の前にバックスラッシュを付ける（@Design\ Docs/api-conventions.md）。引用符で囲んだパスはインポートされない。3つ目に、パスを書くだけでインポートしたくないときは、バッククォートで囲む。また、作業フォルダの外を指すインポートが初めて見つかったときは、承認のダイアログが出る。断ると、そのインポートは無効のままになる。

.claude/rules/：テーマ別・ファイル別に分ける

プロジェクトの .claude/rules/ フォルダに、testing.md や api-design.md のようにテーマごとのMarkdownを置ける。サブフォルダの中も含めて、すべての .md が見つけられる。先頭に paths を書かないルールは、起動時に .claude/CLAUDE.md と同じ優先度で読み込まれる。

先頭のYAMLに paths を書くと、そのパターンに合うファイルをClaudeが扱ったときだけ読み込まれる。

---
paths:
  - "src/api/**/*.ts"
---

# API開発のルール
- すべてのAPIエンドポイントで入力値を検証する
- エラーは共通の形式で返す

全プロジェクトで使う個人のルールは ~/.claude/rules/ に置く。ユーザーのルールはプロジェクトのルールより先に読まれるが、どちらかが優先されるわけではない。矛盾するとどちらに従うかわからないため、両方をそろえておく必要がある。

スキル：手順は必要なときだけ読ませる

公式ドキュメントは、毎回は必要ない作業手順は、呼び出したときやClaudeが関係すると判断したときだけ読み込まれる「スキル」にするよう勧めている。CLAUDE.mdやルールは毎回コンテキストに入るため、長い手順を置くと、ほかの作業でも容量を使い続けることになる。

7. AGENTS.mdとの関係（Codexなどと共用する場合）

Claude Codeは、ほかのコーディングエージェント向けの AGENTS.md も読める。ただし初期設定では、作業フォルダかその上の階層にCLAUDE.md（またはCLAUDE.local.md）が1つもないときだけ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のみ
AGENTS.mdをインポートしているCLAUDE.md	CLAUDE.md（インポート経由でAGENTS.mdも含む）

Codex CLIなどと同じ指示書を共有したいときは、CLAUDE.mdの先頭に @AGENTS.md と書き、その下にClaude Code向けの指示だけを足す方法が案内されている。両方を常に読ませたい場合は、/config の「Project instructions」を claude-md-and-agents-md に変える。ローカル用のCLAUDE.local.mdを1つ置いただけでAGENTS.mdが読まれなくなる点は、気づきにくいつまずきだ。Codex側の設定はCodex CLI使い方完全ガイドで扱っている。

8. 自動メモリ（auto memory）との使い分け

自動メモリとは、Claudeが利用者の指摘や好みをもとに、自分でメモを書きためる仕組みのことだ。ローカルのセッションでは初期設定でオンになっている。保存先はプロジェクトごとの ~/.claude/projects/<project>/memory/ で、索引の MEMORY.md と、テーマごとのファイルに分かれる。毎セッションで読み込まれるのは MEMORY.md の先頭200行か25KBのどちらか少ないほうまでで、テーマごとのファイルは必要なときに読まれる。

• チャットで「npmではなく必ずpnpmを使うと覚えて」と頼むと、自動メモリに保存される。
• CLAUDE.mdに書かせたいときは「これをCLAUDE.mdに追加して」と頼むか、/memory から自分で編集する。
• 自動メモリはマシンの中だけにあり、ほかのマシンやクラウド環境とは共有されない。チームで共有したい決まりは、CLAUDE.mdに書いてGitで配る。
• オフにするには /memory の切り替えを使う。プロジェクト単位では、そのプロジェクトの設定に "autoMemoryEnabled": false を書く。

9. 書いたのに守られない・読み込まれないときの対処

まず「読み込まれているか」を確かめ、次に「書き方」を疑う。公式ドキュメントのトラブルシューティングをもとに、確認の順番を整理する。

1. /context all で読み込みを確認する。「Memory files」にファイルがなければ、Claudeには見えていない。置き場所が読み込まれる場所か（2章の表）を確かめる。
2. サブフォルダのCLAUDE.mdは一覧に出ない。起動時ではなく必要なときに読まれるため、Memory filesには載らない。読み込まれると、ターミナルにパス付きの「Loaded」の行が出る。試すときは、シェルでファイルを作ってから、そのフォルダのファイルを読むようClaudeに頼む。
3. 指示を具体的にする。「きれいに整形」ではなく「インデントはスペース2つ」と書く。
4. ファイル同士の矛盾を探す。複数のCLAUDE.mdで同じことに違う指示があると、どちらかが任意に選ばれる。/doctor prompt-audit で探せる。
5. Claude Code自身の指示とぶつかっていないかを見る。コミットやプルリクエストの決まりを書いている場合は、設定の includeGitInstructions で組み込みの指示を切り、attribution で署名の文言を決めるよう案内されている。
6. 決まったタイミングで必ず動かしたいことは、フックにする。「コミット前に毎回」「ファイル編集のたびに」のような処理は、CLAUDE.mdではなくフックで、シェルコマンドとして実行させる。

よくある症状と原因

症状	原因と対処
/compactの後に指示が消えた	プロジェクト直下のCLAUDE.mdは、圧縮後にディスクから読み直される。消えたのは、チャットでだけ伝えた指示、まだ読み直されていないサブフォルダのCLAUDE.md、まだ対象ファイルを扱っていないパス指定ルールのどれか。残したい指示はCLAUDE.mdに書く
サブフォルダのCLAUDE.mdの後半が無視される	必要なときに読み込むファイルには1ファイルの上限があり、超えると冒頭だけが渡される。上限は200Kのコンテキストで40,000文字（v2.1.309以降で適用）。wc -m で文字数を数え、超えていれば分ける
大きなCLAUDE.mdがまるごと読まれない	起動時に読むCLAUDE.mdは4MiBを超えると1行も読み込まれない。推奨の長さを超えたファイルがあると、起動時と /status で警告が出る
AGENTS.mdが読まれない	作業フォルダかその上にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdがある（~/.claude/CLAUDE.mdは数えない）。v2.1.277未満でも読まれない。/config の Project instructions も確認する
「Instruction file not loaded」が出る	公式のエラー一覧（Errors）に意味と対処がある

ログイン・利用上限・429など、CLAUDE.md以外のエラーはClaude Codeのエラー一覧と対処法にまとめている。

10. チームで運用するときの決め方

CLAUDE.mdは、チームでAIエージェントを使うときの「社内ルール」の置き場所にもなる。ただし、CLAUDE.mdに書けるのは「こう動いてほしい」という指示までで、操作を止める力はない。公式ドキュメントも、全社のCLAUDE.mdは行動の指針に使い、ツールやコマンドの禁止は管理設定の permissions.deny で強制するよう分けている。何をCLAUDE.mdに書き、何を権限で止め、どこで人が判断するかを先に決めておくと、指示書が長くなりすぎずに済む。業務に入れる前に決めておくことは、LIFRELLの生成AI・Claude Code研修／AIエージェント導入支援のページでも、実際の業務の進め方とあわせて紹介している。

11. 欠点・制限事項（わからないこと）

• 守られる保証はない。CLAUDE.mdはユーザーメッセージとして渡される文脈で、厳密な遵守は保証されないと公式に書かれている。
• 「200行」は目安で、何行から守られなくなるかの数値は公式に記載なし。長いほど守られにくくなる、という説明にとどまる。
• CLAUDE.mdがどれだけトークンを使うかの目安は公式に記載なし。実際の使用量は /context で確かめるしかない。
• 仕様の変化が速い。AGENTS.mdの直接読み込み（v2.1.277）、/doctor prompt-audit（v2.1.283）、サブフォルダの文字数上限（v2.1.309）のように、バージョンで挙動が変わる。古いバージョンでは本記事のとおりに動かないことがある。
• 本記事の記入例は公式のテンプレートではない。公式の原則に沿って作った例で、効果を数値で確かめたものではない。

12. よくある質問

まとめ

CLAUDE.mdは、Claude Codeが毎回読む指示書だ。置き場所は組織・ユーザー・プロジェクト・ローカルの4つで、上書きではなくつなげて読まれる。書くのは「毎回説明し直していること」で、確かめられるほど具体的に、200行未満で、矛盾なく書く。長くなったら @インポート、.claude/rules/、スキルに分け、必ず止めたい操作は権限設定かフックで止める。

今すぐできるアクション：

1. 今日：よく使うプロジェクトで /init を実行し、できた下書きから「コードを見ればわかること」を削る。/context all で読み込まれたことを確かめる。
2. 今週：チャットで2回以上言い直したことを1行ずつCLAUDE.mdに足す。自分だけの設定はCLAUDE.local.mdに分け、.gitignoreに入れる。
3. 来月：/doctor prompt-audit で古い指示と矛盾を点検する。200行を超えたら、一部のファイルだけの決まりを .claude/rules/ に、手順をスキルに移す。

本記事の内容は、2026年11月7日にClaude Codeの公式ドキュメントで確認したもの。Claude Codeは頻繁に更新され、機能・必要なバージョン・上限は変わることがある。最新の情報は本文中のリンク先で確認できる。記入例は公式のテンプレートではない。

関連記事

• Claude Code完全ガイド｜使い方・料金・最新モデル・活用法
• Claude Codeの権限設定【2026年】許可ルールとモードの決め方（Claude Codeの権限設定｜許可ルールとモードの決め方）
• Claude in Chromeの使い方【2026年】始め方と権限・接続エラー（Claude in Chromeの使い方｜始め方と権限・接続エラー）
• Claude Code生みの親「Boris」が実践する30の最強Tips（CLAUDE.md・並列セッション）
• Claude Codeのインストール方法｜Windows・Mac・Linux別の手順
• Claude CodeのMCP設定方法｜claude mcp addの使い方・スコープ・.mcp.json
• Claude Codeのエラー一覧と対処法

出典

• Claude Code Docs「How Claude remembers your project」（CLAUDE.md・.claude/rules/・AGENTS.md・自動メモリ・トラブルシューティング。2026年11月7日確認）
• Claude Code Docs「Configure permissions」（権限ルールはモデルではなくClaude Codeが強制する。2026年11月7日確認）
• Claude Code Docs「Settings files and precedence」（設定ファイルとCLAUDE.mdの役割分担。2026年11月7日確認）
• Claude Code Docs「Errors」（Instruction file not loaded など。2026年11月7日確認）