Claude Code CLAUDE.md 書き方ベストプラクティス

Claude Codeを触り始めたころ、最初は /init が出した素案をそのままCLAUDE.mdに置いていましたが、少し追記するだけで説明がふくらみ、肝心のルールが埋もれがちでした。
そこから、最初は10〜30行のテンプレートで始めて、足りないものだけ足すほうが運用が安定すると実感しています。

この記事は、Claude Codeの基本操作はわかるけれど、CLAUDE.mdに何を書き、どこまで書くべきか迷っている初心者〜中級者に向けたものです。
CLAUDE.mdはAI向けの最小限オンボーディング資料だと捉えると設計がぶれにくく、長くなってきたら rules・skills・hooks・@import に責務を逃がすのが筋道です。

配置場所や読み込み方の前提はClaude があなたのプロジェクトを記憶する方法やClaude Code のベストプラクティスに沿って押さえます。
30分で自分のプロジェクト用に作成し、必要なら分割できるところまで一気に整理します。

CLAUDE.md とは何か

CLAUDE.mdは、Claude Codeが各セッション開始時に読む AI向けの永続指示ファイル です。
READMEの代わりというより、人間とAIの両方が同じ前提に立つための、最小限のオンボーディング資料と捉えると収まりがよいです。
公式の目安は約500行以内です。
もっとも、実務ではそこまで使い切らないほうが安定します。
私もREADME側に背景説明を足して長文化させていた時期より、CLAUDE.mdを20行前後まで削って「このプロジェクトで毎回必要な前提」だけ残した時のほうが、応答のぶれが減って一貫した返答になりやすい感触がありました。

読者が最初に押さえるべきなのは、何でも書く場所ではないという点です。
広く効く前提だけを置き、たまにしか使わない手順はSkillsへ、毎回必ず走らせる処理はHooksへ逃がすと役割が噛み合います。
CLAUDE.mdに向いているのは、たとえば次のような内容です。

プロジェクト概要なら、「Next.js製の管理画面。
API は apps/web から packages/api-client を経由して呼ぶ。
状態管理はZustandで統一」のように、技術スタックと構成を2〜3文で示します。
主要コマンドなら、「開発は pnpm dev、単体テストは pnpm test、型チェックは pnpm typecheck、提出前は pnpm lint && pnpm test」という書き方で十分です。
アーキテクチャ判断は、「新規API呼び出しは fetch 直書き禁止。
api-client に集約」「日付処理はdayjsに統一」のように、迷いやすい分岐だけ残します。
コーディング規約は、「TypeScriptでは any を避け、型が曖昧な入力は zod で検証」「Reactコンポーネント名は PascalCase」のように、既存コードの癖を短文で固定します。
検証フローやレビュー観点なら、「変更後は関連テスト実行、スクリーンショット差分確認、破壊的変更の有無をPR説明に明記」と書いておくと、成果物の粒度が揃います。

配置場所

プロジェクト用のCLAUDE.mdは、公式仕様ではプロジェクトルートの ./CLAUDE.md または ./.claude/CLAUDE.md に置けます。
読み込みの前提はClaude があなたのプロジェクトを記憶する方法に整理されていて、ワーキングディレクトリより上の階層にあるファイルは起動時に読み込まれ、サブディレクトリ内のCLAUDE.mdは、その領域のファイルを扱う時にオンデマンドで参照されます。

この挙動を踏まえると、単一アプリならルートに1枚置けば足ります。
モノレポなら、ルートには全体方針だけを書き、apps/frontend/CLAUDE.md や packages/backend/CLAUDE.md のように領域ごとの補足を分けるほうが素直です。
たとえばルート側には「パッケージ管理は pnpm」「CI通過前提で提案」「共有型は packages/shared に集約」と書きます。
フロント側には「UIはTailwind CSS準拠」「データ取得はReact Query経由」、バックエンド側には「DB変更時はマイグレーション必須」「外部APIエラーは Result 型で吸収」といった具合です。
1枚に詰め込むより、どの判断がどこで効くのかが明確になります。

ファイルが膨らんできたら、@path/to/import で別ファイルを参照する設計も使えます。
たとえば CLAUDE.md 本体には要約だけ残し、@.claude/rules/typescript.md や @.claude/rules/review.md を読み込む構成です。
実践記事では再帰的なインポート深度にも言及がありますが、そこは公式仕様として断定せず、分割の目的を「長文回避」と「責務分離」に置いたほうが運用がぶれません。

Claude があなたのプロジェクトを記憶する方法 - Claude Code Docs

CLAUDE.md ファイルで Claude に永続的な指示を与え、自動メモリで Claude が自動的に学習を蓄積できるようにします。

code.claude.com

位置づけ

位置づけとして近いのはREADMEですが、役割は同じではありません。
READMEが人間向けの案内板なら、CLAUDE.mdは AIが毎回読む前提の最小限オンボーディング資料 です。
背景説明や導入経緯を丁寧に書くより、方針・前提・コマンド・判断基準を先に置いたほうが、実際のセッションで効きます。

たとえばREADMEには「なぜこの技術を選んだか」「チームの背景」「今後の構想」まで書いてよいのですが、CLAUDE.mdで欲しいのは「今このリポジトリでどう振る舞うべきか」です。
短い文で切るなら、「このリポジトリはFastAPI+SQLAlchemy構成」「ORMモデルを直接レスポンスに返さない」「例外メッセージは日本語で統一」「修正後は pytest -q を実行」のような書き方になります。
これだけで、生成コードの方向性もレビュー時の観点も揃います。

推奨長についても、この位置づけを意識すると判断しやすくなります。
公式は約500行以内を目安にしていますが、現場ではもっと短い運用がよく機能します。
500行でも読むこと自体はできますが、紙に置き換えると20ページ前後の文量に相当し、更新のたびに全体を見直すのは軽い作業ではありません。
だからこそ、「毎回必要なことだけを残す」「領域別ルールは分割する」という設計が効きます。
実務で安定するCLAUDE.mdは、情報量の多さよりも、削る判断が入っているかで差が出ます。

読み手

読み手は人間ではなく、まずClaudeです。
ここを取り違えると、説明のうまい文書はできても、実際のコード生成やレビューで効かないファイルになります。
Claudeが必要としているのは長い叙述ではなく、行動に直結する前提です。
方針、使うコマンド、避ける実装、レビュー時の見る場所。
この4点が短く書かれているだけで、会話の立ち上がりが変わります。

実務で入れておくと効く項目を、そのまま書式の見本にすると次のようになります。
プロジェクト概要は「B2B向け請求管理SaaS。
フロントはNext.js、APIはNestJS、認証はAuth0」。
主要コマンドは「開発 pnpm dev、E2E pnpm test:e2e、提出前 pnpm lint && pnpm test && pnpm build」。
アーキテクチャ判断は「新規画面は App Router 前提」「直接SQL禁止、Repository 経由」。
コーディング規約は「TypeScriptの export は named export 優先」「UI文言は messages/ja.json に集約」。
検証フローとレビュー観点は「テスト追加の有無、型エラーゼロ、権限境界の破綻がないか、UI差分が既存トーンを壊していないか」といった具合です。
どれも説明文を足しすぎず、1行で判断が伝わる形が向いています。

このファイルは、プロジェクト固有の知識や罠を書く場所でもあります。
たとえば「請求締め日はタイムゾーン Asia/Tokyo 固定」「管理画面のCSV出力は古い顧客仕様を維持」「packages/ui のトークンを無視して色を直書きしない」といった情報です。
一般論のコーディング作法より、リポジトリを触らないと見えないルールのほうが価値があります。
AIは一般論をもともと持っていますが、そのプロジェクトだけの前提はファイルに書かない限り拾えません。
そこでCLAUDE.mdの短い一文が効いてきます。

最初に知っておきたい読み込みの仕組み

起動時に読む範囲

CLAUDE.md の読み込み方は、まず「Claude がどこから文脈を拾うのか」を押さえると整理できます。
Anthropicの『Claude があなたのプロジェクトを記憶する方法』で説明されている通り、ワーキングディレクトリより上の階層にある CLAUDE.md は、セッション開始時に読まれます。
つまり、いま開いている場所が apps/web だとして、その上にあるリポジトリルートや、さらに親階層に CLAUDE.md があれば、その内容が最初の前提として入ります。

ここで効いてくるのが、親階層ほど広い方針、現在地に近いほど具体的な方針という考え方です。
たとえばルートの CLAUDE.md には「依存管理は pnpm に統一」「レビューではテスト追加の有無を見る」といった全体ルールを書き、apps/web 側には React や Next.js の実装方針を書く、という分け方が自然です。
こうしておくと、Claude は最初に全体ルールを読んだうえで、必要な領域の情報を重ねていけます。

実際に運用してみると、親階層に何でも書き込む構成はすぐ苦しくなります。
frontend と backend と infra の事情を全部ルートに詰めると、今は UI を触っているのに DB マイグレーションの注意点まで毎回前提に入ってきます。
こうなると「知識が多い」状態ではなく、「最初からノイズも一緒に背負っている」状態なんですよね。
起動時に読む範囲は広いからこそ、親側には本当に共通の内容だけを置くのが筋です。

サブディレクトリのオンデマンド読み込み

一方で、サブディレクトリ配下の CLAUDE.md は挙動が違います。
これはセッション開始時に全部読むのではなく、そのディレクトリ内のファイルを参照したときにオンデマンドで読み込まれます。
たとえば apps/web/components/Button.tsx を開いたり編集したりした時点で、apps/web/CLAUDE.md のような領域固有の指示が効いてくる、というイメージです。

この仕組みを理解すると、CLAUDE.md は1枚に集約するより、ルートで全体方針を定義し、子階層で領域固有ルールを足すほうが理にかなっています。
ルートには全員共通の開発コマンドやレビュー観点だけを置き、frontend には UI 実装の規約、backend には API 設計や DB 操作の注意、infra には Terraform やデプロイ周りの前提を書く、という分担です。
親と子が競合するというより、広い前提に細かい前提が重なる感覚で考えると整理しやすくなります。

筆者は、サブディレクトリごとに短い CLAUDE.md を置いた構成にしてから、不要な文脈の混入が目に見えて減りました。
以前は frontend のコンポーネント修正でも、リポジトリ全体の長い運用ルールが先に効いて、Claude の提案が少し回り道になることがありました。
apps/web 側に「Server Components を優先」「UI 文言は既存トーンに合わせる」「テストは pnpm test --filter web」のような簡潔な指示を分けておくと、その領域に入った瞬間に必要な前提だけが乗るので、提案の焦点が合いやすくなります。

この設計は、人間のオンボーディングにも近いです。
最初に会社全体のルールを説明し、そのあと配属先のチームルールを渡すほうが理解しやすいのと同じで、Claude にも段階的に文脈を与えるほうが扱いやすいと言えます。

モノレポでの除外: claudeMdExcludes

モノレポでは、親子構造が増えるぶん CLAUDE.md も増えやすくなります。
ここで問題になるのが、「存在するから読ませたい」とは限らないことです。
たとえば apps/web を触っているのに、実験用ディレクトリや保守対象外のパッケージにある CLAUDE.md まで候補に入ると、文脈が散ります。
こうしたケース向けに、不要な CLAUDE.md の読み込みを除外する設定として claudeMdExcludes が使えます。

特に frontend、backend、infra、docs、legacy が同居する大きなモノレポでは、この除外設定の有無で運用感が変わります。
全部を丁寧に書くより、読ませる必要のない木を最初から切っておくほうが、Claude の探索範囲を狭められます。
ドキュメント生成用の補助リポジトリ、過去バージョンの移行コード、検証用 sandbox など、普段の作業に無関係な場所は除外対象として考えやすいところです。

これは CLAUDE.md の内容改善とは別方向の最適化です。
文章を短くするのはもちろん効きますが、そもそも関係ないファイルを読ませないほうが先に効く場面もあります。
モノレポでは「何を書くか」だけでなく、「どの CLAUDE.md を文脈に参加させないか」も設計の一部として見ると、挙動が安定しやすくなります。

長文化が精度・コストに与える影響

CLAUDE.md が長くなると困る理由は、単に読むのが面倒だからではありません。
Claude はセッションの前提としてその内容をコンテキストに持ち込むため、長い CLAUDE.md ほど毎回の会話で使える余白を圧迫します。
Anthropicの『Claude Code のベストプラクティス』でも、CLAUDE.md は短く人間可読に保つことが勧められており、公式の目安は約500行以内です。

この「余白を圧迫する」という感覚は、実際に運用するとよくわかります。
ルートの CLAUDE.md が背景説明や歴史的事情まで抱え込んで長くなるほど、Claude は毎回そこから判断材料を拾うことになります。
すると、目の前のタスクとは関係の薄いルールまで前提に入り、回答やコード提案の焦点がぼやけやすくなります。
短い文書のほうが賢く見えるというより、必要な情報だけ先に渡されるので判断の軸がぶれにくいということです。

コスト面でも無視できません。
Anthropicの『Manage costs effectively』では、Claude Code の平均コストは開発者1人あたり1日 \$6、日次コストの90%は \$12 未満とされています。
さらに Extended thinking のデフォルト予算は 31,999 tokens です。
長い CLAUDE.md 自体がそのまま毎回この予算を使い切るわけではありませんが、常に大きな前提を抱えた状態でやり取りすると、入力トークンも思考トークンも積み上がりやすくなります。
キャッシュが効く場面でも cache hit は標準入力価格の10%で課金されるため、「長いけれどキャッシュされるから無料同然」とは言い切れません。

人間のレビュー負荷で見ても、長文化の不利ははっきりしています。
500行をざっくり 6,000 words 前後とみなすと、通読に約30分かかる計算です。
これが 1,500行級になると 90分規模になり、実務では誰も全体を見直さなくなります。
実践記事で 47k words から 9k words に圧縮した事例が話題になるのも、文量が増えると AI 以前に人間が保守できなくなるからです。
公式は500行を目安にしていますが、現場では 300行未満、場合によっては 200行前後まで削って運用する例が多いのも納得できます。

なお、Auto memory の MEMORY.md に関しては、実務記事やコミュニティ観測で「先頭200行前後を優先的に読む」と整理されることがあります。
しかしこの挙動（何行読むか、どのようにキャッシュされるか等）はバージョンや実装に依存する可能性が高く、公式ドキュメントで確定した仕様とは限りません。
ここでは「実践上の観測・運用目安」として扱い。

Claude Code のベストプラクティス - Claude Code Docs

環境設定から並列セッションでのスケーリングまで、Claude Code を最大限に活用するためのヒントとパターン。

code.claude.com

良い CLAUDE.md に書くべき 5 つの項目

ここでは、CLAUDE.md に何でも書くのではなく、毎回の作業で判断の土台になるものだけを残します。
私自身、最初は背景説明や運用史まで詰め込んでいましたが、結局よく参照されるのは限られていました。
短いのに役に立つファイルは、たいてい次の5項目に収まります。
長文の説明は @README.md や @docs/architecture.md のように外へ逃がし、CLAUDE.md には入口だけを書く形が崩れにくい設計です。

プロジェクト概要

最初にあると効くのは、「このリポジトリは何を作る場所か」「どこまで面倒を見るか」「今回はやらないことは何か」の3点です。
Claude はコードを読む前に前提を持つので、目的と非目標がないと、親切のつもりで余計な提案を混ぜがちです。

• 目的: B2B向け請求管理SaaSのWebアプリを開発する
• スコープ: apps/web と apps/api の機能追加・修正を対象にする
• 非目標: デザイン刷新、インフラ全面移行、legacy/ 配下の改修は含めない

この欄は3行前後で十分です。
仕様の詳細や用語集までここに抱え込むと、概要ではなく本編になります。
読む側が最初の30秒で輪郭をつかめる密度にとどめるのが実務向きです。

主要コマンド

次に固定したいのが、開発・テスト・ビルド・Lint の最小セットです。
ここが曖昧だと、毎回「このプロジェクトは pnpm test ですか、npm run test ですか」と聞き返されます。
実際、主要コマンドを書いてからは、セッションのたびに実行方法を説明する場面がほぼ消え、やり取りの往復が目に見えて減りました。

• 開発: pnpm dev
• テスト: pnpm test
• ビルド: pnpm build
• Lint: pnpm lint

コマンドは「たぶん使うもの一覧」ではなく、「まずこれを打てば困らないセット」に絞るのがコツです。
E2E、Storybook、DB seed のような補助系まで並べたくなりますが、頻度が低い手順は @README.md や @docs/development.md に送ったほうが、日常運用の摩擦が減ります。

アーキテクチャ判断

ここには、採用技術の名前だけでなく、「なぜそれを外してはいけないのか」を短く書きます。
Claude は新しい案を出すのが得意ですが、既存方針を知らないまま提案すると、正しそうでもチームの判断を踏み外します。
代替不可の理由と、例外をどこまで許すかがあると、提案の方向が揃います。

• 状態管理は Redux Toolkit を使い、グローバル共有が必要な状態のみ置く
• データ取得は React Query に統一し、独自 fetch ラッパーを増やさない
• DBアクセスは apps/api の repository 層を経由し、route handler から直接 ORM を呼ばない

この項目では、技術選定の歴史を長く語る必要はありません。
「採用技術」「避けたい代替」「判断原則」が1行ずつ見えるだけで十分です。
詳細なADRがあるなら @docs/adr/ を示し、CLAUDE.md には結論だけ残す形が収まりません。

コーディング規約

Lint や Formatter で自動化できる部分よりも、人が迷う判断を書いておくと効きます。
たとえば命名、責務の切り方、ディレクトリの置き場所、UI とロジックの分離方針は、静的チェックだけでは揃いません。
ここがないと、Claude は「通るコード」は出せても「このチームらしいコード」にはなりません。

• hooks は useXxx で命名し、副作用を持つ処理を component 本体に直書きしない
• features/ 配下は機能単位で分け、components/common に業務依存UIを置かない
• boolean は is/has/can で始め、略語だけの変数名を作らない

プロジェクト固有の癖は、一般論より価値があります。
たとえばNext.jsやTypeScriptの一般的な書き方は外部情報でも拾えますが、「このリポジトリでは server action をどこに置くか」「DTO と domain model を分けるか」は内部文脈そのものです。
そうした判断だけを短く残すと、生成物のブレが減ります。

検証フロー/レビュー観点

コードを書いたあとに何を確認するかまで書いておくと、提案の質が安定します。
レビューで毎回見る観点が決まっているなら、Claude にも先に渡したほうが手戻りが減ります。
特にセキュリティ、性能、破壊的変更の確認は、機能実装の陰に隠れやすい判断材料になります。

• PR前に pnpm lint && pnpm test && pnpm build を通す
• 変更した画面は主要操作を手動確認し、空状態・読み込み中・エラー表示も見る

この欄では、テスト観点を網羅表にするより、「落とすと事故になるもの」を先に置くと運用に乗ります。
ブラウザ差分のような細かな確認手順まで広げるより、PR のたびに必ず見る観点を固定するほうが効きます。
長くなる検証手順は @docs/testing.md に分け、CLAUDE.md には入口のチェックリストだけ置く形が扱いやすいのが利点です。

5項目を書き切っても長いと感じたら、各見出しの役割を「前提」「入口」「禁止事項」に絞ると削れます。実務では、ルートの CLAUDE.md は短い索引にして、説明本体を @README.md や @docs/ に逃がしたほうが、読み返す側も保守する側も迷いません。

書かないほうがよい内容とアンチパターン

アンチパターン一覧

CLAUDE.mdで精度を落としやすいのは、足りないことより、書き込み先を間違えた情報が積み重なることです。
特に混ざりやすいのが、一時的な進捗ログ、作業中の感想、期限の切れた TODO です。
「今は API だけ実装済み」「後で E2E を足す」「この方針でいったん進める」といった文は、その場では役に立っても、次のセッションではノイズになりやすいのが利点です。
こうした情報は人間の作業メモか Auto memory に逃がし、CLAUDE.mdには永続前提だけ残したほうが、判断の軸がぶれません。

コードから読めることを文章で重ねるのも、典型的な過積載です。
たとえば formatPrice(price, currency) という関数があるのに、「価格を通貨付き文字列に変換する関数」と延々書いても、モデルに新しい判断材料は増えません。
コンポーネントの props やディレクトリ構造をそのまま説明した一覧も同様で、すでにリポジトリにある事実をもう一度 prose に展開すると、読むべき規則が埋もれます。
CLAUDE.mdに残す価値があるのは、コードからは分からないチーム判断です。

スタイル指定の書きすぎにも注意が必要です。
インデント幅、クォート、セミコロン、 import 順のように lint や formatter で固定できる内容まで文章で縛ると、毎回読む前提ばかり増えます。
『Claude Code のベストプラクティス』 が短く保つことを勧めているのも、この種の情報を道具に寄せられるからです。
CLAUDE.md側で持つべきなのは、「自動整形では表現できない例外方針」だけです。
たとえば「テストコードでは一時的な any を許容しない」「UI 層から ORM 型を直接参照しない」といった、静的整形では担保できない線引きに絞ると効きます。

毎回参照しない詳細仕様やデータ一覧を本体に貼り込む運用も、精度を鈍らせます。
自分の経験でも、長い仕様原文をCLAUDE.mdに直接貼っていた時期は、指示の要点より引用文の細部に引っ張られ、解釈が揺れる場面がありました。
@specs/〜のように分離して必要時だけ参照させる形に変えてからは、常時読む前提が短くなり、指示の受け取り方が安定しました。
ルートには結論だけ置き、重い一次資料は @import で呼ぶほうが、モデルにも人間にも扱いやすい構成になります。

セッション中にClaudeが気を利かせて追記した運用メモを、そのまま永続化するのも避けたい流れです。
たとえば「このリポジトリでは先に grep してから編集する」「この画面は触る前にスクリーンショットを残す」といったメモは、文脈依存のその場ルールであることが少なくありません。
検証前の気づきを全部残すと、数日後には由来の分からないお願い集になります。
実際に運用して定着したものだけを採択し、採択後は最小表現に削る。
この一段階を挟むだけで、CLAUDE.mdはぐっと締まります。

もうひとつ厄介なのが、「お願いの羅列」です。
「丁寧にやってください」「既存実装に合わせてください」「読みやすくしてください」「保守性を意識してください」といった文は、一見もっともらしく見えても、具体的な判断には変換されません。
抽象的な依頼が積み上がるほど、どれを優先するのかが曖昧になります。
禁止事項、判断基準、優先順位の3つに分けて短く置くほうが、生成結果のぶれを抑えられます。

どこへ逃がすかの判断基準

迷ったときは、「その情報は毎セッション共通で効くか」「コードを読んでも分からないか」「判断を変える力があるか」で振り分けると整理しやすくなります。
3つとも満たすならCLAUDE.mdに置く価値があります。
逆に、作業の途中経過、単発の会話メモ、将来消える予定の TODO は、永続指示に入れる理由がありません。
実務記事で語られるAuto memoryやMEMORY.mdの整理は、まさにこの一時情報の受け皿として相性がよい考え方です。

詳細仕様の扱いでは、「毎回読む必要があるか」を基準にすると判断しやすくなります。
API の全レスポンス一覧、業務コード表、画面ごとの例外条件のような大きい資料は、常駐させるより @docs/ や @specs/ に分けたほうが、日常セッションの視界を汚しません（内部ドキュメントとして分離します）。
CLAUDE.mdには「受注ステータスの定義は @specs/order-status.md を参照」と入口だけ書けば足ります。
公式でもCLAUDE.mdは約500行以内が目安とされており、コミュニティではそれより短い運用が支持されるのは、こうした責務分離を前提にしているからです。

スタイル関連は、「ツールで強制できるか」で即決できます。
ESLint や Prettier で固定できるなら設定ファイルへ、保存時に必ず走らせたいなら Hooks へ、たまにしか使わない手順なら Skills へ回すのが自然です。
CLAUDE.mdに残すのは、ツール化しにくい設計判断やレビュー観点だけで十分です。
たとえばTypeScriptでの import 並び順は ESLint に任せ、依存の向きや責務分離の原則だけを文章で持つ、という分担のほうが情報の重複が減ります。
スタイル関連は、「ツールで強制できるか」で即決できます。
ESLint や Prettier で固定できるなら設定ファイルへ移し、保存時に必ず走らせたい処理は Hooks に任せるのが自然です。
運用メモについては、「その場の学び」から「チームの規則」へ昇格したかで見分けると判断しやすくなります。
セッション中に見つかったコツは、いったん別メモに置いて何度か再現し、採用すると決めた時点で要点だけを永続化する流れが堅実です。
ここを省くと、Claudeが親切心で書き足したメモが堆積し、読む側には由来不明のローカルルールに見えてきます。
永続化の条件を厳しくするほど、CLAUDE.mdは「覚えてほしいこと」だけが残る形に近づきます。

文量の感覚がつかみにくい場合は、人間が読める長さに置き換えると判断しやすくなります。
公式目安の約500行は、語数換算ではおおむね 6,000 words 規模で、紙にすると約20ページ分です。
このくらいならオンボーディングでもレビューでも現実的ですが、そこに進捗ログや仕様原文まで抱え込むと、一つひとつは正しくても全体の見通しが崩れます。
必要な情報を削るのではなく、置き場を分ける。
その発想で整理したほうが、CLAUDE.mdは長期運用で傷みにくくなります。

肥大化を防ぐ設計: CLAUDE.md と .claude/rules/ と Skills と Hooks の使い分け

このセクションで押さえたいのは、置き場ごとの責務を先に決めることです。
CLAUDE.mdに何でも集める運用は、書き始めは楽でも、数週間で「どこに何があるか分からない」状態に寄っていきます。
実務では、一枚絵として CLAUDE.mdは広く適用される前提、.claude/rules/ は関心ごとやパス単位の分割、Skills はオンデマンドの手順、Hooks は決定論的に毎回走らせる処理、@import は詳細資料の参照先 と置くと、迷いどころが減ります。

判断フローもこの順で考えると収まりがよくなります。
毎回必ず実施したいなら Hooks、プロジェクト全体の前提ならCLAUDE.md、特定領域だけに効かせたいなら .claude/rules/、たまに使う専門ワークフローなら Skills、説明が長くなる資料は @import です。
人間が統制したいルールを Auto memory に置く発想だけは外したほうが安定します。
Auto memory は補助記憶としては便利でも、チームルールの正本には向きません。
このセクションで押さえたいのは、置き場ごとの責務を先に決めることです。
CLAUDE.mdに何でも集める運用は、書き始めは楽でも、数週間で「どこに何があるか分からない」状態に寄っていきます。
比較すると役割の違いが見えやすくなります。

CLAUDE.md

Claude Code のベストプラクティスではCLAUDE.mdを短く保つ方針が示されており、広く効く前提だけを置く設計と相性がいいです。
ルートのCLAUDE.mdは、チーム全員に共通する「このリポジトリでは何を前提に動くか」を伝える索引だと考えるとまとまります。
実務では 1 本の長文説明より、見出しごとに短く切ったほうがメンテナも読み返せます。

入れる内容は、まずプロジェクト概要です。
たとえば「このプロジェクトはNext.jsフロントエンドとFastAPIバックエンドのモノレポ。
注文管理と在庫同期が主機能」のように、何のためのコードベースかを 2 行で示します。
主要コマンドなら「開発は pnpm dev、単体テストは pnpm test、型検査は pnpm typecheck」という形が素直です。
アーキテクチャ判断は「新規 API は BFF を経由し、フロントエンドから基幹 API を直接呼ばない」のように、迷ったときの分岐点だけを書きます。
コーディング規約では「TypeScriptでは any を増やさず、zod で入出力境界を検証する」といったツール設定では拾いきれない規約が向いています。
検証フローやレビュー観点は「変更後は pnpm test と pnpm typecheck を通す。
レビューでは責務の逆流と例外処理の欠落を見る」と短く置くと、会話ごとの判断が揃います。
自分の運用でも、ここに「編集後は整形してテストも見てください」と書いていた時期は、守られる回と抜ける回がありました。
文章でお願いする限り、手順としては読まれても、実行の保証にはなりません。
その種のものを Hooks に移してから、整形漏れやテスト起動忘れが消え、ルートのCLAUDE.mdには「何を守るか」だけが残りました。
結果として、読む側の負荷も下がります。

.claude/rules/

.claude/rules/ は、全体ルールを細かく分けたいときの主戦場です。
CLAUDE.mdに「frontend ではこう、backend ではこう、infra ではこう」と並べ始めると、全員に不要な文脈まで常駐します。
そこで rules に分け、関心ごとやパスごとに適用範囲を絞ると、誤適用が減ります。

典型は領域別の規約です。
たとえば frontend/ 向けには「データ取得はReact Query経由に統一し、fetch の直書きは避ける」、backend/ 向けには「DB 更新は service 層でトランザクションを閉じる」、infra/ 向けには「Terraformの module 追加時は environment 差分を variables に寄せる」といった書き方です。
Git 運用を分けるのも相性がよく、レビュー観点は rules に逃がせます。
たとえば「マイグレーションを含む変更は schema 差分を PR 説明に必ず含める」のような観点です。

Skills

Skills は、読まれる頻度が低いが、読まれたときにはまとまった手順が必要なものに向いています。
普段の開発で毎回参照する内容を Skills に入れると、必要な前提が会話に現れません。
一方で、たまにしか出番のない運用をCLAUDE.mdへ入れると、常時読むには重すぎます。
この中間を埋めるのが Skills です。

たとえば PR 作成の流れは Skills 向きです。
「変更要約を 3 行で書く」「影響範囲を frontend backend infra に分けて整理する」「再現手順と検証コマンドを添える」といったまとまった手順は、毎回の前提ではなく必要時に呼び出す形が合います。
障害調査も同じで、「ログ確認、再現条件の切り分け、暫定回避、恒久対応の順で進める」といったワークフローは Skills に置いたほうが本文の密度を保てます。

短い記述例もその発想で考えると作りやすいのが利点です。
プロジェクト概要は Skills には不要で、代わりに「Sentryアラート対応 Skill」など目的をタイトルで示します。
主要コマンドは「障害調査では docker compose logs api と pnpm test --filter orders を使う」。
アーキテクチャ判断は「暫定対応では公開 API を変えずに内部実装で吸収する」、コーディング規約は「調査用ログは恒久コードに残さない」、検証フローは「再現ケースを 1 つ追加してから修正する」といった粒度がちょうどいいです。
読むとそのまま進められるが、毎回ロードするほどではない。
そこに Skills の価値があります。

Hooks

Hooks は「お願い」ではなく「実行」に変えるための置き場です。
ここを文章で済ませると、守る前提はあっても、機械的な保証にはなりません。
毎回必ず走らせたい整形や検証は、最初から Hooks に寄せたほうが運用が安定します。

自分の現場でも、ビルド後の自動整形やテスト起動を長くCLAUDE.mdに書いていましたが、どれだけ丁寧に書いても抜けるときは抜けました。
Hooks に移してからは、編集のたびに同じ処理が同じ順序で走るので、レビュー前に「format が当たっていない」「最低限のテストが回っていない」と気づく場面がほとんど消えました。
文章の説得力を上げるより、決定論的な仕組みに変えたほうが効きます。

書く内容も明確です。
プロジェクト概要を Hooks に置く必要はありません。
主要コマンドは「ファイル編集後に pnpm exec prettier --write」「特定パス変更後に pnpm test --filter web」のように、そのまま実行される形にします。
アーキテクチャ判断は Hooks ではなく文書側が担当し、Hooks は「判断の結果を壊していないか」を機械で見ます。
コーディング規約も同じで、eslint や formatter で検査できるものは Hooks と設定ファイルに任せるのが自然です。
検証フローやレビュー観点に関しては、「コミット前に型検査」「生成ファイル更新の確認」のように再現可能なものだけを Hooks に置き、設計レビューの観点までは持ち込まないほうが濁りません。

@import

@import は、ルートに置くには長いが、切り捨てると判断材料がなくなる資料の逃がし先です。
前のセクションでも触れた通り、仕様原文や画面別の例外条件までCLAUDE.mdへ抱え込むと、索引ではなく倉庫になります。
@import を使うと、入口だけを短く保ったまま、必要な詳細へつなげられます。

実務で相性がいいのは、一次資料の参照です。
たとえばプロジェクト概要の補足として「受注ステータスの業務定義は @specs/order-status.md を参照」、主要コマンドの補足として「ローカル起動の詳細は @docs/dev-setup.md」。
アーキテクチャ判断の背景として「集約境界の説明は @docs/architecture/bounded-context.md」、コーディング規約の例外条件として「API エラー仕様は @docs/api/error-contract.md」、検証フローの詳細として「E2E シナリオ一覧は @docs/testing/e2e-matrix.md」という形です。
入口は短く、詳細は分離。
この構図なら、ルートの密度を保てます。

詳細を毎回読む前提から外すだけで、会話の焦点がぶれにくくなります。資料を捨てるのではなく、読む条件を切り替えるのが判断材料になります。

Auto memory

Auto memory は、ここまでの置き場とは性格が違います。
人間が「このルールを絶対に守らせる」と決めて置く場所ではなく、補助的な記憶として扱うほうが混同しません。
Claude があなたのプロジェクトを記憶する。

ここを混ぜると、どこを見れば最新のチーム方針が分かるのか曖昧になります。
たとえばプロジェクト概要、主要コマンド、アーキテクチャ判断、コーディング規約、検証フローやレビュー観点は、チームが意図して更新する情報なのでCLAUDE.mdや rules に置くべきです。
短い記述例なら「開発コマンドは pnpm dev」「新規 API は BFF 経由」「レビューでは例外処理と責務境界を見る」といった内容です。
これらを Auto memory 任せにすると、運用の正本が人間の手元から離れます。

Auto memory は補助的な記憶機構として便利ですが、MEMORY.md の読み込み行数や優先度のような細かな内部挙動については、実践観測と公式仕様が一致しない場合があります。記事内で挙げる数値（先頭○○行を読む等）はあくまで運用上の目安として明示してください。正式な挙動を確認する場合は Anthropic / Claude Code の公式ドキュメントを直接参照することをおすすめします。

そのまま使える CLAUDE.md テンプレート

小規模プロジェクト用テンプレ

最初の一枚は、説明書というより索引に寄せたほうが運用が続きます。
私もはじめは /init の出力に背景説明を足していましたが、数回の更新で読む側も書く側も息切れしました。
そこからは最小テンプレで始めて、細部が増えた箇所だけ @import を差し込む形に変えています。
この流れだと、日々触る本体は短いまま保てて、維持の負担が目に見えて下がります。

10〜30行で収めるなら、5項目だけで十分です。
短く保つ方針とも噛み合います。
（注）Auto memory や MEMORY.md の読み込みに関する細かな挙動（例: 先頭数百行の優先読み込みなど）は、コミュニティの実践観測として語られることがあります。
本記事ではそうした記述を「運用上の目安」として扱い、公式仕様と混同しないよう明示しています。
公式な挙動を確認する必要がある場合は、Anthropic / Claude Code の公式ドキュメントを直接参照してください。

# Project overview

- B2B向け在庫管理アプリ。受注・出荷・棚卸を扱う。
- 詳細な業務用語は @README.md を参照。

# Main commands

- 開発: `pnpm dev`
- テスト: `pnpm test`
- 型検査: `pnpm typecheck`

# Architecture decisions

- 画面からDBへ直接触らず、API経由で更新する。
- 状態管理は React Query を優先。グローバル state の新規導入は避ける。

# Coding conventions

- TypeScript は strict 前提。`any` は禁止。
- UI文言は直書きせず、既存の文言管理に追加する。

# Validation / review

- 変更後は `pnpm test` と `pnpm typecheck` を通す。
- レビューでは例外処理、責務分離、既存命名との一貫性を見る。

短く保つコツは、段落で説明しきろうとしないことです。
箇条書きで原則を書く、禁止リストで事故を減らす、判断基準を一行で置く。
この3種に寄せると密度が上がります。
たとえばコーディング規約なら「any 禁止」が禁止リスト、アーキテクチャ判断なら「DB直アクセス禁止」が判断基準です。
背景説明が2文を超えそうなら、本体ではなく @docs/architecture.md に逃がしたほうが収まりがよくなります。

モノレポ用テンプレ

モノレポでは、ルートに全部を書くとすぐ破綻します。
起動時に読む全体方針と、対象ディレクトリに入ったときだけ読む領域別ルールを分けるほうが、誤適用も減ります。
実務でも、ルートは共通前提だけ、frontend/ と backend/ は各領域の作法だけ、という切り方が一番安定しました。

まずはルートの最小形です。

# Project overview

- Monorepo。`frontend/` は Web UI、`backend/` は API。
- リポジトリ全体の概要は @README.md を参照。

# Main commands

- 全体起動: `pnpm dev`
- 全体テスト: `pnpm test`
- 依存更新後の確認: `pnpm typecheck`

# Architecture decisions

- 共有型は `packages/` 経由で配布し、相対参照で横断共有しない。
- 領域固有の判断は各ディレクトリの `CLAUDE.md` を優先する。

# Coding conventions

- パッケージ間 import は公開APIのみ使う。
- 生成物の直接編集は禁止。

# Validation / review

- 影響範囲のパッケージ単位でテストする。
- レビューでは境界越え依存と破壊的変更を確認する。

frontend/CLAUDE.md は、UI 側の判断だけに絞ります。

# Project overview

- `frontend/` は Next.js ベースの管理画面。
- 画面構成の詳細は @frontend/README.md を参照。

# Main commands

- 開発: `pnpm --filter frontend dev`
- テスト: `pnpm --filter frontend test`
- Lint: `pnpm --filter frontend lint`

# Architecture decisions

- データ取得は Server Actions ではなく既存APIクライアントを優先。
- フォームは既存の `components/form/` を再利用する。

# Coding conventions

- CSS は既存トークンを使う。色コード直書きは禁止。
- 新規UIは `frontend/src/features/` 配下に置く。

# Validation / review

- 変更画面の表示崩れと文言差分を確認する。
- レビューではアクセシビリティ属性と状態遷移を見る。

backend/CLAUDE.md も同じく、サーバー側だけを書きます。

# Project overview

- `backend/` は Node.js の API サービス。
- API仕様の詳細は @docs/api.md を参照。

# Main commands

- 起動: `pnpm --filter backend dev`
- テスト: `pnpm --filter backend test`
- 型検査: `pnpm --filter backend typecheck`

# Architecture decisions

- DBアクセスは repository 層を通す。
- 外部公開レスポンスは DTO で整形し、 ORM の生オブジェクトを返さない。

# Coding conventions

- 例外は共通エラー型で返す。
- migration を伴う変更では schema とコードを同時更新する。

# Validation / review

- 変更エンドポイントのテストを追加する。
- レビューでは後方互換性、トランザクション境界、ログ出力を確認する。

巨大なモノレポでは、不要な CLAUDE.md を読ませない設定も効きます。
前述の分割に加えて claudeMdExcludes を使うと、関係ない領域の前提が混ざりにくくなります。
ルートに全知識を集めるより、読む条件を設計したほうが、オンボーディングでも日常運用でも迷いが減ります。

@import活用の書き方

@import は長文化の逃げ道ではなく、入口を短く保つための設計です。
本体に置くのは判断に必要な要約だけ、詳細は別ファイルに渡す。
この形にすると、CLAUDE.md 全体を紙で20ページ近い説明書に育てずに済みます。
読むべき本体が短ければ、初日に方針をつかむ時間も取りやすくなります。

書き方は単純で、本文では「何のために参照するか」まで書きます。参照先のパスだけ置くより、使う場面が伝わります。

# Project overview

- 業務用語とドメイン境界は @docs/architecture.md を参照。
- セットアップ手順は @README.md を参照。

# Main commands

- 補助コマンド一覧は @package.json を参照。
- E2E 実行条件は @docs/testing/e2e.md を参照。

# Architecture decisions

- 例外的に同期APIを使う理由は @docs/architecture.md を参照。
- 画面別の責務分担は @docs/frontend/screens.md を参照。

# Coding conventions

- 命名規約の詳細例は @docs/coding-style.md を参照。
- ESLint で表現できない例外は @docs/lint-exceptions.md を参照。

# Validation / review

- PRレビュー観点の詳細は @docs/review-checklist.md を参照。
- 回帰確認の対象一覧は @docs/testing/regression.md を参照。

短く保つなら、@import の前にもルールがあります。
まず、箇条書きで要約を書くこと。
次に、禁止リストを一行で置くこと。
さらに、判断基準を添えることです。
たとえば「長い仕様を丸ごと貼らない」「例外条件は参照先へ送る」「毎回必要な原則だけ本体に残す」といった形です。
これだけでも、CLAUDE.md が倉庫になるのを防げます。

• 禁止: 仕様書全文の転載
• 判断基準: 毎回読む必要がある内容だけ本体に置く
• 長文: @docs/specs/order-flow.md

> [!NOTE]
> `@import` の再帰的な参照が深く連なってしまう課題があり、運用上の目安として「5階層前後」を想定する例が散見されます。ただし、これはコミュニティの観測・運用知に基づく目安であり、公式ドキュメントで確定された仕様ではありません。運用ポリシーを決める際は公式ドキュメントを確認したうえで、チーム内の実測や管理上のしきい値を定めてください。
参照先の例も、実務では定番があります。プロジェクト概要は `@README.md`、コマンドは `@package.json`、設計判断は `@docs/architecture.md`、レビュー観点は `@docs/review-checklist.md` といった分け方です。Claude があなたのプロジェクトを記憶する。テンプレから始めて、必要が出た箇所だけ `@import` を差し込む運用にすると、更新のたびに全体を読み直す回数が減り、手入れの単位も小さく保てます。

{{related:claude-code-mcp}}
## モノレポ・大規模案件での分割パターン

### 階層分割の基本形

モノレポで `CLAUDE.md` を1枚に寄せると、最初は管理が楽に見えても、領域ごとの前提が混ざった瞬間に破綻しがちです。Claude Code のベストプラクティスでも `CLAUDE.md` は短く保つ前提が整理されており、実務ではルートは全体方針だけに絞る運用が安定することが多いです。なお、`@import` の再帰的な参照深度については、実務記事やコミュニティ観測で「運用上は5階層前後を目安にする」などの整理が見られますが、これはあくまで実践観測に基づく運用目安であり、公式仕様で確定した値ではありません。チームで運用ルールを決める際は。

基本形は、ルート `CLAUDE.md` に全体共通の前提だけを書き、`frontend/CLAUDE.md` と `backend/CLAUDE.md` に領域固有の規約を置く形です。ルートにはリポジトリ全体の目的、共通コマンド、ブランチ運用、レビューの最低条件のような「どこを触っても効く話」だけを残します。一方で、React の状態管理方針や UI コンポーネント規約は `frontend/CLAUDE.md`、DTO や repository 層、トランザクション境界の扱いは `backend/CLAUDE.md` に逃がします。こうしておくと、対象ディレクトリに入ったときだけ必要な文脈が追加されるので、探索の起点がぶれません。

たとえば次のような役割分担が扱いやすいです。

| ファイル | 主に置く内容 | 置かない内容 |
|---|---|---|
| ルート `CLAUDE.md` | 全体方針、共通コマンド、横断レビュー観点 | frontend 専用の UI 規約、backend 専用の DB 規約 |
| `frontend/CLAUDE.md` | 画面構成、状態管理、CSS 方針、Storybook や E2E の前提 | API の例外設計、DB migration 手順 |
| `backend/CLAUDE.md` | レイヤ構成、DTO、ORM の扱い、テスト観点 | UI 命名、デザインシステム運用 |

この分け方だと、ルートの `CLAUDE.md` は入口として読める長さに保ちやすく、サブ領域のファイルもそのチームが自分たちで更新できます。公式の目安は約500行以内ですが、モノレポでは「1枚に収める」より「1枚ごとの責務を狭くする」発想のほうが効きます。

### .claude/rules/ の paths 設計

階層分割だけでも効果はありますが、規約の粒度がさらに細かいなら `.claude/rules/` を併用したほうが収まりがよくなります。ここで役立つのが `paths:` による条件付き適用です。`CLAUDE.md` は領域の前提、rules は特定パスにだけ効かせる規則、と考えると設計しやすくなります。

たとえば `frontend/CLAUDE.md` には「UI 実装は Server Components を優先する」「フォームは既存の設計に合わせる」といった方針を書きます。さらに `.claude/rules/` では `frontend/src/components/**` 用のルール、`frontend/src/pages/**` 用のルールを分けます。backend 側でも `backend/src/api/**` と `backend/src/db/**` で分離すると、API 層と永続化層の約束を混同せずに済みます。

設定例は概念的には次のようなイメージです。

name: frontend-components paths:

• frontend/src/components/**

description: コンポーネント実装時の規約

name: backend-api paths:

• backend/src/api/**

description: API 層のレスポンス設計と例外処理の規約

この設計の利点は、1つの巨大な規約ファイルを毎回読ませるのではなく、触っている場所に応じて必要なルールだけを効かせられる点にあります。モノレポでは `packages/web` と `packages/api` で言葉の意味が違うことが珍しくありません。`paths:` を切っておくと、同じ「validation」という単語でも、画面入力チェックの話なのか API 入力検証の話なのかが文脈で自然に分かれます。結果として、ルール同士の衝突より「その場に必要な説明だけが出てくる」状態に近づきます。

{{ogp:https://tech-lab.sios.jp/archives/51064|Claude Code: CLAUDE.md vs .claude/rules/ の実践的な使い分け|メタディスクリプション：CLAUDE.mdと.claude/rules/、どちらを使うべき？チーム開発では中央管理、特殊ディレクトリは分散管理がおすすめ。比較表とフローチャートで解説。|https://tech-lab.sios.jp/wp-content/uploads/2026/01/2026-01-26_claude-2line_001.jpg}}

### claudeMdExcludes の考え方

モノレポが大きくなると、読むべき `CLAUDE.md` を増やすだけでは足りません。**読まなくてよいものを除外する設計**も同じくらい効きます。そこで出てくるのが `claudeMdExcludes` という考え方です。これは「巨大リポジトリで、無関係な `CLAUDE.md` の読み込みを避ける」という目的で語られることが多く、設定値そのものを覚えるより、何を防ぐための仕組みかを押さえたほうが役に立ちます。

典型例は、`frontend/` を触っているのに `infra/` や `data-pipeline/` の前提まで混ざってくるケースです。指示が多いほど賢くなるわけではなく、関係ない制約が入ると判断の軸が増えて迷走しやすくなります。とくにモノレポでは、同じ TypeScript でも `packages/web` と `packages/cli` で求める作法が違います。不要スコープを除外しておくと、関係ないローカルルールを抱え込まずに済みます。

私がこの設計を効くと感じたのは、ルートに多くを書かず、各領域の `CLAUDE.md` も短くしたうえで、さらに不要領域を読まない形にしたときでした。それまでは「この修正はどの前提に従うのか」を毎回確認する流れになりがちでしたが、除外対象を明確にしてからは、対象外ディレクトリの知識が会話に割り込む場面が減りました。結果として、同じ質問を言い換えて説明し直す回数も減りました。探索コストを下げるには、情報を増やすより、入口を狭くするほうが効く場面があります。

### 関連ファイルを明示するプロンプト例

大規模案件では、ファイル設計だけでなく、プロンプト側でも探索範囲を切ると安定します。とくにモノレポでは「どこを見ればいいか」を先に渡したほうが、関係ない領域へ飛ぶ確率を下げられます。短い局所 `CLAUDE.md` と、関連ファイルを明示する依頼文は相性がよく、迷走の抑制に直結します。

たとえば実務では、次のような書き方がそのまま使えます。

関連するのは packages/app と packages/web です。
該当領域の CLAUDE.md と rules のみ参照してください。
ルート CLAUDE.md の共通方針は守りつつ、infra や backend の文脈は使わないでください。

今回の修正対象は frontend/login と backend/auth-api です。
frontend/CLAUDE.md、backend/CLAUDE.md、ならびに該当 paths の rules だけを前提に実装方針を考えてください。
関連しない packages は探索しないでください。

packages/app の注文画面と packages/web の共有 UI が関係します。
まず参照対象を列挙し、その範囲の CLAUDE.md と rules に基づいて変更案を出してください。

この一文があるだけで、対象外ディレクトリの規約まで拾ってきて話が広がる事故を抑えられます。モノレポ運用では、良い `CLAUDE.md` を書くことと同じくらい、「今回見るべき領域はここです」と明示することが効きます。構成が整理されていても、探索開始点が曖昧だと結局広く読み始めるからです。反対に、ルートは薄く、局所ファイルは短く、プロンプトでは関連領域を先に切る形にすると、会話の初手から対象が揃います。これが大規模案件での分割パターンの肝です。

## よくある失敗と改善フロー

### /init の使いどころ

`/init` は、白紙から最初の土台を出すには便利です。ただし、そのまま常設の `CLAUDE.md` に昇格させる前提で使うと、運用はすぐ重くなります。初回生成では、プロジェクトの説明、ディレクトリ構成、開発フロー、用語整理まで一気に盛り込まれがちですが、その中にはコードを見ればわかる説明や、毎回読ませるほどではない補足も混ざります。そこで実務では、`/init` の出力を「完成品」ではなく「たたき台」と見なすのが安定します。

私が最も失敗しやすいと感じたのもここでした。最初は `/init` 直後の下書きに少しずつ追記していき、気づくと説明文が膨らみ、会話のたびに前提が揺れていました。そこで1スプリントだけでも運用を変え、`/init` で素案を作ったあとに不要説明を削り、短い方針へ寄せる流れに固定したところ、応答のブレが目に見えて減りました。足すより削るほうが、Claude の判断軸が揃います。

残す基準はシンプルで十分です。まずは**概要、主要コマンド、検証手順**の3要素だけを芯にして、そこに共通で効く方針を少量だけ足します。ディレクトリ一覧の長い説明や、コードから自明な命名規則の解説は、最初に削る候補です。公式は約500行以内を目安にしていますが、運用感としてはその上限まで使い切る発想より、200〜300行以下に収まる状態へ寄せたほうが見直しも会話も軽くなります。

### 生成後はまず削る

生成物を見た直後は、足りないものを足したくなります。実際には逆で、最初にやるべき作業は削減です。`/init` 由来の文章には「親切だけれど毎回は不要」な情報が多く、そこを放置すると、どの指示が本当に守ってほしいものなのかが埋もれます。

削る順番も決めておくと迷いません。まず削るのは、コードを読めばわかる説明です。たとえば「`src/components` には UI コンポーネントがある」のような記述は、初見の人向け資料としては機能しても、永続指示としては重複になりやすいです。次に削るのは、例外込みで長文化した手順です。例外条件が多い運用は `CLAUDE.md` に押し込まず、前述の通り `rules` や補助ファイルへ逃がしたほうが崩れません。

実務では、生成直後の原稿から**概要、主要コマンド、検証手順**だけ残し、それ以外を一度ほぼ落としてから再追加するくらいでちょうどよいです。この順番にすると、「何を常設し、何を都度渡すか」が自然に分かれます。47k words から 9k words へ圧縮した事例が話題になったのも、長い説明を磨き込むより、先に捨てるほうが効くからです。文量が減ると人間側のレビューも回り、誰も読まない規約が増殖する流れを止められます。

> [!WARNING]
> 1〜2週間ごとに見直すなら、全部をリライトする必要はありません。実際に守られなかった指示だけを拾い、その行だけ言い換えるか、別の置き場へ分離するほうが運用に乗ります。

### ルール未遵守時の見直し

Claude がルールを守らないとき、まず疑うべきなのはモデルの気分ではなく、置き場と書き方です。`CLAUDE.md` に「お願い」を並べる形は、見た目以上に弱く出ます。毎回必須の処理、特定領域だけの規約、たまに呼び出す専門手順が同じ場所に混ざると、重要度の差が消えるからです。

たとえば「編集後に必ず lint を実行する」は文章でお願いするより、Hooksに寄せたほうが機械的に通ります。「frontend ではこの UI 規約を守る」は.claude/rules/で領域を切ったほうが、backend の作業に混ざりません。「PR 作成時のチェック観点」のように毎回ではない手順はSkillsに置くと、必要な場面だけ呼べます。Anthropicのベストプラクティスでも、広く適用する知識だけを `CLAUDE.md` に残し、毎回必須の処理はHooks、ときどき使うワークフローはSkillsへ分ける考え方が示されています。

見直しの観点は3つです。ひとつ目は、その指示が**本当に毎回必要か**。ふたつ目は、**特定領域だけのルールではないか**。みっつ目は、**文章ではなく自動実行に寄せられないか**です。この整理をせずに「守られないのでさらにお願いを追加する」を繰り返すと、`CLAUDE.md` は長くなるのに効き目は薄くなります。行数が増えるほどレビューの負担も積み上がるので、守られない指示ほど、短く言い換えるか別ファイルへ分ける判断が必要です。

### セッション途中の変更の扱い

セッション途中で `CLAUDE.md` を書き換えると、その内容を今この瞬間から当然のように前提化したくなります。ここは運用上の落とし穴です。起動時に読む前提ファイルとして扱うなら、途中変更は「次回セッションから効くもの」と考えたほうが混乱しません。今の会話で確実に反映してほしいなら、変更内容をその場で短く言い直して再認識させる必要があります。

このズレを放置すると、「書き換えたのに守られない」という誤解が起きます。実際には、ファイルを書き換えた事実と、会話の前提として再ロードされた事実は別です。とくに方針を整理しながら作業する場面では、途中で `CLAUDE.md` を更新して安心し、そのまま次の依頼を投げて意図がずれる流れが起きやすいです。

運用としては、セッション途中の修正は二段階で扱うと安定します。ひとつは今の会話用に、変更点を短く明示すること。もうひとつは、永続設定として次回起動時に効かせることです。この切り分けを決めておくと、途中編集を前提化して会話が噛み合わなくなる場面を減らせます。

### Auto memory との役割分担

`Auto memory` は便利ですが、そこへ統制ルールまで預けると責任境界が曖昧になります。人間が厳密に管理したい方針、たとえば「このリポジトリでは `pnpm test` を正とする」「レビューではアクセシビリティ観点を必須にする」のような統制は、`CLAUDE.md` や `rules` 側に置いたほうが管理しやすくなります。`Auto memory` は、会話の中で学んだ癖や補助メモを蓄える場所として使うほうが筋がよいです。

この役割分担を崩すと、どのルールが誰の管理下にあるのか見えなくなります。比較すると、`CLAUDE.md` は人間が書く永続指示、`Auto memory` は Claude が自動で蓄積する補助メモ、`.claude/rules/` は条件付きで効かせる分割ルールです。性質が違うので、統制の中心は人間が更新できるファイル群に置くほうが追跡できます。実践記事では `MEMORY.md` の先頭200行をまず読む整理もありますが、これはあくまで運用知として見るべきで、そこに重要ルールを押し込む理由にはなりません。

私自身、`Auto memory` に「守ってほしいこと」を増やした時期は、意図した統制より「以前の会話で学んだ傾向」が前に出る感触がありました。そこで、人間が明示的に統制したい方針は `CLAUDE.md` と `rules` に戻し、`Auto memory` には補助的な学習だけを任せる形にすると、どこを直せば挙動が変わるのかが見えやすくなりました。迷ったときは、「これは人が管理したいルールか、Claude に覚えておいてほしい補助情報か」で分けると整理しやすくなります。

{{product:5}}

## まとめ

`CLAUDE.md` は、何でも載せる設計書ではなく、Claude Codeが最初に読む**AI向けの最小限オンボーディング資料**として保つのが軸です。まずは `/init` で土台を作り、自明な説明を削って、概要・主要コマンド・検証手順の3要素だけを残した10〜30行程度から始めてください。そこで足りなくなった内容は追記で膨らませるのではなく、`rules`、`skills`、`hooks`、必要なら `@import` へ分けると運用が崩れません。保存したら1〜2週間回して見直し、守られない指示だけを短く直す形で育てると定着します。私も短い `CLAUDE.md` に切り替えてから、初動のやり取りがひと息で噛み合う感覚がはっきり出ました。