CLAUDE.md設計パターン｜規模別テンプレと階層分割・肥大化対策

Claude Code を日常的に使うほど、毎回同じプロジェクト規約やコマンドをチャットに書き直すコストが積み上がります。その受け皿が CLAUDE.md です。公式ドキュメントでは、セッションをまたいで読み込まれる永続的なプロジェクト指示として位置づけられています。

📑目次

1. CLAUDE.mdの役割と公式スコープ（User / Project / Local）
2. 規模別テンプレの選び方と初日チェックリスト
3. モノレポ向け階層分割パターン
4. 短く保つ原則と prune 基準
5. 用途特化はスキル分離か always-on かの判断
6. アンチパターンとサイズ目安
7. よくある質問（FAQ）
8. まとめ — 読者が今日やること

一方で「とりあえず全部書く」とファイルが肥大化し、指示の追従率が落ちたり、モノレポでは無関係なルールが常時コンテキストを占有したりします。本記事では Anthropic 公式のスコープ定義とベストプラクティスを軸に、個人スクリプトからモノレポまでの設計パターン、階層分割、スキル分離、prune 基準、初日チェックリストまでを整理します。

---

CLAUDE.mdの役割と公式スコープ（User / Project / Local）

CLAUDE.md の本質は「毎回のプロンプト再入力を減らす永続コンテキスト」です。モデルを再学習する仕組みではなく、会話開始時に前提として読み込まれる指示面だと捉えると設計がぶれにくくなります。公式の Memory ドキュメントでは、配置場所ごとに共有範囲が分かれます。

スコープ表と共有範囲

スコープ	典型パス	共有範囲	主な用途
Managed policy	OS 別の管理パス	組織	会社標準・コンプライアンス
User	~/.claude/CLAUDE.md	自分のみ	全プロジェクト共通の個人好み
Project	./CLAUDE.md または ./.claude/CLAUDE.md	Git でチーム共有	スタック・規約・共通ワークフロー
Local	./CLAUDE.local.md	自分（gitignore 想定）	個人用 URL やテストデータ

出典：Anthropic Claude Code Memory（2026年7月時点）

---

ロード順序と設計の非対称

読み込みのイメージは次の通りです。

• 作業ディレクトリより上の CLAUDE.md は起動時にまとめて読み込まれる
• 子ディレクトリ側は、その配下のファイルを実際に扱うタイミングでオンデマンド追加される

モノレポで「ルートに全部書く」と毎回フルコストが乗る一方、「パッケージ側に局所ルールを置く」と関連時だけ増える、という非対称が設計の核心です。

---

context と enforcement の境界

ここでの重要境界は、CLAUDE.md は context であり enforced configuration ではない点です。

• 「禁止」と書いてもハードブロックにはならない
• 操作を確実に止めたい場合は PreToolUse hook など、スキップできない仕組み側に寄せる

日本語での整理として、スコープと AGENTS.md との対比を扱った解説も同方向の理解を補強します（note.com/kazu_t）。

---

規模別テンプレの選び方と初日チェックリスト

規模が違うのに同じテンプレをコピーすると、個人リポジトリでは過剰設計、大規模では不足、の両方が起きます。次の目安で「何を always-on に残すか」を先に決めてください。

規模別の最小セット

• 個人スクリプト: 概要・スタック・実行/テストコマンドに絞る。ディレクトリ責務の長文は不要になりがちです。
• 中規模 Web: ディレクトリ責務、依存の向き、やってはいけないこと、主要コマンドを足します。
• モノレポ: ルートは横断方針と各パッケージへの pointer のみ。固有規約はパッケージ側へ。

---

初日15分チェックリスト

初日に 15 分で置ける最小チェックリストは次です。埋まらない項目は「今は書かない」と明示する方が、曖昧な願望リストを残すより安全です。

• ✓ プロジェクト概要（1〜2行）
• ✓ 技術スタック
• ✓ ディレクトリ責務（中規模以上）
• ✓ 依存方向 / パッケージ境界（該当時）
• ✓ コーディング規約は検証可能な具体句だけ（例: インデント、命名、禁止 API）
• ✓ 「やってはいけないこと」
• ✓ build / test / run コマンド
• ✓ モノレポなら階層分割の要否判定

---

配置後の検証

置き終わったら、新しいセッションで規約が効いているかを確認します。

• 配置ずれ・階層ずれは「書いたのに効かない」事故の定番
• 日本語の実務メモでも、最小構成のあと新規セッションで適用を検証する手順が勧められている（note.com/kurokawa_claude）

Claude Code 自体の外部設定の位置づけを広く把握したい場合は、Claude Codeのハーネスとは｜モデル・内部ループ・外部設定の3層 もあわせて読むと、CLAUDE.md が「どの層のレバーか」が明確になります。

---

モノレポ向け階層分割パターン

ルート巨大ファイルの失敗モード

ルートに巨大な単一 CLAUDE.md を置くと、次の失敗が重なりやすいです。

1. context cost: 毎セッションで全行が載る
2. relevance dilution: 無関係ルールが常時競合する
3. merge pain: 複数チームが1ファイルを編集し続ける

独立解説でも、ルートは横断ポリシー（スタック方針、ブランチ保護、パッケージへの pointer）に薄くし、パッケージ側にローカル規約とパッケージ限定コマンドを置く構成が推奨されています（Claude Fast: Subdirectory CLAUDE.md）。

出典

---

分割シグナルとパッケージ限定コマンド

分割の実務シグナルは単純です。ルートに「packages/api で作業するなら…」という条件分岐が増え始めたら split の合図です。

テストもルートの pnpm test 一発ではなく、pnpm --filter @app/api test のようにパッケージ限定へ寄せると、無関係な出力でコンテキストを汚しにくくなります。

---

公式整合（フルロード / オンデマンド / 除外）

公式側の整合も取れています。

• 親はフルロード、子はオンデマンド
• 長い topic 別ルールは .claude/rules/ の path-scoped rules や skills へ退避できる
• 無関係な祖先ディレクトリの指示を外したい場合は、公式 Memory が案内する claudeMdExcludes も選択肢

---

短く保つ原則と prune 基準

トークンコストと追従のトレードオフ

CLAUDE.md は毎セッションの先頭近くに入るため、トークンコストと指示追従のトレードオフが常にあります。

Anthropic Engineering のベストプラクティスは、次を示しています（Claude Code best practices）。

• 推論できない前提だけを短く書く
• 「Would removing this cause Claude to make mistakes?」に No なら削除する（prune 基準）

公式 Memory も 1 ファイル 200 行未満を目安とし、長い手順は rules / skills へ移すよう案内します。

---

検証可能な書き方と import の注意

書き方のコツは「検証可能」であることです。

• 良い例: コミット前に npm test を実行する / インデントはスペース2
• 弱い例: きれいなコードを書く / 適切に設計する

@path による import は整理には使えますが、launch 時に展開されるため context 量そのものは減らない点に注意してください。ファイルを分けた気分だけで短くなったと誤解しやすい箇所です。

---

progressive disclosure と無視リスク

HumanLayer は progressive disclosure（タスク固有手順は別 MD、CLAUDE.md には短い目次と読取指示）と、指示が多すぎると関連性が低いと判断され無視されやすいリスクを強調しています。

自社 root を 60 行未満に抑える例も、短さの実務アンカーになります（Writing a good CLAUDE.md）。

出典

---

用途特化はスキル分離か always-on かの判断

全部を CLAUDE.md に押し込まず、役割を分けると判断が速くなります。

仕組みの役割分担

仕組み	読み込み	向いている内容
CLAUDE.md	ほぼ always-on	毎回真に必要な規則だけ
Skill	タスク種別でオンデマンド	レビュー手順、生成手順など数行超のモード
Hook	スキップ不可	安全上どうしても止めたい操作

出典：dev.to / Hamid Shoja、Anthropic Memory（2026年7月時点）

---

単一真実とドキュメント検証

腐敗を防ぐ単一ルールは「事実は1ファイルに置き、他はリンクする」です。

• レビュー方針やテスト生成手順が膨らんだら skill（または別 MD + 短いポインタ）へ移す
• CLAUDE.md 側は「詳細は skill X」に留める
• ドキュメント自体もコード同様に検証し、例示パスが実在するか確認する（壊れた手順は長いデバッグループを生む）

Skills の書き方そのものを深掘りするなら Claude Code Skills の書き方｜公式ルールと公開SKILL.mdから学ぶ設計 が隣接トピックです。リポジトリ解析から hooks / skills を提案する公式プラグインの話は Claude Code Setup 公式プラグイン も参考になります。

---

アンチパターンとサイズ目安

次の表は、よくある肥大化パターンと対処の対応表です。

アンチパターン	症状	対処
全部入り	300行超の単一ファイル	階層分割、rules/skills へ移す
追記オンリー	矛盾ルールが共存	定期 prune（削除質問を使う）
長文コード埋め込み	サンプルが本体を圧迫	最小例 + file:line 参照
願望リスト	検証不能な抽象指示	具体的でテスト可能な規則へ置換
秘密情報混入	キーやパスワード記載	環境変数名のみ。値は書かない

サイズ感覚は、公式の 200 行/ファイル目安を上限の警戒線にし、実務では「短いほど追従しやすい」側へ寄せるのが安全です。over-specified な CLAUDE.md は、書いた半分が無視される失敗モードとして公式ベストプラクティスでも警告されています。

---

関連記事:

• グラフとループの使い分け｜導入判断チェックリスト【2026】
• Claude CoworkのRecord a skillとは｜Macで画面録画から再利用スキルを作る手順と導入判断
• Claude Opus 5が浅く感じる原因｜lean promptとCLAUDE.md改修

よくある質問（FAQ）

Q1. CLAUDE.md に禁止を書けば操作は絶対に止まりますか？

いいえ。CLAUDE.md は context であり hard enforcement ではありません。必須ブロックは PreToolUse hook など強制側の仕組みを使います（Memory docs）。

---

Q2. ルートとパッケージの両方に CLAUDE.md があるとき、どちらが勝ちますか？

単純な上書き優先ではなく連結ロードです。近い階層が後から読まれる一方、矛盾時の優先は保証されません。本筋は矛盾自体を消すことです。

---

Q3. AGENTS.md だけで足りますか？

Claude Code が主に読むのは CLAUDE.md です。既存の AGENTS.md は CLAUDE.md から @AGENTS.md で import するか symlink で共有する方法が案内されています。

---

Q4. どれくらいの長さが危険信号ですか？

公式は 200 行/ファイル未満を推奨します。肥大時は追従低下や無視が増えるため、rules/skills 分割と prune を検討してください。

---

まとめ — 読者が今日やること

CLAUDE.md は「全部を教えるファイル」ではなく、「毎回必要な最小の共通前提」を置くファイルです。今日やることは次の5手に絞れます。

1. User / Project / Local のどのスコープに何を置くか決める
2. 200 行未満を意識して最小版を書く（検証可能な規約と禁止事項を優先）
3. モノレポならルート薄く・パッケージ局所の要否を判定する
4. 新規セッションで Memory files / 規約適用を確認する
5. タスク手順が膨らんだら skill / rules へ移し、1週間後に prune 質問で棚卸しする

安全境界をコード実行環境まで含めて設計したい場合は、Claude CodeとCodexのサンドボックス選び方 も併せて検討すると、指示面（CLAUDE.md）と実行面（sandbox）の分担がはっきりします。