CLAUDE.mdの書き方｜書く内容と200行の目安、効かない時の確認

CLAUDE.mdの書き方の答えは短い。毎回のセッションで Claude に知っておいてほしい事実だけを、検証できる具体さで、見出しと箇条書きにまとめ、1ファイル200行未満を目安にする。中身は、ビルドやテストのコマンド、既定と違うコーディング規約、命名規則、プロジェクト固有の設計判断、見落としやすい落とし穴。逆に、コードを読めば分かること、頻繁に変わる情報、長い解説は入れない。書いたら /context で実際の読み込み確認を行い、守られないときは「読み込まれていない」のか「書き方が曖昧」なのかを分けて直す。

CLAUDE.mdは何のためのファイルか

CLAUDE.md は人が書く Markdown の指示書で、Claude がセッション開始時に毎回読む。Claude が自分で書くメモである自動メモリ（auto memory）とは別物だ。

押さえておきたいのは、CLAUDE.md が「設定」ではなく「文脈」として扱われることだ。公式の How Claude remembers your project は、CLAUDE.md の内容はシステムプロンプトの後にユーザーメッセージとして渡され、Claude は従おうとするが厳密に守られる確約はなく、曖昧な指示や矛盾する指示では特にそうだ、と書いている。だから書き方次第で効き方が変わり、どんな場合でも止めたい操作は権限設定やフックに任せることになる。

会話中に「覚えておいて」と頼んだ内容は自動メモリに入る。CLAUDE.md に入れたいときは「これを CLAUDE.md に追加して」と明示するか、/memory から自分で編集する。自動メモリの保存先や止め方はClaude Codeの自動メモリ(auto memory)の保存先と停止する方法で扱っている。

どこに置けばよいか（4つの置き場所と読み込み順）

チームで共有する指示はプロジェクト直下の ./CLAUDE.md（または ./.claude/CLAUDE.md）に、全プロジェクト共通の個人の好みは ~/.claude/CLAUDE.md に置く。置き場所で効く範囲が変わり、公式の表を日本語で整理するとこうなる。

範囲	場所	用途	共有される相手
管理ポリシー	macOS は `/Library/Application Support/ClaudeCode/CLAUDE.md` など	IT/DevOps が管理する組織全体の指示	組織の全ユーザー
ユーザー	`~/.claude/CLAUDE.md`	全プロジェクト共通の個人の好み	自分だけ（全プロジェクト）
プロジェクト	`./CLAUDE.md` または `./.claude/CLAUDE.md`	チームで共有するプロジェクトの指示	ソース管理経由でチーム
ローカル	`./CLAUDE.local.md`（`.gitignore` に追加）	このプロジェクトだけの個人設定	自分だけ（このプロジェクト）

チームで使うなら、プロジェクト直下の CLAUDE.md を git に入れて共有する（公式もチェックインを勧めている）。自分用のサンドボックスの URL のような個人的なものは CLAUDE.local.md に分ける。

読み込みのルールも書き方に関係する。作業ディレクトリとその上の階層にある CLAUDE.md は起動時に読み込まれ、サブディレクトリにあるものは、Claude がそのサブディレクトリの別のファイルを読む、書く、編集するときに読み込まれる。見つかったファイルは上書きではなく連結される。起動した場所に近いファイルほど後に読まれ、同じ階層では CLAUDE.local.md が CLAUDE.md の後に来る。上位と下位で同じ事柄に違う指示を書くと両方が並び、矛盾の原因になる。同じ事柄は1か所にだけ書く。

リポジトリにすでに AGENTS.md がある場合、既定では、作業ディレクトリとその上の階層に CLAUDE.md も CLAUDE.local.md も無いときに AGENTS.md を読み、どちらかがあれば CLAUDE.md 側のファイルだけを読む。AGENTS.md を直接読むには Claude Code v2.1.277 以降が必要で、読めないセッションもあるため、その場合は CLAUDE.md から AGENTS.md を import する。

最初の1枚はどう作るか

ゼロから書くより、/init で初版を作るのが公式の示す始め方だ。

/init

/init はコードベースを解析し、見つけたビルドコマンド、テストの手順、プロジェクトの規約を入れた CLAUDE.md を作る。すでに CLAUDE.md がある場合は上書きせず、改善案を提案する。公式は、ここから「Claude が自力では見つけられない指示」を足して仕上げるように書いている。

環境変数 CLAUDE_CODE_NEW_INIT を 1 にしてから実行すると、質問で不足を埋め、書き込む前に提案を見せる対話式になる。

決まった書式は無い。公式のベストプラクティスは「短く、人が読める形で」と求めていて、例として次の CLAUDE.md を載せている。

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

この例の見出しは「Code style」と「Workflow」の2つだけで、どちらもこのプロジェクトで採用する選択（CommonJS ではなく ES modules、テストスイート全体ではなく単体のテストを優先）を具体的に書いている。見出しを先に決めて埋めるより、こうした採用している選択から書き始める。

何を書き、何を書かないか

公式のベストプラクティスには、入れるものと外すものの判断基準がある。日本語にするとこうなる。

入れる	外す
Claude が推測できない Bash コマンド	コードを読めば分かること
既定と違うコードスタイルのルール	Claude がすでに知っている言語の標準的な慣習
テストの手順と使うテストランナー	詳細な API ドキュメント（リンクで示す）
リポジトリの作法（ブランチ名、PR の慣例）	頻繁に変わる情報
プロジェクト固有の設計判断	長い説明やチュートリアル
開発環境のクセ（必須の環境変数など）	ファイルごとの説明
自明でない落とし穴や挙動	「きれいなコードを書く」のような自明な心がけ

迷ったら、公式の問い「この行を消したら Claude は間違えるか」を各行に当て、間違えないなら削る。肥大化したファイルは本当に守ってほしい指示を埋もれさせる。

/doctor の点検も同じ方向を向いている。公式によれば、/doctor はチェックインされた CLAUDE.md について、ディレクトリ構成、依存関係の一覧、アーキテクチャの概要のようなコードから導ける内容を削り、落とし穴、理由、ツールの既定と違う規約は残す提案をする。よく見かける「冒頭にプロジェクト概要とディレクトリ構成を詳しく書く」テンプレートは、この基準では削られる側に入る。

追記するタイミングについても公式の基準がある。

Claude が同じ間違いを2回した
コードレビューで、このコードベースについて Claude が知っているべきことが指摘された
前回のセッションと同じ訂正や補足をチャットに打った
新しいメンバーが入っても同じ文脈が必要になる

/init の初版に、このどれかが起きるたびに1行ずつ足していけばよい。

伝わる書き方はどう違うか

CLAUDE.md は強制ではなく文脈なので、書き方で守られ方が変わる。公式は「検証できる具体性を持たせて書く」として、次の書き換え例を挙げている。

曖昧な書き方	検証できる書き方
Format code properly（きちんと整形する）	Use 2-space indentation（インデントは2スペース）
Test your changes（変更をテストする）	Run `npm test` before committing（コミット前に `npm test` を実行する）
Keep files organized（ファイルを整理する）	API handlers live in `src/api/handlers/`（API ハンドラは `src/api/handlers/` に置く）

右の列は、守られたかどうかを後から確かめられる。左の列は、何をもって守ったとするかを Claude に委ねてしまう。

そのほかの公式の指針は次のとおり。

長さ: 1ファイル200行未満を目安にする。長いファイルは文脈を多く消費し、遵守も下がる
構造: 関連する指示を Markdown の見出しと箇条書きでまとめる。詰まった段落より従いやすい
一貫性: 2つの指示が矛盾すると、Claude はどちらかを恣意的に選ぶことがある。サブディレクトリの CLAUDE.md や .claude/rules/ も含めて定期見直しを行う
強調: 1つの指示だけが飛ばされるなら、その行にだけ「IMPORTANT」のような強調を付ける。多くの行を強調すると、どれも目立たなくなる
人間向けのメモ: ブロック単位の HTML コメント（）は Claude に渡す前に取り除かれる。保守担当向けの注記は、文脈を消費せずにここへ残せる。ただしコードブロック内のコメントは残る

プロジェクト直下の CLAUDE.md は /compact の後に読み直されるので、会話の中だけで伝えた指示を圧縮後も残したいなら CLAUDE.md へ移す。

200行を超えそうなときはどこへ分けるか

公式は、複数手順の手順書や、コードベースの一部にしか関係しない内容は、スキルかパス指定ルールへ移すよう書いている。振り分けを表にするとこうなる。

置き場所	読み込まれるタイミング	向いている内容
CLAUDE.md	毎セッションの開始時	ビルドコマンド、規約、プロジェクト構成、「常に X する」ルール
`.claude/rules/`（paths なし）	起動時（`.claude/CLAUDE.md` と同じ優先度）	トピック別に分けたい常時の指示
`.claude/rules/`（paths あり）	該当ファイルを Read・Write・Edit したとき	特定のディレクトリや拡張子だけの規約
スキル	呼び出したとき、または関連すると判断されたとき	毎回は要らない手順や専門知識
フック	決まったライフサイクルのタイミングで実行	コミット前やファイル編集後に必ず走らせたい処理
権限設定	Claude の判断に関係なくクライアントが強制	セキュリティ境界、決してさせない操作

パス指定ルールは、ルールファイルの先頭に paths のフロントマターを書く。公式の例は次のとおりで、src/api/ 配下の TypeScript ファイルを扱うときだけ読み込まれる。

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

@path/to/import の書き方で別ファイルを取り込む方法もあるが、公式は「import は長いファイルの整理には役立つが、読み込み量は減らない」と書いている。200行の目安のための分割なら、パス指定ルールかスキルを選ぶ。import の相対パスや承認の仕組みはCLAUDE.mdのimport仕様にまとめている。

CLAUDE.md と権限・フックの境界について、公式のデバッグ手順は、CLAUDE.md は「ここではこうする」に使い、セキュリティ境界や決して起きてはいけないことには権限かフックを使うよう書いている。たとえば「main に直接 push しない」を CLAUDE.md に書くことはできるが、それは守ってほしいというお願いであり、止める仕組みではない。止める側の設定はClaude Code hooksの仕組み・設定手順、スキルの作り方はClaude Codeのスキルとは、権限や情報の扱いをどう決めるかはClaude Codeの運用ルールの決め方で扱っている。

書いたCLAUDE.mdが読み込まれたか確かめる方法

書いた直後にやることは1つで、セッション内で /context を実行する（公式の確認手順）。

/context

表示の Memory files の一覧に、起動時に読み込まれるはずの CLAUDE.md と CLAUDE.local.md が並んでいれば読み込まれている。ここに無いファイルは Claude には見えていない。ファイルを開いて編集したいときは /memory を使う。

/memory

/memory は未作成のものも含めて CLAUDE.md の場所を一覧にし、選んだファイルをエディタで開く。

注意点が2つある。1つ目は、セッション途中の編集は反映されないこと。公式のプロンプトキャッシュの説明によれば、プロジェクト直下とユーザーの CLAUDE.md はセッション開始時に一度読まれて保持され、途中で編集しても Claude は開始時の版で作業を続ける。新しい内容は次の /clear、/compact、または再起動で読み込まれる。

2つ目は、サブディレクトリの CLAUDE.md は Memory files に出ないこと。起動時ではなく必要になったときに読み込まれるためで、読み込まれるとそのパスを示す Loaded 行がターミナルに表示される。

指示が守られないときの切り分け

まず読み込まれているか、次に書き方に問題がないかを確認し、編集の反映時点や組み込みエージェントの例外も切り分ける。公式のトラブルシューティングを症状から引ける形にまとめる。

症状	考えられる原因	確認と対処
`/context` の Memory files にファイルが無い	読み込まれる場所に置かれていない	置き場所の表と照らし合わせる。サブディレクトリなら、そのディレクトリのファイルを Claude に読ませる
編集したのに挙動が変わらない	セッション開始時の版のまま	`/clear`、`/compact`、再起動のどれかで読み直す
ルールがあるのに同じことを繰り返す	ファイルが長すぎて埋もれている	「消したら間違えるか」で削る。一部の作業だけの指示はパス指定ルールかスキルへ
CLAUDE.md に書いてあることを質問される	表現が曖昧	検証できる具体的な書き方に直す
2つの指示のうち片方しか守られない	指示が矛盾している	上位・下位の CLAUDE.md と `.claude/rules/` を見直し、同じ事柄を1か所にまとめる
コミットや PR のルールが守られない	Claude Code の組み込みの指示と競合している	`includeGitInstructions` で組み込みの指示をオフにし、`attribution` で帰属表記を設定する
サブエージェントが指示を無視する	組み込みの Explore と Plan は起動時に CLAUDE.md を読まない	委任するプロンプトの中で指示を改めて伝える
起動時や `/status` で長さの警告が出る	推奨の長さを超えている	分割先の表に沿って移す

公式は、/context で読み込みを確認できたのに特定の指示が守られないなら、問題は読み込みではなく書き方にある可能性が高い、と書いている。変更したら、Claude の挙動が実際に変わったかを観察して確かめる。

古い記述や矛盾を Claude に探させることもできる。

/doctor prompt-audit

これは CLAUDE.md、CLAUDE.local.md、AGENTS.md と、.claude/ および ~/.claude/ 配下のルールやスキルなどを点検し、古いモデル向けの指示、存在しないファイルやコマンドへの参照、互いに矛盾するファイルを報告する。提案された修正は、適用を頼むまでファイルに反映されない。公式には Claude Code v2.1.283 以降が必要と書かれている。

200行は上限か、版で変わる点はどこか

200行は「目安」であって上限ではない。公式は 4 MiB までの CLAUDE.md を全文読み込み、それを超えるファイルは読み飛ばすと書いている。版で変わる点は、/doctor prompt-audit が v2.1.283 以降、AGENTS.md の直接の読み込みが v2.1.277 以降という2つだ。本稿は、2026年10月19日に取得した公式ドキュメント（How Claude remembers your project、Best practices for Claude Code、Debug your configuration、How Claude Code uses prompt caching）の記述を基に整理した。バージョン条件付きの機能は claude --version で手元の版を確かめてから使い、挙動が違う場合は公式ページで再確認してほしい。

議事録を題材に指示を書いて試す練習はCLAUDE.mdで議事録テンプレートを練習にある。