Claude Code の CLAUDE.md 書き方｜最小テンプレートと育てた後の整理・メモリ運用

監修者_SD以外

監修者プロフィール

森下浩志

日本最大級のAI情報プラットフォーム「romptn ai」編集長。著書に「0からはじめるStable Diffusion」「0からはじめるStable Diffusion モデル・拡張機能集編」など、AmazonベストセラーのAI関連書籍を多数執筆。AIにおける情報の非対称性を解消するための社内研修や出張講義も行う。

毎回の説明をやめるための最小 CLAUDE.md

毎セッションの前提説明を止めたいなら、まずプロジェクト直下に CLAUDE.md を 1 本置くところから始めます。書き方の良し悪しを学ぶ前に、最小の 1 本があるかどうかで負担が大きく変わるためです。

「今のプロジェクトは TypeScript で」「テストは vitest で」「マスターブランチは触らないで」と、Claude Code に毎回同じ前提を打ち直していないでしょうか。新しいチャットを開くたびに同じ説明を 5 分繰り返すのは、開発の集中を確実に削ります。

この負担は、プロジェクト直下に 30〜80 行ほどの CLAUDE.md を 1 本置くだけで多くが消えます。Claude Code はセッション開始時にこのファイルを自動で読み込むため、書いた内容はそのまま常時の前提になります。

最初に置く 1 本は、次のような骨格で十分です。

# Project

- Node.js 20 / TypeScript / pnpm モノレポ
- Web: Next.js (App Router) / API: Hono
- DB: PostgreSQL (Drizzle ORM)

# よく使うコマンド

- 開発サーバー: `pnpm dev`
- 単体テスト: `pnpm test`
- 型チェック: `pnpm typecheck`
- Lint: `pnpm lint`

# コーディング規約

- 関数は小さく、副作用は最外層に寄せる
- import は alias (`@/...`) を優先
- React component は default export しない
- 日付は dayjs ではなく date-fns を使う

# 触らないでほしい場所

- `packages/legacy/` 以下は凍結 (移行完了まで触らない)
- DB マイグレーションファイルは編集禁止 (新規追加のみ)
- `.env*` は読み取り専用

# 進め方の好み

- 大きな変更前は手順案を先に共有する
- 不確実な依存は推測せず docs を確認する
- コメントは「何をしているか」より「なぜそうしたか」を残す
- テストを書き換える時は元の意図を本人に確認する

この骨格に共通するのは、毎セッション必ず読ませたい『前提・コマンド・スタイル』だけに絞っている点です。可変な作業ログや一時的なお願いは混ぜず、長く有効な事実だけを残しています。

ここまでで「毎回喋っていた内容の 7〜8 割は CLAUDE.md 側に逃がせる」感覚が掴めるはずです。なぜこの 1 本が常時効くのか、どこに置けば狙ったタイミングで読み込まれるのかは、続く『CLAUDE.md が読み込まれる仕組みと置き場所』で扱います。

CLAUDE.md が読み込まれる仕組みと置き場所

最小テンプレが効くのは偶然ではなく、CLAUDE.md が Claude Code 起動時に常時読み込まれる facts のインデックスとして扱われているからです。どこに置けば読まれるか、複数階層があるとどう合成されるかは仕様で決まっており、ここを押さえると「なぜそれだけで効くか」が腑に落ちます。

仕組みは大きく 2 つの観点で整理できます。まず置き場所の側面として、CLAUDE.md は組織配布から個人設定まで複数のスコープを持ち、近いものほど強く効きます。次に読み込み挙動の側面として、Claude Code は起動ディレクトリから親方向へ walk-up しながら見つかった CLAUDE.md を順次重ねていきます。

この 2 つを順に見ていきます。まず「4 つのスコープと読み込み順」で置き場所の地図を整理し、続いて「walk-up と node_modules の落とし穴」で、自分が書いていない CLAUDE.md まで自動で読まれてしまう副作用を確認します。

4 つのスコープと読み込み順

CLAUDE.md の置き場所は、Anthropic 公式の memory ドキュメントが 4 つのスコープを定義しています。同じファイル名でも、どこに置くかで「誰の指示か」「いつ読まれるか」が変わります。

読み込み順は Managed policy が最も強く、次に Project、User、Local の順で重なります。下位のスコープが上位の指示を覆い隠すのではなく、近いものほど後から効く形で合成されると考えると整理しやすいです。

ここから前章で見せた最小テンプレの位置付けが見えます。プロジェクト直下の CLAUDE.md は Project スコープに当たり、リポジトリを clone した全員が同じ前提を受け取ります。「TypeScript で」「pnpm モノレポで」のようなチーム共通の事実はここに集めるのが素直です。

一方で「自分は説明を簡潔にしてほしい」「コミットメッセージは英語で書きたい」のような個人の好みは、ユーザー配下の ~/.claude/CLAUDE.md に置いておくと、別のプロジェクトに移っても効き続けます。

プロジェクトと自分の好み、2 つの引き出しを最初に分けておくと、毎セッションで同じ前提を Claude に喋り直す手間が積み上がりません。新しいリポジトリに移った時の説明コストも小さく済みます。

walk-up と node_modules の落とし穴

もう 1 つ押さえておきたいのが、Claude Code は起動ディレクトリから親方向へ歩きながら、途中で見つけた CLAUDE.md を片っ端から重ねて読む挙動です。手元のプロジェクト直下にしか CLAUDE.md を置いていないつもりでも、上位ディレクトリやサブパッケージ内のファイルまで一緒に読まれることがあります。

この仕様で実際にぶつかりやすいのが、node_modules の中に潜んでいる CLAUDE.md です。依存ライブラリが配布物として CLAUDE.md を同梱しているケースがあり、利用者の環境では「自分が書いていない 986 行のファイル」と「346 行のファイル」が自動で読み込まれていた、という事例も観測されています。

対処の方向性は 2 つあります。1 つは、自分のプロジェクト直下より上位の階層に古い CLAUDE.md が残っていないかを find などで一度棚卸しすることです。もう 1 つは、Claude Code 側の設定で特定パス配下の CLAUDE.md を除外する方法を検討することで、最新の対応は Anthropic 公式の Claude Code settings ドキュメント で確認するのが確実です。

まず「読まれている範囲を自分で把握できる」状態に持っていけば、後の章で扱う「書きすぎてブレる」失敗の半分は手前で防げます。

何を書き、何を書かないかの判断軸

書く / 書かないの判断は、Claude Code が CLAUDE.md を毎回必ず読むという性格から逆算するのが近道です。常時持っていてほしい事実だけを残し、それ以外は別の場所に分けるのが基本姿勢になります。

判断軸は次の 4 つに整理できます。

ここで効くのは「書くべきもの = 何度読まれても陳腐化しない事実」という見立てです。半年後に読み返しても変わらない情報だけを残せば、CLAUDE.md は自然に短くまとまります。

逆に 作業ログや一時指示を書き溜めると、古い指示が常時 load されて挙動を引っ張る事態が起こります。「やめたはずの方針が今も発動している」と感じたら、まず CLAUDE.md に残骸が居座っていないかを疑うのが近道です。

この判断軸は「短く保つ」だけでなく「短すぎて必要情報を落とす」失敗にも効きます。常時必要なら残す、その他は別の機構へ逃がす、というシンプルな基準で迷いが減ります。具体的な目安としての行数や、増えた分の逃がし先は、続く 2 つの章で扱います。

200 行ガイドラインの根拠と読み解き方

「200 行を目安に」という数字は、Anthropic 公式のメモリドキュメントに明記された推奨であり、コミュニティの噂ではありません。何度も読み込まれる常時前提だからこそ、上限の目安が示されています。

この数字を支える理由は大きく 2 つあります。1 つは context window の圧迫で、CLAUDE.md が長くなるほど、その分だけ本来のコードや会話に使える残量が削られます。もう 1 つは 指示への追従率の問題で、長文の前提が注入されるほど「関係なければ無視してよい」という前置きが効いてしまい、肝心な規約まで弱く扱われる傾向が報告されています。

ここから 200 行を 「常時 load されてよい予算」 として捉え直すのが実用的です。絶対値の上限ではなく、「この予算内に収まる事実だけ常時 load にする」という設計の物差しとして使います。

この読み替えは、両極端の失敗を同時に避けるのに役立ちます。

予算という捉え方なら、必要なら 250 行になっても致命傷ではないし、120 行で収まっているなら無理に増やす必要もない、と判断できます。

大事なのは、200 行という数字を超える前に 「これは本当に常時必要か」 を 1 回ふるいに掛ける癖を持つことです。常時必要でないものは別の機構へ逃がす、というのが次章の整理動線につながります。

育った CLAUDE.md の整理動線

ここからは、書き足し続けて 200〜500 行に膨らんでしまった CLAUDE.md を、どこへ何を逃がして整えるかを扱います。中身を捨てるのではなく、似た役割の別機構へ移すのが基本です。

実例として、長く運用していた CLAUDE.md を 171 行から 82 行へ半減させた整理例があります。削った分は消えたわけではなく、Skills や Sub-agent memory、Auto MEMORY.md など別の置き場所に役割ごと移っています。常時 load される予算は 82 行で守りつつ、必要な知識は引き出せる状態を維持できます。

この整理を進めるには、Claude Code 周辺の機構が どれが常時読まれ、どれが必要なときだけ呼び出され、どれが強制力を持つか を地図として持っておくと判断が速くなります。

この章では次の 3 つの観点で順に整理します。最初に CLAUDE.md / Skills / Slash Commands / Hooks / Sub-agent memory / Auto MEMORY.md の 6 機構を仕分けるための地図を示し、次に「分けたつもりで context は減らない」@import の落とし穴を確認し、最後に「具体的に何をどこへ逃がすか」の対応を機構ごとに整理します。

① 6 機構を 3 軸で仕分ける

似た名前の機構が並んで混乱しやすいので、まず 6 つの機構を「常時 load か」「on-demand か」「enforce か」の 3 軸で並べておきます。これを物差しにすると、自分の指示をどこに置くべきかが見えてきます。

ここで効くのが 「CLAUDE.md は suggestion でしかない」 という性質です。書いてあっても無視される瞬間がどうしてもあるため、絶対に守らせたいルール (たとえば「本番 DB に直接書き込まない」「特定ファイルは編集しない」) は Hooks 側で deterministic に止める設計が向きます。Hooks の具体的な設定は Anthropic 公式の Claude Code hooks ドキュメント で確認できます。

この 3 軸を踏まえると、整理の方針も決めやすくなります。常時必要な前提は CLAUDE.md に残し、必要なときだけで足りる知識は Skills か Slash Commands に逃がし、強制力が要るものだけを Hooks に上げる、という形です。

② @import と Hybrid 配置の落とし穴

「長くなったから別ファイルに @import で分けた」という対応は、見かけ上の行数は減っても、context に注入される量はほぼ変わりません。@import は import 先の本文を CLAUDE.md と一緒に context へ展開する仕様だからです。

では何を分けるべきかを考えるヒントになるのが、r/ClaudeAI の Skills 実験です。2,455 回の評価で、embedded 配置 (本体をすべて CLAUDE.md に書く) より hybrid 配置 (CLAUDE.md には要約と参照だけ、本体は Skills 側に置く) のほうが追従率が高かったと報告されています。

つまり「分ける方向」が大事です。CLAUDE.md には次の 2 つだけを残します。

本体の手順や長い説明は Skills や .claude/rules/ のような on-demand 側に置き、必要なときだけ context に乗せる構成にします。これなら CLAUDE.md は常時 load の予算内に収まり、必要なときには本体を呼べる状態が両立できます。

@import を使うこと自体は問題ではありません。「import 先まで含めて常時 load される」という前提で設計する、というのが落とし穴の正体です。

③ 各機構への逃がし方

ここまでの整理を踏まえて、CLAUDE.md から何をどこへ逃がすかを機構ごとに対応付けます。判断軸はシンプルで、「常時必要なら CLAUDE.md に残す」「必要なときだけで足りるなら on-demand 側へ」「絶対に守らせたいなら enforce 側へ」の 3 つです。

運用の流れとしては、まず Skills と .claude/rules/ への切り出しから始めると効果が大きいです。Hooks や Sub-agent memory は、CLAUDE.md だけでは抑えきれない症状が出てきたタイミングで足していくのが現実的で、最新の設定方法は Anthropic 公式の Skills ドキュメント や Sub-agents ドキュメント で確認できます。

この逃がし方を続けると、CLAUDE.md は徐々に 「facts のインデックス」 に近づき、本体の知識はそれぞれの専門機構が持つ形に整っていきます。

Claude Code の CLAUDE.md 運用のまとめ

ここまでの内容を、「最小で始める → 仕組みを知る → 育ったら逃がす」 の 3 ステップに圧縮しておきます。

手を動かすときの最初の一歩は、次の順番が無理なく進みます。

CLAUDE.md は一度書いて終わりのファイルではなく、プロジェクトと自分が育つほど、置き場所を見直し続ける運用ドキュメントです。短く保つことを目的にせず、「常時 load にふさわしい事実だけが残っているか」を物差しにしていけば、Claude Code との会話は徐々に軽く、徐々に意図通りに動くようになっていきます。