CLAUDE.mdに何を書くか｜200行で効かせる置き場所と書き方

新しいセッションを始めるたびに、同じ注意を打ち直すことになります。 パッケージマネージャを間違える、自動生成のファイルを手で書き換える、テストの走らせ方を毎回尋ねてくる。 Claude Codeは毎回まっさらな状態から始まるので、前のセッションで直させた内容は残りません。 その持ち越し先がCLAUDE.mdで、うまくいかない原因はたいてい「書く内容」「置き場所」「分量」の3つに分かれます。 この記事では、公式ドキュメントの記述をもとに、どこに何を書けば効くのかを整理します。

CLAUDE.mdは設定ファイルではなく「毎回読ませるメモ」

CLAUDE.mdは、ただのMarkdownファイルです。 特別な書式はなく、セッションの開始時にそのまま読み込まれます。 ここで押さえておくべき性質が1つあります。 公式ドキュメントは、この内容がシステムプロンプトの一部ではなく、その後ろに置かれる利用者からのメッセージとして届くと説明しています。 読んだうえで従おうとはするものの、曖昧な指示や矛盾した指示では厳密な遵守は保証されない、という位置づけです。

そのため、「絶対に止めたい」種類の決まりはCLAUDE.mdの仕事ではありません。 コミットの前に必ず走らせたい処理や、特定のフォルダへの書き込み禁止は、フックとして書くほうが確実です。 フックはシェルコマンドとして決まった時点で実行されるので、モデルの判断が入りません。

もう1つの仕組みが自動メモリです。 こちらはClaude自身が、セッション中の指摘や訂正から学んだことを書き残す領域で、リポジトリごとに ~/.claude/projects/<プロジェクト>/memory/ に保存されます。 索引となる MEMORY.md は、先頭200行または25KBまでが毎回読み込まれます。 人が意図して書くのがCLAUDE.md、自動でたまるのが自動メモリ、という住み分けです。

置き場所で効く範囲が変わる

CLAUDE.mdは1か所ではありません。 上書きではなく積み重ねで読み込まれるため、昔ホームフォルダに書いた決まりが、いま触っているプロジェクトにも効いています。

置き場所	効く範囲	書く内容	共有先
~/.claude/CLAUDE.md	すべてのプロジェクト	個人の好み、道具の使い方	自分だけ
./CLAUDE.md または ./.claude/CLAUDE.md	そのプロジェクト	ビルド・テスト・規約	チーム（Git経由）
./CLAUDE.local.md	そのプロジェクトの自分だけ	検証用URL、テストデータ	自分だけ
/Library/Application Support/ClaudeCode/CLAUDE.md	組織全体（macOS）	セキュリティ方針	管理者が配る全員

読み込みは、起動したフォルダとその上位のフォルダをすべてたどる形で行われます。 順番はファイルシステムの上から下へで、起動した場所に近いファイルが最後に読まれます。 同じ階層では CLAUDE.md の後に CLAUDE.local.md が続きます。 起動した場所より下のフォルダにあるファイルは起動時には読まれず、そのフォルダのファイルを読んだ時点で取り込まれます。

ここから2つの実害が出ます。 複数のプロジェクトをまとめた親フォルダで起動すると、別のリポジトリ向けの指示を読ませてしまいます。 モノレポでパッケージごとにCLAUDE.mdを置いている場合、そのパッケージのファイルに触れるまで、そのファイルの決まりは効きません。

なお、他のAIツール向けの AGENTS.md が既にあるリポジトリでは、作業フォルダとその上位に CLAUDE.md も CLAUDE.local.md も無いときに限り、AGENTS.md が直接読まれます。 両方を活かしたいときは、短い CLAUDE.md から @AGENTS.md として取り込むのが単純です。

書くべきこと、書かなくてよいこと

公式の目安は「毎回のセッションで持っていてほしい事実」です。 ビルドのコマンド、規約、プロジェクトの構造、常に守ってほしい決まりが該当します。 追記の判断材料としては、同じ間違いが2回目に起きたとき、レビューで拾われたとき、前のセッションと同じ訂正を打ったとき、新しく入った人にも同じ説明が要るとき、が挙げられています。

具体的に効くのは次の4種類です。

• 推測できないコマンド。npm test は自力で見つけますが、単体のテストを走らせる引数、必要な環境変数、ローカルDBの前提は書かないと分かりません
• 自明でない置き場所。フォルダ一覧は自分で見られるので、手で編集してはいけない生成物や、死んでいるように見えて現役のフォルダだけを書きます
• 既定と違う規約。「インデントは半角2つ」「APIのハンドラは src/api/handlers/ に置く」のように、検証できる粒度で書きます
• すでに時間を溶かした落とし穴。「移行スクリプトを共有DBに向けない。ローカルのDockerを使う」の1行は、書式の規則1ページより効きます

逆に、コードを読めば分かること（依存関係の一覧、READMEの写し、全フォルダの説明）は削ります。 たまにしか使わない長い手順はスキルへ、自分だけの好みは利用者向けのファイルかローカル用のファイルへ移します。

実際に置くと、この程度の分量に収まります。

## コマンド
- 開発サーバー: npm run dev（ポート3047）
- 単体テスト: npx jest 対象ファイル
- コミット前: npm run lint && npm run typecheck

## 決まり
- src/generated/ は手で編集しない。npm run codegen を使う
- DBの変更は db/migrations/ にマイグレーションを追加する
- ローカルのPostgreSQLはDockerのものを使う

見出しと箇条書きで区切るのは見た目の問題ではありません。 公式も、関連する指示をMarkdownの見出しと箇条書きでまとめることを勧めています。 だらだらと続く段落より、整理された節のほうが追いやすいからです。 なお、<!-- 保守メモ --> のようなブロックのHTMLコメントは読み込みの前に取り除かれるので、人に向けた注記をコンテキストを消費せずに残せます。

200行を超えたら、分け方を変える

CLAUDE.mdは毎回コンテキストに載り、実際の依頼と同じ窓を奪い合います。 公式はここに具体的な線を引いています。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using imports or .claude/rules/ files. 出典: zenn.dev

太らせないための道具は3つありますが、効き方が違います。

1つ目は .claude/rules/ に置くファイルです。 先頭のフロントマターに paths: を書いて src/api/**/*.ts のように対象を絞ると、そのファイルを読んだときだけ取り込まれます。 3つのうち、毎回の読み込み量を実際に減らせるのはこれだけです。

2つ目が @docs/testing.md のようなimportです。 本体は読みやすくなりますが、取り込まれたファイルも起動時に読まれるので、量そのものは減りません。 最大4段までたどれます。 バッククォートで囲んだパスは取り込まれず、ただの文字列として残ります。

3つ目がスキルです。 リリース手順のような多段の作業は、呼ばれたときだけ読み込まれるスキルに移すのが向いています。

分量と同じくらい効くのが、矛盾を残さないことです。 片方のファイルで「npmを使う」、別のファイルで「pnpmを使う」と書いてあれば、どちらが選ばれるかは決まりません。 数週間に一度読み返して、古くなった行を消す作業のほうが、新しい行を足すより効果があります。

効いていないときに確かめる順番

指示が守られないとき、原因は「読み込まれていない」「別のファイルと矛盾している」「曖昧すぎる」「そもそも仕組みが違う」のどれかです。

最初に、セッション内で /context を実行します。 Memory filesの欄に自分のCLAUDE.mdが並んでいなければ、読み込まれていません。 この場合は文面ではなく、起動したフォルダを疑います。 /memory を使えば、利用者向けとプロジェクト向けのCLAUDE.mdを一覧して開けます。

読み込まれているのに守られないなら、他のファイルに反対の指示が無いかを探し、そのうえで指示を具体化します。 「関数は短く」では検証できませんが、「40行を超えたら分割する」なら確かめられます。

/compact のあとに指示が消えたように見えることもあります。 プロジェクト直下のCLAUDE.mdは圧縮後にディスクから読み直されるので残りますが、会話の中だけで伝えた指示は残りません。 消えて困る決まりは、その場でファイルへ移します。

最初の1本を用意するだけなら /init が使えます。 コードベースを解析して、見つけたビルドやテストのコマンドを書き出します。 既にファイルがある場合は上書きせず改善案を出す作りです。 出力にはコードを読めば分かる記述も混ざるので、そこを削るところから育て始めます。

ファイルが大きくなりすぎたときは、/doctor の点検も使えます。 コードベースから分かる記述（フォルダ構成、依存関係の一覧、構造の概説）を削り、落とし穴や理由、既定と違う規約を残す方向で、削減案を出す作りになっています。 自分で削る基準が決まらないときの当たりを付ける用途に向きます。

もう1つ、仕組みそのものが違うケースもあります。 「毎回この時点で必ず実行してほしい」という要求は、CLAUDE.mdに何度書いても確実にはなりません。 コミット前やファイル編集後のように時点が決まっているなら、フックに移すのが筋です。 システムプロンプトの側に置きたい内容なら、起動時に渡す --append-system-prompt という手段もあります。

決まりを書く手と、フォルダを開く手をそろえる

CLAUDE.mdはプロジェクトの説明であり、読み込まれるかどうかは「どのフォルダで起動したか」で決まります。 つまり、書き方の話は最後に置き場所の話に戻ってきます。 ファイルを探す窓とターミナルの窓を行き来していると、親フォルダで起動して別プロジェクトの決まりを読ませる、という取り違えが起きます。

書いた内容の点検も同じです。 「生成物はここ」「移行ファイルはここ」と書いた場所が、いつの間にか移動していないかを見るとき、フォルダを目で確かめながらセッションを続けられると早く済みます。 フォルダとターミナルとAIが同じ窓にあるファイル管理アプリなら、いま見ているフォルダでそのまま起動でき、取り違えが起きません。 具体的な操作はできることに、ほかのファイル管理アプリとの違いは他のファイル管理との比較にまとめています。 費用は料金、残りの疑問はよくある質問で確かめられます。