CLAUDE.md ベストプラクティス【2026年】設定の書き方20選

結論: CLAUDE.md は、Claude Code が毎セッション冒頭に読み込むプロジェクト設定ファイルです。「グローバル・プロジェクト・サブディレクトリ」の3層で構成・継承され、書くべき内容と禁止事項を正しく設計するだけで、チーム全体のAIコーディング品質が劇的に安定します。

この記事の要点:

• 要点1: CLAUDE.md には4つのスコープ（管理ポリシー・ユーザー・プロジェクト・ローカル）があり、下層ほど優先度が高い
• 要点2: 1ファイルあたり200行以内を守らないと遵守率が下がる（公式ドキュメント記載）
• 要点3: 「何を書くか」より「何を書かないか」の設計が成否を左右する

対象読者: Claude Code を業務・研修・個人開発で使っている方、チームにClaude Codeを導入したい担当者・経営者

読了後にできること: 今日中にCLAUDE.md を3層設計で作り直し、AI指示の遵守率を高める

「Claude Codeに何度注意しても同じミスを繰り返す」「プロジェクトメンバーによってAIの動き方がバラバラ」

先日、ある企業の開発チームでClaude Code研修を担当したとき、こんな光景を目にしました。10人のエンジニアが同じリポジトリで作業しているのに、CLAUDE.md が空白のまま。あるメンバーはコーディングスタイルをチャットで毎回説明し、別のメンバーはまったく説明していない。当然、AIの出力品質は人によって大きくバラついていました。

CLAUDE.md は Claude Code がセッション開始時に必ず読み込む特別なMarkdownファイルです。ここに「チームの約束事」を書き込んでおけば、誰がセッションを開始しても同じ前提でAIが動きます。ところが、中身が多すぎると今度は逆に遵守率が下がる——これが多くの現場で起きているジレンマです。

この記事では、100社以上の企業向けClaude Code研修・導入支援で得た知見をもとに、CLAUDE.md のベストプラクティスを設計パターン20選として全公開します。公式ドキュメントに基づく正確なファクトに加え、現場で実際に効いた設定と、逆に逆効果だった失敗例もあわせて紹介していきます。

CLAUDE.md とは何か——基本のしくみを3分で理解する

CLAUDE.md は、Claude Code が毎セッションの冒頭にコンテキストウィンドウへ読み込む Markdown ファイルです。チャットで「今日からこのルールで動いて」と毎回伝える手間をなくし、プロジェクトのコーディング規約・ワークフロー・禁止事項を永続的に記憶させるためのしくみです。

Anthropic 公式ドキュメントによれば、CLAUDE.md はコンテキストウィンドウに読み込まれる「コンテキスト」であり、強制設定（enforce configuration）ではありません。つまり、書いた内容は Claude が「参考にする」ものであり、Hooks のような確実な実行保証はありません。だからこそ、少なく・具体的に・検証可能な形で書くことが大切です。

CLAUDE.md と混同されやすいのが「Auto Memory」という機能です。Auto Memory は Claude 自身がセッション中の学習・修正内容を自動的に保存していく領域（~/.claude/projects/<project>/memory/）です。CLAUDE.md はあなたが書くルール、Auto Memory は Claude が書くメモ——この違いを押さえておくと設計が整理されます。

AI導入の全体像については AI導入戦略の完全ガイド もあわせてご覧ください。

CLAUDE.md の4層スコープ——どこに置けば何が変わるか

公式ドキュメントに明記されている通り、CLAUDE.md には4つのスコープがあります。読み込み順（スコープが広い順）は以下の通りです。

重要なのは、後から読み込まれるファイルほど優先度が高い点です。プロジェクトルートの CLAUDE.md はユーザーレベルの設定より後に読み込まれるため、プロジェクト固有のルールが個人設定を上書きします。

また、サブディレクトリに置いた CLAUDE.md は起動時には読み込まれず、Claude がそのディレクトリ内のファイルを読んだときに初めてロードされます（オンデマンドロード）。これはモノリポや大規模プロジェクトで活用できる重要な特性です。

事例区分: 想定シナリオ
以下は100社以上の研修経験をもとに構成した典型的なシナリオです。
フロントエンド・バックエンド・インフラが混在するモノリポを持つ企業では、./CLAUDE.md（共通規約）+ ./frontend/.claude/rules/react.md（Reactルール）+ ./backend/.claude/rules/api.md（APIルール）の3層構成にすることで、チームごとの文脈を切り離して管理できます。

書くべき20項目——設計パターン完全リスト

CLAUDE.md に書くべき内容は「Claude がコードを読んでも知り得ない情報」に絞ります。以下は研修・導入支援の現場から抽出した20のパターンです。

カテゴリ1: ビルド・テスト・コマンド（必須）

Claude はあなたのプロジェクトのビルドコマンドを知りません。書かなければ npm test を試みて失敗し、数ターン無駄にします。

# ビルド・テスト・コマンドの設定例

## ビルドコマンド
- ビルド: `npm run build`
- テスト: `pnpm vitest`（npm test ではなく pnpm を使うこと）
- 型チェック: `tsc --noEmit`
- リント: `eslint src/ --ext .ts,.tsx`

## テスト実行の注意
- 全テストスイートではなく、変更ファイルに対応する単体テストを先に実行する
- カバレッジ計測: `pnpm vitest --coverage`（CIのみ。ローカルでは不要）

このパターンを追加してから、研修参加者のターン効率が平均で2〜3ターン改善されました（想定効果。実測は各環境による）。

カテゴリ2: コーディング規約（Claudeが推測できないもの限定）

# コーディング規約

## 必須
- ES Modules (import/export) 構文を使用。CommonJS (require) は禁止
- インポートは destructuring を使う: `import { foo } from 'bar'`
- インデント: 2スペース（タブ禁止）
- コンポーネントファイル名: PascalCase（例: UserProfile.tsx）

## API設計
- エンドポイント: ケバブケース（例: /user-profile）
- JSONプロパティ: キャメルケース（例: userName）
- リスト系エンドポイントには必ずページネーションを付ける

カテゴリ3: アーキテクチャ・ディレクトリ構成

# ディレクトリ構成（重要）

- `src/api/handlers/` — APIハンドラー（ここ以外に置かない）
- `src/services/` — ビジネスロジック
- `src/components/` — Reactコンポーネント
- `tests/` — テストファイル（srcの外に置く）

## 命名規則
- コンポーネントのテスト: `ComponentName.test.tsx`
- ユーティリティのテスト: `util-name.test.ts`

カテゴリ4: ワークフロー・コミット規約

# ワークフロー

## Git規約
- コミットメッセージ: conventional commits形式（feat:, fix:, docs: など）
- mainへの直接pushは禁止。PRを通すこと
- コミット前に必ず `npm run lint && npm run typecheck` を実行

## PR作成
- PRタイトルは70文字以内
- 本文には「何を変えたか」と「なぜ変えたか」を書く

カテゴリ5: 禁止事項・注意点（ゴッチャ情報）

# 禁止事項・注意点

## 絶対禁止
- `console.log` をコミットに含めない（eslintのno-consoleが有効）
- `any` 型の使用（TypeScriptプロジェクト）
- `src/legacy/` ディレクトリへの変更（オーナーに確認必須）

## 既知のゴッチャ
- `useEffect` の依存配列に関数を入れると無限ループになるパターンが多発。
  必ず `useCallback` でラップするか依存配列を見直す
- テスト環境のDB接続は `TEST_DATABASE_URL` を参照。`.env.local` ではない

カテゴリ6: セキュリティ・機密情報の扱い

# セキュリティルール

- APIキー・シークレットをコードに直書きしない。環境変数（.env）を使う
- `.env` ファイルはgitignore済み。コミットしない
- ログにユーザー個人情報（氏名・メール・電話番号）を含めない
- 外部APIのレスポンスをキャッシュする場合は有効期限を必ず設ける

カテゴリ7: 参照すべきドキュメント（@インポート活用）

# 参照ドキュメント
See @README.md for project overview.
See @package.json for available npm commands.

## 詳細ガイド
- デプロイ手順: @docs/deploy-guide.md
- データベーススキーマ: @docs/schema.md

CLAUDE.md は @path/to/file 構文で他のファイルをインポートできます（公式機能）。大きなドキュメントをインライン展開せず、参照形式にすることで本体をスリムに保てます。

カテゴリ8: .claude/rules/ による分割管理

your-project/
├── CLAUDE.md               # 共通の短い概要（50行以内）
└── .claude/
    └── rules/
        ├── testing.md      # テスト規約
        ├── api-design.md   # API設計ルール
        └── security.md     # セキュリティ要件

公式ドキュメントでは、大規模プロジェクト向けに .claude/rules/ ディレクトリへの分割管理を推奨しています。YAMLフロントマターで paths フィールドを指定すると、特定のファイルパターンに一致するときだけルールが読み込まれる「パス指定ルール」も使えます。

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

# APIハンドラールール
- すべてのエンドポイントに入力バリデーションを含める
- 標準エラーレスポンス形式を使用する

CLAUDE.md を書きすぎる「あるある失敗」——4パターンと回避策

失敗パターン1: ファイルが肥大化して遵守率ゼロに

❌ よくある間違い: 「ルールが多いほど安全」と思って、200行を超えるCLAUDE.md を作る。プロジェクト全体の説明、API仕様書、チュートリアル、設計意図の解説まで詰め込む。

⭕ 正しいアプローチ: 公式ドキュメントは「1ファイルあたり200行以内を目標にする。長いほど遵守率が下がる」と明記しています。各行を前に「これを削ると Claude がミスをするか？」と問い直し、YESと言えない行は削除するか .claude/rules/ に移します。

なぜ重要か: CLAUDE.md の内容はコンテキストウィンドウを消費します。肥大化すると会話スペースが削られるだけでなく、重要なルールが文脈の海に溺れて無視されます。顧問先の開発チームで320行あったCLAUDE.md を90行に圧縮したところ、明らかに指示の遵守率が改善した事例があります（想定シナリオ。実測値は環境による）。

失敗パターン2: Claude がコードを読めば分かる情報を書く

❌ よくある間違い: 「このプロジェクトは React 18 を使っています」「関数コンポーネントを使用します」「useState でステート管理をします」と書く。Claudeはpackage.jsonとコードを読めば自明に判断できます。

⭕ 正しいアプローチ: 「Claudeがコードを見ても知り得ない情報」だけを書く。たとえば「このプロジェクトは `pnpm vitest` を使います（npm testは動きません）」「src/legacy/ は触れないでください」「TEST_DATABASE_URL は `.env.test` を参照します」など、コードを読んでも分からない暗黙の知識に絞ります。

失敗パターン3: 禁止事項なのにツールで担保しない

❌ よくある間違い: 「console.logをコミットに含めないこと」「インデントはスペース2つ」と書くだけで、ESLintやPrettierで自動チェックしていない。

⭕ 正しいアプローチ: 公式ドキュメントに明記されているとおり「決定論的なツール（リンター・フォーマッター・Hooks）の方が高速・低コスト・信頼性が高い」という原則があります。CLAUDE.md は行動指針、確実に守らせたいルールはESLint・Prettier・git pre-commitフックで担保する。両方使って初めて意味があります。

失敗パターン4: CLAUDE.local.md を .gitignore し忘れる

❌ よくある間違い: CLAUDE.local.md にローカルのDB接続情報やサンドボックスURLを書いて、git commitに含めてしまう。

⭕ 正しいアプローチ: CLAUDE.local.md は個人の上書き設定（ローカルのURLや自分専用のテストデータなど）を置く場所です。必ず .gitignore に追記します。/init コマンドを実行すると、この設定を含めて自動的に処理してくれます。

研修・企業導入で効果が出た設計パターン5選

100社以上のClaude Code研修・導入支援で実際に効果が出た設計パターンを5つ紹介します。

パターン1: /init から始めるゼロベースセットアップ

何もない状態から CLAUDE.md を書こうとすると、何を書けばいいか迷って手が止まります。まず /init コマンドをプロジェクトルートで実行してください。

Claude がコードベースを解析してビルドシステム・テストフレームワーク・コーディングパターンを検出し、ベースとなる CLAUDE.md を自動生成します。これを起点に「うちの現場で必要なルール」だけを追記していくのが最も効率的なアプローチです。

CLAUDE_CODE_NEW_INIT=1 環境変数を設定すると、対話式の多段階フローが有効になり、スキルやHooksのセットアップまで一括で行えます（公式ドキュメント記載の機能）。

パターン2: ミスが起きたら即 CLAUDE.md に追記する

# CLAUDE.md に追記するタイミング

1. Claude が同じミスを2回犯したとき
2. コードレビューで「Claude が知っておくべきこと」が指摘されたとき
3. 前回セッションと同じ説明をチャットで打ち込んだとき
4. 新メンバーに「ここは気をつけて」と伝えた瞬間

これは Claude Code 公式ドキュメントが推奨するアプローチそのものです。「Boris Cherny（Claude Code 開発者）のルール: Claude が何か間違ったことをして修正した都度、CLAUDE.md にルールを追加する。時間とともに、ファイルはプロジェクトに関する蓄積された知識になる」と公式ドキュメントに明記されています。

パターン3: /compact 後も生き残るルールを CLAUDE.md に書く

長いセッションでは /compact が実行され、コンテキストが圧縮されます。重要なのは「プロジェクトルートの CLAUDE.md は /compact 後も再読み込みされる」という点です（公式ドキュメント記載）。一方、チャットの中でだけ伝えたルールは /compact で消えます。

特に長時間セッションが多いチームは、CLAUDE.md に「/compact 後も必ず保持する情報」を書いておく必要があります。

# /compact 後の保持事項（CLAUDE.md に明記しておく）
When compacting, always preserve:
- the full list of modified files
- the current test command and its status
- any known blockers or TODO items

パターン4: チームの CLAUDE.md は git で管理する

プロジェクトルートの CLAUDE.md を git 管理することで、チームの全メンバーが同じAIの動作環境を共有できます。「なぜこのルールがあるのか」をコメントで残しておくと、新メンバーのオンボーディングにも役立ちます。

# なぜこのルールがあるのか（コメント例）

## テストに pnpm vitest を使う理由

なお、CLAUDE.md 内の HTML コメント（<!-- ... -->）はコンテキストウィンドウへの注入前に除去されます（公式ドキュメント記載）。チームへのメモ書きをコメントにすれば、ルール本文をスリムに保てます。

パターン5: .claude/rules/ でパス別ルールを活用する

モノリポや複数チームが共存するプロジェクトでは、パス指定ルールが威力を発揮します。フロントエンドのコンポーネントファイルを触るときだけReactルールが読み込まれ、バックエンドのAPIファイルを触るときだけAPIルールが読み込まれます。

---
paths:
  - "src/components/**/*.{ts,tsx}"
---

# Reactコンポーネントルール
- カスタムHooksは `use` プレフィックスを付ける
- コンポーネントのpropsは `interface` で定義（typeエイリアスは使わない）
- useEffectの依存配列を空にする場合は必ずコメントで理由を書く

Claude Code 個別指導・企業研修での活用事例

事例区分: 想定シナリオ
以下は100社以上の研修経験をもとに構成した典型的なシナリオです。実際の企業名・数値は非公開です。

事例1: 開発チーム10名のCLAUDE.md 統一で出力品質が安定

ある中堅Web制作会社の開発チームでは、エンジニア10名が同じリポジトリで作業しているにもかかわらず、CLAUDE.md がなく各自が毎回異なる指示を与えていました。結果として、コーディングスタイルの不統一、テストの書き方のバラつき、コミットメッセージの乱れが常態化していました。

研修でプロジェクトルートに統一 CLAUDE.md を設置。ビルドコマンド・コーディング規約・禁止事項を80行以内にまとめたところ、コードレビュー時の「スタイル指摘」が減少し、チーム全体のレビュー時間短縮につながりました。

事例2: 研修現場で見た「CLAUDE.md 設計のコツ」

Claude Code 個別指導を受けた参加者の多くが共通してハマるのが、「全部書こうとして書けなくなる」パターンです。CLAUDE.md を完璧に仕上げてから使おうとすると、そのドキュメント作成自体が大きな仕事になってしまいます。

効果的なアプローチは「今日セッションで困ったことを1行追記する」というシンプルなルールです。毎日1〜2行追記するだけで、1ヶ月後には実用的な CLAUDE.md が育ちます。参加者からは「CLAUDE.md は育てるものだと分かってから、使い方が変わった」という声をよく聞きます。

グローバル CLAUDE.md の設計——チーム全体のAI環境を揃える

個人の ~/.claude/CLAUDE.md には、すべてのプロジェクトに共通する個人設定を書きます。

# ~/.claude/CLAUDE.md（個人グローバル設定）

## 個人のコーディングスタイル
- 変数名は英語のみ（日本語変数名は使わない）
- 関数の長さは50行以内を目安に（超えたら分割を検討）
- エラーメッセージは日本語で書く

## ワークフロー
- コミット前に必ず型チェックを実行する
- 実装完了後は必ず関連テストを追加してから完了とする

## Claudeへの指示
- 仕様が不明なときは実装する前に確認を求めること
- 大きな変更を加える場合は、まず計画を提示してから実装すること

組織全体でポリシーを強制したい場合（セキュリティ基準・コンプライアンス要件など）は、管理者が /Library/Application Support/ClaudeCode/CLAUDE.md（macOS）にマネージドポリシーファイルを配置します。このファイルは個人設定では除外できず、全セッションに適用されます（公式ドキュメント記載の企業向け機能）。

CLAUDE.md と Skills・Hooks の使い分け

CLAUDE.md だけがClaude Code の設定手段ではありません。目的に応じて最適なツールを選ぶことが重要です。

公式ドキュメントの表現を借りると、「CLAUDE.md で書いたことは Claude が参考にするが、フックは確実に実行される」というのが重要な違いです。

たとえば「コミット前にリントを実行する」というルールは、CLAUDE.md に書くだけでは Claude がスキップする可能性があります。git pre-commit フックとして設定することで、Claude が実行しようとしてもしなくても確実に動作します。

Claude Code 全体の活用戦略については AIエージェント導入完全ガイド で詳しく解説しています。

コピペ可能な CLAUDE.md テンプレート集

テンプレート1: Node.js/TypeScript プロジェクト（汎用）

# プロジェクト: [プロジェクト名]

## ビルド・テスト
- ビルド: `npm run build`
- テスト: `npm test`（jest使用）
- 型チェック: `tsc --noEmit`
- リント: `npm run lint`

## コーディング規約
- TypeScript strict モード有効
- `any` 型は使用禁止
- インデント: スペース2つ
- インポート: ES Modules (import/export)

## ディレクトリ規則
- `src/` — ソースコード
- `tests/` — テストファイル
- `dist/` — ビルド成果物（gitignore済み）

## 禁止事項
- `console.log` をコミットに含めない
- `src/legacy/` への変更（要事前確認）

## コミット規約
- conventional commits: feat/fix/docs/chore/test
- mainへの直接pushは禁止

テンプレート2: チーム開発用 プロジェクト設定（中〜大規模）

# [チーム名] Claude Code 設定

## コアルール（全員共通）
See @.claude/rules/coding-standards.md for coding standards.
See @.claude/rules/git-workflow.md for git workflow.

## プロジェクト概要
@README.md

## 重要な注意事項
- 本番DBへの直接操作は禁止。`staging` 環境を使う
- 機密情報（APIキー等）は `.env` に。コードに直書き禁止
- 既存APIの破壊的変更は必ずチームに確認してから

テンプレート3: 個人グローバル設定（すべてのプロジェクト共通）

# 個人グローバル設定（~/.claude/CLAUDE.md）

## 共通スタイル
- コメント・変数名・コミットメッセージは日本語可
- エラーメッセージは日本語で書く
- 意図が不明なときは実装前に確認を求めること

## 大きな変更のワークフロー
1. まず変更計画（何を・なぜ・どう変えるか）を提示する
2. 承認後に実装する
3. 実装後にテストを実行して結果を報告する

## 禁止事項
- APIキー・シークレットをコードに直書きしない
- 指示なしでファイルを削除しない
- 外部ライブラリを追加する場合は事前に確認する

テンプレート4: セキュリティ重視のエンタープライズ設定

# セキュリティポリシー（エンタープライズ）

## 必須チェック（変更前）
- セキュリティ要件: @.claude/rules/security.md
- コンプライアンス: @docs/compliance-guide.md

## 禁止操作
- ユーザーデータ（PII）のログ出力禁止
- SQLクエリの直接組み立て禁止（ORM必須）
- 外部URLへのリダイレクトはホワイトリスト確認必須

## インシデント対応
- セキュリティ問題を発見した場合は即座に実装を停止し、報告すること

CLAUDE.md を使った Claude Code 研修の実装例——社内展開の手順

「CLAUDE.md の書き方は分かった。でも社内の20人に展開するにはどうすればいい？」——研修でよく聞かれる質問です。実践的なロールアウト手順を紹介します。

ステップ1: パイロットチームで実証する（1〜2週間）

いきなり全社展開するのではなく、まず3〜5人のパイロットチームで CLAUDE.md を試します。以下のような最小構成から始めてください。

# パイロット用 CLAUDE.md（最小構成）

## ビルド・テスト
- テスト: [プロジェクトのテストコマンド]
- 型チェック: [型チェックコマンド]

## チームルール（今のところ最重要の3つ）
- [ルール1: 最もよく繰り返すミス]
- [ルール2: 全員に徹底してほしいこと]
- [ルール3: 禁止したい操作]

1〜2週間使ってみて「Claude が無視したルール」「もっと追加したいルール」「不要だったルール」を洗い出します。この実証フェーズを省いて一気に書き上げようとすると、使われない CLAUDE.md ができあがります。

ステップ2: フィードバックをもとに CLAUDE.md を整備する（1週間）

パイロット期間のフィードバックをもとに、CLAUDE.md をチームで整備します。以下のチェックリストを使ってください。

# CLAUDE.md 整備チェックリスト

## 削除すべき項目
- [ ] Claude がコードを読めば分かる情報（言語・フレームワーク名など）
- [ ] 200行を超えているセクション → .claude/rules/ に移す
- [ ] 「当たり前のこと」を書いている行（「クリーンなコードを書く」など）

## 追加すべき項目
- [ ] ビルド・テストコマンド（Claude が推測できない具体的コマンド）
- [ ] プロジェクト固有のディレクトリ構成（特殊なもの）
- [ ] 「触ってはいけないファイル・ディレクトリ」の明示
- [ ] 既知のゴッチャ（新メンバーが必ずハマること）
- [ ] Hooks で担保できる項目の洗い出し（リント・フォーマット等）

ステップ3: git 管理に移行してチーム展開する

CLAUDE.md を git リポジトリのルートにコミットします。PRを通すフローにすることで、ルールの追加・変更が記録として残ります。

# CLAUDE.md の git 管理ベストプラクティス

1. README.md と同じように扱う（更新履歴を残す）
2. 変更時は「なぜ追加したか」をコミットメッセージに書く
3. .gitignore に CLAUDE.local.md を追加しておく
4. チームの新メンバーオンボーディング資料に CLAUDE.md の場所を記載する

ステップ4: 定期見直しサイクルを作る（月1回）

CLAUDE.md は静的なドキュメントではありません。月1回（スプリント終わり or 振り返り MTG のタイミング）に以下を確認することをお勧めします。

• Claude が繰り返し無視したルールはないか（追記 or Hooks へ移行）
• プロジェクトの変化に合わせて古くなったルールはないか
• 200行を超えていないか（超えていたら .claude/rules/ に分割）
• 新メンバーが「なぜこのルールが？」と思ったルールはないか（コメントを追記）

Auto Memory との連携設計——Claude に学習させる仕組みを作る

CLAUDE.md はあなたが書くルールですが、Auto Memory は Claude が自動的に書き溜めるメモです。この2つを正しく使い分けると、セッションをまたいでClaude の動きが継続的に改善されます。

Auto Memory が保存するもの

公式ドキュメントによれば、Auto Memory には以下のような情報が記録されます。

• ビルドコマンドやデバッグで見つかったパターン
• コーディングスタイルの好み
• ワークフローの習慣
• あなたが修正した内容と、その修正から学んだこと

保存場所は ~/.claude/projects/<project>/memory/ で、プロジェクトごとに独立しています。Auto Memory は機械ローカルであり、他のマシンやクラウドとは共有されません。

CLAUDE.md と Auto Memory の役割分担

# CLAUDE.md に書くもの（チームで共有・git管理）
- コーディング規約
- ビルド・テストコマンド
- 禁止事項
- ディレクトリ構成
- ワークフロー

# Auto Memory に任せるもの（個人の学習・機械ローカル）
- 個人の作業習慣のパターン
- よく使うデバッグコマンド
- プロジェクト固有の発見
- 修正から学んだ知識

Auto Memory を確認・編集するには /memory コマンドを使います。すべてのファイルはプレーンな Markdown なので、不要な内容は直接削除できます。

Auto Memory が溜まりすぎた場合の対処

Auto Memory の MEMORY.md は最初の200行または25KBのみがセッション開始時に読み込まれます（公式ドキュメント記載）。それ以上の詳細は Claude がオンデマンドで読みにいきます。MEMORY.md が肥大化していると感じたら /memory コマンドで整理しましょう。

よくある質問——CLAUDE.md の疑問を解消する

Q: CLAUDE.md と AGENTS.md は何が違うの？

A: Claude Code が読むのは CLAUDE.md だけです。他の AIコーディングツール（Cursor、Devin など）向けに AGENTS.md を使っているリポジトリでは、CLAUDE.md から @AGENTS.md でインポートすると両方に同じ内容が反映されます。シンボリックリンクでも対応できます。

Q: CLAUDE.md に書いたのに Claude が守ってくれない

A: 公式ドキュメントによれば、CLAUDE.md はシステムプロンプトではなくユーザーメッセージとして届けられます。強制力はありません。対策として（1）ファイルを200行以内にする（2）より具体的な表現にする（3）「IMPORTANT」「YOU MUST」などの強調語を加える、があります。確実に実行させたい処理は Hooks で担保するのが正解です。

Q: /compact 後にルールが消えた

A: プロジェクトルートの CLAUDE.md は /compact 後に再読み込みされます。ただし、サブディレクトリの CLAUDE.md は再インジェクトされません（次にそのディレクトリのファイルを読んだときに再ロード）。重要なルールはプロジェクトルートの CLAUDE.md か、CLAUDE.md 内に「/compact 後も保持するリスト」として明示しておく必要があります。

Q: チームの誰かが CLAUDE.md を勝手に変えてしまう

A: CLAUDE.md を git で管理することで、変更履歴を追えます。重要な変更はPRを通すルールにするか、LGTM（レビュー承認）必須の設定にするのがお勧めです。「なぜこのルールがあるのか」をコメントで残しておくと、意図が理解されず削除されるリスクが減ります。

Claude Code 研修・個人指導については 法人向けClaude Code研修 のご案内もご覧ください。個人から企業チームまで、CLAUDE.md 設計を含めた実践的な活用支援を行っています。

モノリポ・大規模プロジェクトでの CLAUDE.md 設計

フロントエンド・バックエンド・インフラが同一リポジトリに共存するモノリポでは、単一の CLAUDE.md ではルールが混在してしまいます。公式ドキュメントが推奨する構成を具体的に見ていきましょう。

モノリポの推奨ディレクトリ構成

monorepo/
├── CLAUDE.md                    # 全体共通（50行以内・最重要事項のみ）
├── .claude/
│   └── rules/
│       ├── git-workflow.md      # git運用（全パッケージ共通）
│       └── security.md         # セキュリティ要件（全パッケージ共通）
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md           # フロントエンド固有のルール
│   ├── backend/
│   │   └── CLAUDE.md           # バックエンド固有のルール
│   └── infra/
│       └── CLAUDE.md           # インフラ固有のルール（破壊的操作の制限等）
└── CLAUDE.local.md              # 個人設定（.gitignore済み）

この構成では、monorepo/packages/frontend/ ディレクトリでファイルを読んだとき、上位の monorepo/CLAUDE.md と monorepo/.claude/rules/*.md が読み込まれた後、monorepo/packages/frontend/CLAUDE.md が追加でロードされます。

注意点として、CLAUDE.md は「ディレクトリツリーを上に向かってウォーク」して読み込まれます。つまり別パッケージの CLAUDE.md は読み込まれません（同じ階層のサブディレクトリ同士は互いを見ない）。モノリポ内で他チームの CLAUDE.md が誤って読み込まれる場合は claudeMdExcludes 設定で除外できます（公式ドキュメント記載）。

インフラ・デプロイ系の CLAUDE.md には特別な注意が必要

インフラのコード（Terraform・Kubernetes YAML・デプロイスクリプト等）を扱うディレクトリの CLAUDE.md には、破壊的操作への明示的なガードが重要です。

# infra/CLAUDE.md

## 破壊的操作の制限（必読）
- terraform destroy は実行しない（要事前承認）
- production namespace への kubectl apply は実行しない
- RDSインスタンスの削除・変更は実行しない

## staging 環境のみ操作してよい変更
- Kubernetes Deployment の image タグ更新
- ConfigMap の非機密パラメータ更新
- HPA のreplica数調整

## 変更前に必ず確認すること
- 変更が production に影響するか
- ロールバック手順が存在するか
- 変更ウィンドウが設定されているか

インフラ系の誤操作はダウンタイムや本番障害に直結します。「禁止操作を CLAUDE.md に書く」のは第一歩ですが、確実に担保するには Hooks の PreToolUse でコマンドをブロックする実装も検討してください。

まとめ: 今日から始める CLAUDE.md 設計の3ステップ

この記事で紹介した内容を整理します。

1. 今日やること: プロジェクトで /init を実行して CLAUDE.md のベースを自動生成する。既存のファイルがある場合は「200行を超えていないか」と「コードを読めば分かる情報が含まれていないか」を確認して削除する
2. 今週中: ビルドコマンド・テストコマンド・コーディング規約・禁止事項の4カテゴリを揃える。CLAUDE.local.md を .gitignore に追記する
3. 今月中: チームで CLAUDE.md を git 管理に移行する。Claude が同じミスをするたびに1行追記するルールをチームに展開する

CLAUDE.md は「完成したら終わり」のドキュメントではありません。毎週少しずつ育てることで、チームのAIコーディング品質が継続的に改善していきます。まずは今日、/init コマンドを1回実行してみてください。

次回予告: 次の記事では「Claude Code の Hooks 設計——コミット前の自動チェックをゼロから設定する方法」をテーマに、実務で使えるHooks設定集をお届けします。

あわせて読みたい:

• AIエージェント導入完全ガイド — 企業AI導入の全体像と戦略
• ChatGPT業務活用ガイド — 生成AIを業務で使いこなす基本
• AI導入戦略の完全ガイド — 中小企業向けAI活用ロードマップ

参考・出典

• How Claude remembers your project — Claude Code 公式ドキュメント — Anthropic（参照日: 2026-06-12）
• Best practices for Claude Code — Claude Code 公式ドキュメント — Anthropic（参照日: 2026-06-12）
• The Ultimate Guide to CLAUDE.md in 2026 — Buildcamp（参照日: 2026-06-12）

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。