CLAUDE.md 書き方ベストプラクティス｜設計パターン・300行ルール完全ガイド

CLAUDE.md は「Claude がコードを読んでも推測できないこと」だけを、公式推奨の 200 行以内・コミュニティ最適の 60 行前後で書くのがベストプラクティスです。 よく見かける「300 行ルール」は Anthropic 公式の数字ではなく、HumanLayer 社発のコミュニティ基準で、300 行は事実上の上限ラインという位置づけです。

この記事では、Claude Code 公式ドキュメント（2026 年 5 月時点）と運用コミュニティの知見をもとに、CLAUDE.md の書き方・設計パターン・育て方を体系的に整理します。v2.1.69 で追加された InstructionsLoaded フックや、CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 環境変数、Auto Memory との使い分けなど、最新の仕様もすべて反映しました。

この記事でわかること

• CLAUDE.md の役割と Claude がどう読み込むかの公式仕様
• 60 行・200 行・300 行ルールの出所と、現場での現実的な運用ライン
• 配置場所（4 階層スコープ）と優先順位
• 含めるべき内容／書くべきでない内容の明確な線引き
• プロジェクト規模別の設計パターン（小規模・中規模・大規模・モノレポ）
• @import と .claude/rules/ によるファイル分割のベストプラクティス
• CLAUDE.md / Skill / Hook / Subagent / Auto Memory の使い分け
• 「ルールが守られない」失敗の根本原因と対策
• すぐ使える CLAUDE.md テンプレート（ミニマル・標準・大規模）
• InstructionsLoaded フックを使った組織ガバナンス
• 書いた後の「育て方」フレームワーク

誰向けの記事か

• Claude Code を導入したが、思ったように指示が通らず悩んでいる開発者
• チームで CLAUDE.md の運用ルールを整備したいテックリード／エンジニアリングマネージャ
• 肥大化した CLAUDE.md を分割・整理したいプロジェクトオーナー
• 他のエージェント（Cursor、Codex 等）と併用しており、AGENTS.md との整理をしたい方
• 組織全体でガードレールを敷きたい IT・DevOps 担当者

CLAUDE.md とは：Claude Code が毎回読み込む永続コンテキスト

CLAUDE.md とは、Claude Code がすべてのセッション開始時に自動で読み込む Markdown 形式の指示ファイルです。公式ドキュメント "How Claude remembers your project" では次のように定義されています。

CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session.

押さえておくべき構造的事実は 3 つです。

1. 毎セッションで全文がロードされる — そのぶんコンテキストウィンドウとトークンコストを消費する
2. システムプロンプトではなく「ユーザーメッセージ」として注入される — つまり強制力はなく、Claude にとっては「あなたからの最初の依頼」に近い扱い
3. コードから推測できないことを書くのが目的 — 言語の標準慣習や、見れば分かるディレクトリ構成を書いても効果は薄い

この「ユーザーメッセージとして注入される」という構造は、後述する「ルールが守られない問題」を理解するうえで決定的に重要です。公式自身も CLAUDE.md と Auto Memory を 「2 つの相補的なメモリシステム」 と位置づけ、「どちらもコンテキストであって強制設定ではない」と明示しています。

なぜ CLAUDE.md が重要か

出典: Anthropic - Introducing Claude Code

CLAUDE.md を書くと書かないでは、Claude Code の実用性が大きく変わります。

• 毎回同じ指示を書き直さずに済む — ビルドコマンドや規約を 1 回書けば永続化
• チーム全員で「Claude の振る舞い」を揃えられる — git 管理することで PR レビュー対象にできる
• Claude の推測ミスを未然に防げる — 非自明な環境固有ルール（ポート競合、独自テストランナーなど）を明示できる
• トークンを節約できる — プロジェクト規約を都度チャットで説明しなくて済む

一方で、肥大化した CLAUDE.md は逆効果になります。Anthropic 公式は次のように警告しています。

Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

長すぎる CLAUDE.md ではルールが「ノイズ」の中に埋もれ、Claude が従わなくなります。つまり「書けば書くほど効く」ではなく、適切な粒度・文量・構造で書くことが成果に直結するということです。

60 行・200 行・300 行ルールの真相

出典: HumanLayer - Writing a good CLAUDE.md

CLAUDE.md の文量について、ネット上では複数の数字が流通しています。どれも根拠がありますが、出所が違うので整理して覚えておくとよいでしょう。

公式は「200 行以内」が現行ガイダンス

Anthropic 公式ドキュメント（メモリ仕様）には、現時点で次のように明示されています。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

公式トラブルシューティング欄でも「200 行を超えるとコンテキストを多く消費し、遵守性が下がる可能性がある」と明記されています。

「300 行ルール」は HumanLayer 発のコミュニティ基準

一方、日本語圏で広まっている 「300 行を超えると Claude の挙動が崩れる」 という話は、HumanLayer 社のブログ "Writing a good CLAUDE.md" が起点です。同社は自社の実運用から次の経験則を出しています。

• 最適は 60 行未満（自社の root CLAUDE.md は 60 行以内で運用）
• 150〜200 個程度の指示数が現行フロンティア LLM の遵守限界
• 指示数が増えると「特定の指示が無視される」のではなく 「全ての指示の遵守率が一様に低下」 する

3 階層で覚えると迷わない

以上を踏まえて、実務では次の 3 階層で判断すると整理しやすくなります。

公式は「各行について『これを削除したら Claude が間違いを犯すか？』と問い、No なら削除せよ」と具体的な剪定の指針も示しています。まずは 200 行を守り、できれば 100 行未満まで絞り込むのが現実的なゴールです。

配置場所と優先順位：4 階層のスコープ

CLAUDE.md は 4 つのスコープに配置でき、それぞれ用途が異なります。

優先順位と「連結」の仕組み

公式仕様では、優先順位はより具体的なものが優先（ローカル > プロジェクト > ユーザー > 管理ポリシー）です。ただし注意点が 2 つあります。

1. 「上書き」ではなく「全て連結」されてコンテキストに注入される
2. 親ディレクトリは launch 時に walk up されて全て読み込まれる

連結順は ファイルシステムのルート側が先、作業ディレクトリ側が後 です。LLM は末尾の指示を重く受け取る傾向があるため、作業ディレクトリに近い CLAUDE.md ほど影響力が大きいという事実上の優位性があります。

つまりモノレポで /repo/CLAUDE.md と /repo/apps/web/CLAUDE.md が両方あれば、web ディレクトリで作業すると両方が連結されて注入されます。親子で役割を分け、親に共通ルール、子にプロジェクト固有ルールを置くのが基本設計です。

サブディレクトリ内の CLAUDE.md は on-demand

サブディレクトリ（たとえば src/api/CLAUDE.md）は、Claude がそのディレクトリのファイルを読んだタイミングで初めて注入されます。したがって、細かいドメインルールはサブディレクトリに配置することで、全体のトークン消費を抑えながら必要なときだけ適用できます。

--add-dir で追加したディレクトリの CLAUDE.md は別途オプトイン

2026 年に明示された新仕様として、--add-dir で追加ディレクトリを指定しても、そのディレクトリの CLAUDE.md は自動では読み込まれません。明示的に有効化するには CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定します。

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

これで追加ディレクトリの CLAUDE.md / .claude/CLAUDE.md / .claude/rules/*.md / CLAUDE.local.md がすべて読み込まれるようになります。複数リポジトリを横断する設定ファイル群を共有したい場合に便利です。

含めるべき内容 / 含めるべきでない内容

CLAUDE.md に何を書くかは、「Claude がコードを読んで推測できないこと」という基準一本で決まります。

リンターで強制できるものは書かない

CLAUDE.md に書くべきでない典型例は、リンターやコンパイラで機械的に強制できるルールです。

• インデント幅・クォート種別 → ESLint / Biome / Prettier
• import 順 → 自動整形ツール
• 型チェック → TypeScript コンパイラ
• 命名規則の機械的な強制 → Linter ルール

公式も「リンターで強制できるものは CLAUDE.md ではなく Hook で確定的に強制せよ」と明示しています。HumanLayer の表現を借りれば "Never send an LLM to do a linter's job"。機械が守れるものは機械に任せましょう。

基本構造：WHAT / WHY / HOW の 3 層モデル

英語圏・日本語圏の主要な解説記事で共通して使われる設計モデルが「WHAT / WHY / HOW」の 3 層です。短い CLAUDE.md でもこの構造を意識すると、Claude が情報を整理しやすくなります。

重要なのは WHY を省かないこと です。WHY がないと Claude は「なぜこのルールがあるか」を理解できず、似て非なるケースで誤った判断をします。1〜2 文で構いません、背景だけ書きましょう。

プロジェクト規模別の設計パターン

CLAUDE.md は「規模に応じて」構成を変えるのがベストプラクティスです。

小規模プロジェクト：まず 1 枚で

個人開発や小規模プロジェクトなら、ルート直下の CLAUDE.md 1 枚で十分です。WHAT / WHY / HOW を 30〜60 行に収めて、必要になったら追加するスタイルが最も運用コストが低くなります。

中規模：.claude/rules/ でドメイン別に分割

ファイル数が 100 を超えたあたりから、CLAUDE.md が肥大化しがちです。このタイミングで .claude/rules/ ディレクトリにドメイン別のルールを切り出すと効果的です。

your-project/
├── CLAUDE.md                     # プロジェクト全体（100 行程度）
└── .claude/
    ├── CLAUDE.md                 # ./CLAUDE.md の代替配置（どちらか一方）
    └── rules/
        ├── code-style.md         # コードスタイル
        ├── testing.md            # テスト規約
        └── security.md           # セキュリティ要件

.claude/rules/*.md は再帰的に発見され、launch 時に自動で連結されます。つまり @import を書かなくても自動で読み込まれます。シンボリックリンクにも対応しているため、複数プロジェクトで共通ルール集を共有したい場合は、社内テンプレートリポジトリへの symlink を張る運用が現実的です。

大規模・モノレポ：paths: フロントマターで条件付きロード

500 ファイルを超える規模やモノレポでは、すべてのルールを毎回ロードするとコンテキストが圧迫されます。そこで使うのが paths: フロントマターです。

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

# API Development Rules
- All API endpoints must include input validation
- Use Zod for schema validation

このルールは Claude が src/api/ 以下のファイルを触ったときだけロードされます。ドメインごとに細かくスコープを切れば、巨大リポジトリでもトークン効率を保てます。

paths: フロントマターのパターンは公式に次のように整理されています。

ブレース展開（"src/**/*.{ts,tsx}"）にも対応しています。

path-scoped rules の既知の制約（2026 年 5 月時点）

公式 GitHub の Issue を確認すると、paths: フロントマターには現時点でいくつか運用上の注意点があります。

• Issue #23478: paths: 付きルールは Claude がファイルを Read したときだけ注入され、Write / Create 時には自動注入されない
• Issue #16853 / #16299: マッチするファイルを開いても自動ロードされないケース、逆にパスに関係なくグローバルにロードされてしまうバグが報告されている
• Issue #17204: ドキュメントの paths: 記法が動かないケースがあり、globs: 記法や引用符なしの paths: **/*.cs の方が確実に動作する報告もある
• Issue #38487: Write/Edit 時にも path-scoped rule を読み込んでほしいという機能要望が継続オープン

新規ファイル作成時にも適用したいルールは、プロジェクトルートの CLAUDE.md に最低限の指示を書いて二重化しておくのが安全です。記法が思った通り動かない場合は、paths: を globs: に置き換えてみる、引用符を外してみる、といった切り分けを行ってください。

@import による構造化と Progressive Disclosure

CLAUDE.md は @ 記法で他ファイルをインラインで取り込めます。これを使うと巨大な単一ファイルを避けつつ、必要な情報だけを参照できます。

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

仕様の要点は次の通りです。

• 相対パス・絶対パス・ホームディレクトリ記法（~/）すべて使用可
• インポート先がさらに別ファイルをインポート可能（最大 5 階層）
• 初回のみ承認ダイアログが表示され、拒否すると以降は無効化
• @import で分割しても context の総量は減らない（imported file は launch 時に全文ロードされる）

最後の点は要注意です。@import はあくまで「整理」のための仕組みであり、コンテキスト削減目的なら paths: フロントマター付きの .claude/rules/ を使うべきだと公式も明記しています。

Progressive Disclosure（段階的開示）パターン

CLAUDE.md 肥大化対策で現場で最も推奨されているのが Progressive Disclosure（段階的開示）パターンです。

1. Tier 1: ルート CLAUDE.md（最小） — 普遍的なコンテキストだけ（100 行未満目安）
2. Tier 2: Skill（.claude/skills/<name>/SKILL.md） — タスク特化の手順。Claude が必要だと判断したときだけ on-demand ロード
3. Tier 3: 詳細ドキュメント（docs/agent-guides/ または agent_docs/） — リファレンス。Skill や CLAUDE.md からポインタで参照

実装例：

# 詳細ドキュメント（必要時のみ参照）
- データベーススキーマ変更時: @docs/db-migration.md を読むこと
- 新 API エンドポイント追加時: @docs/api-conventions.md を読むこと
- 決済モジュール修正時: @docs/billing-rules.md を読むこと

CLAUDE.md 本体には「ポインタだけ」残し、詳細は必要なときだけ取り込む。これが肥大化を防ぐ最も効果的な設計です。

CLAUDE.md / Skill / Hook / Subagent の使い分け

「これは CLAUDE.md に書くべきか、別の仕組みを使うべきか」は公式が明確に示している判断軸があります。

→ CLAUDE.md に書くべきではないものは次の 3 種類です。

1. 例外なく毎回守らせたい処理 → Hook で実装
2. 特定タスク専用の長い手順 → Skill で外出し
3. 大量読み込みが必要な探索 → Subagent でコンテキスト分離

Skill と Hook の使い分けは Claude Code Skills vs Hooks 使い分けガイド で詳しく整理しています。

Auto Memory との関係（v2.1.59 以降）

Claude Code v2.1.59 以降は、CLAUDE.md と並行して Auto Memory という Claude が自動で書き込むメモリシステムが追加されました。両者は補完関係にあります。

使い分けの基本

• CLAUDE.md =「こうしてほしいことを明示する」（命令・規約）
• Auto Memory =「Claude が観察して学んだことを保存」（経験・学習）

Auto Memory の制御

• autoMemoryEnabled: false または環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 で無効化
• 保存先は autoMemoryDirectory 設定で変更可能ですが、プロジェクト/ローカル設定からは指定不可（ユーザー設定または --settings 経由のみ）。悪意あるリポジトリが保存先を奪取できない設計です
• MEMORY.md がインデックスとして使われ、トピックごとに別ファイルに分割保存される

Auto Memory と CLAUDE.md に同じトピックを書いてしまうと文脈が冗長になります。「明示ルールは CLAUDE.md、Claude が学んだ細かいパターンは Auto Memory に任せる」と役割を分けるのが推奨です。

ルールが守られないときの根本原因と対策

「ちゃんと CLAUDE.md に書いたのに Claude が従わない」という悩みは公式トラブルシューティングでも最も多く扱われています。公式は典型的な原因として 4 つを挙げています。

原因 1：ユーザーメッセージとして注入される

CLAUDE.md はシステムプロンプトではなく、システムプロンプト直後の「ユーザーメッセージ」として注入されます。つまり Claude にとっては「あなたが会話冒頭で伝えたお願い」と同じ扱いで、強制力はありません。後続のメッセージでユーザーが違うことを言えば、簡単に上書きされます。

対策: 本当に例外なく守らせたい処理は、CLAUDE.md ではなく Claude Code の Hook 機能で強制する。自動化スクリプト経由でシステムプロンプトレベルの上書きが必要な場合は --append-system-prompt を使う。

原因 2：Lost in the Middle 問題

LLM は長文コンテキストの先頭と末尾を、中央より高精度で参照する傾向があります（Lost in the Middle 問題）。CLAUDE.md が長いと、中盤に書いたルールほど無視されやすくなります。

対策:

• 最重要ルールは冒頭に配置
• IMPORTANT: YOU MUST: NEVER: のような強調記法を使う（公式も推奨）
• 見出し・箇条書き・表で視認性を上げる
• モノレポ等では、より作業ディレクトリに近い（=連結順で後ろになる）CLAUDE.md に重要ルールを配置する

原因 3：ファイルが長すぎる

指示数が増えると、特定の指示が無視されるのではなく 全ての指示の遵守率が一様に下がる ことが HumanLayer の検証で報告されています。

対策: 200 行を超えたら剪定。「この行がなくなったら Claude は間違うか？」と各行に問い、No なら削除。CLAUDE.md にあるはずの質問を Claude がしてくる場合は、表現が曖昧な可能性が高い。

原因 4：表現が曖昧／複数 CLAUDE.md の間で矛盾

「綺麗に書く」「適切に処理する」のような曖昧な指示は、Claude にとって守る基準が決まらず無視されます。また、ユーザーレベル・プロジェクトレベル・サブディレクトリで矛盾するルールがあると、どちらに従えばよいか判断できなくなります。

対策:

• 必ず検証可能な形に言い換える。「すべての関数に JSDoc を付ける」「エラーは型付きのカスタムエラークラスで投げる」など、成否が判断できる書き方にする
• /memory で実際にロードされている内容を確認し、矛盾を解消する
• 不要な CLAUDE.md は後述の claudeMdExcludes で除外する

CLAUDE.md テンプレート集

すぐに使える 3 パターンのテンプレートを紹介します。

ミニマル版（個人開発・小規模向け・30 行）

# MyApp

## 概要
TypeScript + Bun で書かれた API サーバー。

## 必須コマンド
- 開発サーバー: `bun run dev`
- 型チェック: `bun run typecheck`
- テスト: `bun run test`
- リント: `bun run lint`

## コーディング規約
- TypeScript strict モード必須
- 関数型スタイルを優先（for ループより map / filter / reduce）
- エラーは `AppError` 派生クラスで投げる

## テスト方針
- 新機能は必ずテストを追加
- `describe` + `it` 形式、日本語 OK

## 注意点
- DB マイグレーションは `bun run db:migrate`。手動で `ALTER TABLE` しない
- `.env.local` は git 管理外。`.env.example` を参考に作成

標準版（チーム開発向け・150 行程度・抜粋）

# ECサイト基盤

## プロジェクト概要（WHAT）
Next.js 16 App Router + TypeScript + Prisma + PostgreSQL のECサイト。
月間1,000万PV想定。

## 設計判断（WHY）
- TypeScript strict: 過去の implicit any 起因の本番バグ再発防止
- Server Actions 優先: API Route は外部連携時のみ
- 決済は Stripe 固定。他社比較は完了済みで再検討不要

## 必須コマンド（HOW）
- 開発: `pnpm dev`
- 型チェック: `pnpm typecheck`
- テスト: `pnpm test` (変更後は必ず実行)
- E2E: `pnpm e2e` (本番リリース前のみ)
- DB マイグレーション: `pnpm db:migrate`

## コーディング規約
- Server Components 優先。`use client` は必要最小限
- Prisma Client は `@/lib/prisma` から import（直接インスタンス化禁止）
- エラーハンドリングは `@/lib/errors` のカスタムエラーを使用

## IMPORTANT: 絶対守ること
- 決済処理の金額計算は必ず Decimal 型で行う（number 禁止）
- 個人情報を含むログを出力しない
- マイグレーション無しで DB スキーマを変えない

## 詳細ドキュメント（必要時に参照）
- API 設計: @docs/api-conventions.md
- 決済モジュール: @docs/billing-rules.md
- セキュリティ要件: @docs/security.md

大規模・モノレポ版（rules 活用）

monorepo-root/
├── CLAUDE.md                     # 共通ルール（80 行）
├── .claude/
│   ├── rules/
│   │   ├── typescript.md         # TS 全般規約（paths なし＝常時）
│   │   ├── api.md                # paths: src/api/**
│   │   ├── frontend.md           # paths: apps/web/**
│   │   └── infra.md              # paths: infrastructure/**
│   └── settings.local.json       # claudeMdExcludes でノイズ除外
├── apps/
│   ├── web/CLAUDE.md             # フロント固有
│   └── admin/CLAUDE.md           # 管理画面固有
└── packages/
    └── core/CLAUDE.md             # コアライブラリ固有

親 CLAUDE.md にはチーム共通の WHAT / WHY / HOW だけ置き、各ドメイン固有の規約は .claude/rules/*.md に paths: フロントマター付きで配置します。他チームの CLAUDE.md がノイズになる場合は、次節の claudeMdExcludes で個人レベルで除外します。

モノレポ運用：claudeMdExcludes でノイズを除外

大規模モノレポで他チームの CLAUDE.md が読み込まれてコンテキストを圧迫する場合、claudeMdExcludes 設定で除外できます。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

仕様の要点は次の通りです。

• user / project / local / managed policy のいずれの階層でも設定可能
• 配列は階層をまたいでマージされる
• 一般的には .claude/settings.local.json（git 管理外）に書いて個人レベルで除外
• 管理ポリシー CLAUDE.md は claudeMdExcludes でも除外不可（IT 部門の強制力を担保）

「自分は決済チームだから他のマイクロサービスのルールは要らない」というようなケースで、トークン消費と Lost in the Middle 問題の両方を緩和できます。

組織導入：管理ポリシー CLAUDE.md と監査

エンタープライズで Claude Code を展開する場合、CLAUDE.md は単なる開発者ツールではなくガバナンスの構成要素になります。

管理ポリシー CLAUDE.md のデプロイ

管理者は OS のシステムパス（macOS の /Library/Application Support/ClaudeCode/CLAUDE.md、Linux の /etc/claude-code/CLAUDE.md、Windows の C:\\Program Files\\ClaudeCode\\CLAUDE.md）に CLAUDE.md を配置することで、組織全体に共通ルールを強制できます。

• macOS: MDM（Jamf、Kandji 等）で配布
• Windows: Group Policy または Intune
• Linux: Ansible や Chef などの構成管理

このスコープに置かれた CLAUDE.md は、開発者が個別設定で除外することができません。「機密データを含むファイルは扱わない」「特定ディレクトリへの書き込みを禁止」など、組織のガードレールを敷くのに使います。

InstructionsLoaded フックでロード履歴を監査（v2.1.69 以降）

2026 年 4 月にリリースされた v2.1.69 で、InstructionsLoaded という新しいフックイベントが追加されました。

• Claude Code が CLAUDE.md ファイル、または .claude/rules/*.md をロードするたびに発火
• 判定制御はできない（ロードをブロックしたり改変したりはできない）
• 用途は 監査ログ・コンプライアンス・観測性
• HTTP フック（外部 URL に JSON ペイロード POST）にも対応 → SaaS の Audit / SIEM に直接送れる

これにより、「どの開発者がどの CLAUDE.md / ルールを読み込んだか」を中央で記録でき、SOX 監査や PCI コンプライアンス確認に直結します。SIEM へ送信して異常なルール変更を検知する運用も可能です。

なお、Issue #31017 で /clear 時はディスクから再ロードされるが InstructionsLoaded フックが発火しないケースがあることが報告されています。完全な監査が必要な場合は、セッション開始時のフックも併用してください。

AGENTS.md や他 AI ツールとの関係

出典: GitHub - anthropics/claude-code

近年は Cursor・Codex・Aider・OpenClaw など複数のコーディングエージェントを併用するチームが増えました。ここで課題になるのが 「指示ファイルの二重管理」 です。

Claude Code は CLAUDE.md しか読まない

公式仕様上、Claude Code は AGENTS.md を自動では読み込みません。一方、Cursor や Codex は AGENTS.md を標準にしています。

1 ソース化の戦略

既に AGENTS.md を使っているリポジトリでは、CLAUDE.md 側で @AGENTS.md として取り込めば二重管理を避けられます。

@AGENTS.md

## Claude Code 固有の指示
- `src/billing/` 以下を変更するときは plan mode を使うこと
- マイグレーションは必ず `/compact` 前に実行すること

共通ルールは AGENTS.md に、Claude 固有の細かい指示だけ CLAUDE.md 本体に書く形です。Windows ではシンボリックリンクに管理者権限が必要なので、@AGENTS.md 取り込みのほうが運用しやすい点も覚えておいてください。

/init は AGENTS.md、.cursorrules、.windsurfrules を読み取って関連部分を自動で取り込んだ CLAUDE.md を生成します。複数ツール環境からの移行時に活用できます。

関連コマンドと運用 Tips

CLAUDE.md を運用するうえで押さえておくべき公式コマンドです。

/init は雛形作成には便利ですが、そのまま使わず必ず手動で剪定するのが鉄則です。冗長な自動生成内容を土台に「これは Claude が推測できるか？」と問いながら削っていきます。

インタラクティブ /init（CLAUDE_CODE_NEW_INIT=1）

公式が 2026 年に追加した拡張モードとして、CLAUDE_CODE_NEW_INIT=1 を設定すると /init の挙動が変わります。

• CLAUDE.md だけでなく Skills と Hooks も含めて段階的にセットアップ
• サブエージェントでコードベースを探索
• 不明点を聞き返したうえで、書き込み前にレビュー可能な提案を出す

新規プロジェクトを Claude Code 用に整備する際は、こちらのモードを有効化すると初期構築の精度が上がります。

HTML コメントでメンテナーメモを残せる

意外と知られていない仕様ですが、<!-- --> 形式の HTML コメントは context 注入前にストリップ されます（コードブロック内のコメントは保持）。

<!-- このルールは2026-03-10のインシデント対策で追加。2026-09に見直し -->
## 決済処理の金額計算は必ず Decimal 型

メンテナーへの注意書きを CLAUDE.md に残しつつ、Claude のコンテキストは圧迫しない運用が可能です。Read ツールで開けばコメントも見えるため、レビュー時の文脈把握にも役立ちます。

/compact 後の挙動

/compact で履歴を圧縮した後でも、プロジェクトルートの CLAUDE.md は再注入されます。ただしサブディレクトリの CLAUDE.md は、次にそのフォルダのファイルを読むまで再ロードされません。長いセッションで頻繁に /compact する場合は、重要ルールはルート CLAUDE.md に集約しておくのが安全です。

CLAUDE.md の「育て方」フレームワーク

CLAUDE.md は一度書いて終わりではありません。公式も「コードのように扱え：問題が起きたらレビュー、定期的に剪定、変更後に Claude の振る舞いが実際に変わるか観察」と推奨しています。

書き加えるシグナル

• 同じ訂正を 2 回した — 3 回目を防ぐために書く
• チームメンバーが詰まった場所 — 暗黙知を形式知化
• コードレビューで頻出する指摘 — Claude に事前に伝えておけば PR が綺麗に
• インシデントの再発防止策 — 「なぜダメか」を WHY として残す

削るシグナル

• Claude が指示なしでも正しく動くようになった
• リンター・型チェッカーで強制可能になった
• 自明すぎる内容（「綺麗なコードを書く」など）
• プロジェクトから外れた技術の名残

Skill / Hook / Subagent に移すシグナル

• 手順が長く、CLAUDE.md で書くと肥大する → Skill
• 特定タスク専用（DB マイグレーション等）で常時ロード不要 → Skill
• 例外なく毎回実行されなければ困る → Hook
• 大量のコード探索やレビューが必要 → Subagent

「CLAUDE.md は指示、Hook は強制、Skill は専門ワークフロー、Subagent はコンテキスト分離」と機能を分けて考えると、各ファイルがスリムに保てます。

よくある失敗パターン

実運用でよくある失敗を整理します。

1. /init の生成結果をそのまま放置 — 冗長かつ自明な内容が混ざっているのでレビュー必須
2. リンターで強制できるルールを書いている — Claude のトークンと遵守率を浪費
3. 曖昧表現（「適切に」「きれいに」） — 守る基準がなく無視される
4. 200 行を超えても放置 — ルールが全体的に守られなくなる
5. WHY を書かない — Claude が派生ケースで誤判断
6. シークレットや接続文字列を書く — セキュリティ事故。.env 参照を指示するに留める
7. CLAUDE.local.md を .gitignore に入れ忘れる — 個人情報・社内パスが漏洩
8. サブディレクトリで親と矛盾するルール — 親子で整合性を取らないと挙動が不安定
9. @import を context 削減目的で使う — @import は全文ロードされる。削減目的なら .claude/rules/ + paths:
10. InstructionsLoaded フックなしで監査が必要な環境 — ロード履歴を取れない

こんな方に向いています

• Claude Code を本格的にチームで運用したい: CLAUDE.md が指示の統一と PR レビュー対象になる
• プロジェクト規約が複雑で毎回説明が必要: 永続化して運用コストを下げたい
• モノレポや大規模コードベースを運用: 階層的スコープと paths: で効率化、claudeMdExcludes でノイズ除去
• 他ツール（Cursor / Codex）と併用: @AGENTS.md で 1 ソース管理したい
• エンタープライズで監査要件がある: 管理ポリシー CLAUDE.md と InstructionsLoaded フックでガバナンスを構築

こんな方にはおすすめしません

• Claude Code を使わない（他ツール専用）: そもそも読み込まれない
• ルール自体がまだ固まっていない: まず運用で試して、必要なものだけ書く方が効率的
• 「書けば Claude が完璧に守る」と期待している: ユーザーメッセージ注入なので強制力は限定的。例外なく守らせたい処理は Hook で

よくある質問（FAQ）

Q1. CLAUDE.md は何行までが現実的な上限ですか？

Anthropic 公式は 200 行以内を明示推奨しています。HumanLayer の経験則では 60 行前後が最適、300 行を超えると遵守率が確実に下がるとされています。まず 200 行を守り、可能なら 100 行未満を目指すのが現実的です。

Q2. プロジェクトと個人のルールはどう分けるべきですか？

チーム共有すべき規約は ./CLAUDE.md（git 管理）、個人固有のメモは ./CLAUDE.local.md（.gitignore 必須）、全プロジェクト共通の個人設定は ~/.claude/CLAUDE.md に分離します。CLAUDE.local.md を git 管理外にしないと、個人情報や社内パスが漏洩するので注意してください。

Q3. .claude/rules/ と @import はどう使い分けますか？

• .claude/rules/: ドメイン別ルールを「自動で」発見・連結したいとき。paths: で条件付きロードもできる（コンテキスト削減効果あり）
• @import: 既存のドキュメント（README、docs/ 以下のファイル）を 1 ソースとして参照したいとき

ただし @import は context の総量を減らさない点に注意。コンテキスト削減目的なら必ず paths: 付きの .claude/rules/ を使ってください。

Q4. AGENTS.md と併用するときのベストな設計は？

AGENTS.md をメインソースにし、CLAUDE.md の先頭で @AGENTS.md を読み込ませる形が推奨されます。Claude 固有の指示（plan mode の使用、/compact 前の必須処理など）だけを CLAUDE.md 本体に書けば、二重管理を避けられます。

Q5. /init で自動生成されたファイルはそのまま使えますか？

使えません。/init は雛形として便利ですが、冗長な内容（自明な技術説明、リンターで強制できるルールなど）が混ざります。必ず手動で剪定し、「この行を削除したら Claude が間違うか？」と各行に問いながら絞り込んでください。Skills / Hooks まで対話的に整備したい場合は CLAUDE_CODE_NEW_INIT=1 を試してみてください。

Q6. ルールを書いても Claude が従いません。どうすればいい？

主な原因は次の 4 つです（公式トラブルシュートの整理）。

1. そもそも CLAUDE.md が読み込まれていない: /memory で確認
2. 配置場所が正しくない: 4 階層スコープのどれかに置く
3. 表現が曖昧: 「綺麗に」ではなく検証可能な条件に
4. 複数 CLAUDE.md の間で矛盾: claudeMdExcludes で不要なものを除外

「例外なく実行されないと困る処理」は CLAUDE.md ではなく Hook で実装してください。

Q7. サブディレクトリの CLAUDE.md はいつ読み込まれますか？

Claude がそのディレクトリのファイルを読んだタイミングで初めて注入されます。親ディレクトリの CLAUDE.md は launch 時に常に読み込まれますが、子は on-demand です。したがって、細かいドメインルールはサブディレクトリに置くと全体のトークンを節約できます。

Q8. /compact 後も CLAUDE.md は効いていますか？

プロジェクトルートの CLAUDE.md は /compact 後に再注入されます。ただしサブディレクトリの CLAUDE.md は、次にそのフォルダのファイルを読むまで再ロードされません。長いセッションで頻繁に compact する場合は、重要ルールはルート CLAUDE.md に集約しておくのが安全です。

Q9. Auto Memory と CLAUDE.md のどちらに書くべき？

明示したい指示・規約は CLAUDE.md、Claude が試行錯誤の中で学習したパターンは Auto Memory に任せるのが原則です。両方に同じ内容を書くと冗長になります。Auto Memory は MEMORY.md の先頭 200 行 / 25KB しかロードされない上限がある点も覚えておいてください。

Q10. --add-dir で追加したディレクトリの CLAUDE.md も読まれますか？

デフォルトでは読み込まれません。CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定すると、追加ディレクトリ内の CLAUDE.md / .claude/CLAUDE.md / .claude/rules/*.md / CLAUDE.local.md がロードされるようになります。

Q11. CLAUDE.md のロード履歴を監査ログに残せますか？

v2.1.69 以降であれば InstructionsLoaded フックを使えます。CLAUDE.md / .claude/rules/*.md のロードごとにイベントが発火し、HTTP フックで SIEM や監査ログ基盤に直接送信できます。SOX / PCI 等のコンプライアンス要件がある組織で有効です。

まとめ

CLAUDE.md 書き方のベストプラクティスを整理します。

• 書く対象: Claude がコードを読んで推測できないことだけ
• 文量: 公式 200 行以内、最適 60 行前後、緊急上限 300 行
• 構造: WHAT / WHY / HOW の 3 層で設計
• 配置: プロジェクト共通は ./CLAUDE.md、個人は ./CLAUDE.local.md（gitignore 必須）
• 分割: 規模が増えたら .claude/rules/ と @import でドメイン別に
• 使い分け: CLAUDE.md は指示、Hook は強制、Skill は専門ワークフロー、Subagent はコンテキスト分離
• 運用: コードのように PR レビュー、同じ訂正 2 回で追加、自明化したら削除
• モノレポ: claudeMdExcludes でノイズ除去、CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD で共有設定をロード
• 組織導入: 管理ポリシー CLAUDE.md + InstructionsLoaded フックでガバナンスを担保

もっとも大切なのは、「書けば効く」ではなく「絞るほど効く」という事実です。200 行を守り、曖昧表現を排し、WHY を添え、使いながら育てる。この 4 原則を守るだけで、Claude Code の振る舞いは劇的に安定します。

関連する内容は以下の記事もあわせてご覧ください。

• Claude Code とは｜使い方・料金・できること完全ガイド
• Claude Code 使い方ガイド｜導入からベストプラクティスまで
• Claude Code Hooks 使い方｜ガードレールを自動強制する方法
• Claude Code Skills 活用ガイド｜ドメイン専門ワークフローの作り方
• Claude Code Skills vs Hooks 使い分けガイド
• Claude Code サブエージェント 使い方
• Claude Code スラッシュコマンド完全ガイド
• Claude Code MCP 連携ガイド｜GitHub・Slack・Notion・freee 統合
• Claude Code Routines 使い方｜スケジュール・API・GitHub Event 自動化完全ガイド
• Claude Code Auto Mode とは｜2 層防御・90% 自律コーディング目標