32blogby Studio Mitsu

Claude Codeのコンテキスト管理術｜CLAUDE.md設計パターン

CLAUDE.md設計5パターンに加え、Auto Memory・Hooks・Custom Commandsを網羅。1Mコンテキスト時代の実践ガイド。

by omitsu27 min read
Claude CodeCLAUDE.mdcontext-managementprompt-designproductivity
目次

Claude Codeのコンテキスト管理の核心は「CLAUDE.mdは短く具体的に、ルールはディレクトリ別に分割し、コンテキスト窓に入る情報を能動的に管理する」の一言に尽きる。この記事で紹介する5つのCLAUDE.md設計パターン（ミニマル型・セクション分割型・タスク特化型・階層型・コンテキスト注入型）と、Auto Memory・Hooks・セッション分割を組み合わせれば、Claude Codeがルールをちゃんと守ってくれるようになる。

CLAUDE.mdを書いたのに、Claude Codeが全然それを参照してくれない——GitHub Discussionsでもよくある悩みだ。原因はCLAUDE.mdの書き方にあることが多い。

この記事では、Claude Codeを実務で使う中で見えてきたコンテキスト管理の実践パターン を全部まとめる。CLAUDE.md設計の5パターン、.claudeignoreの使い方、Plan modeとの組み合わせで、体感の生産性が大きく変わる。

CLAUDE.mdルール定義読み込みコンテキスト窓200K トークンフィルタ.claudeignoreノイズ除外最適化高品質な出力ルール遵守

コンテキスト窓はなぜすぐ埋まる？

2026年3月、Claude CodeはOpus 4.6 / Sonnet 4.6で最大100万トークンに対応した。従来の200Kから一気に5倍だ。しかし、100万トークンあってもコンテキスト管理は重要。コンテキストが増えても出力の質が比例するわけではない。ノイズが増えるだけだ。

たとえばNext.jsプロジェクトで「全ページのリファクタをやってほしい」と依頼すると、ファイル読み込みだけで数万トークンが消える。その上に会話履歴、CLAUDE.mdの内容、ツール定義、MCPサーバー、コード生成結果が積み重なると、思った以上に速く埋まる。

コンテキストが膨張すると何が起きるか。Claudeの注意力が分散する。重要なルールが何千行もの無関係なコードと競合する。実際のところ、200Kで集中したセッションの方が、100万トークンでとっ散らかったセッションよりいい結果を出すことが多い。シグナル密度が高いからだ。

コンテキスト使用量の目安（体感値）:

  • CLAUDE.md（標準的な量）: 2,000〜5,000トークン
  • システムプロンプト＋ツール: 約40,000トークン
  • ソースファイル1本（500行）: 約5,000トークン
  • 会話履歴（長めのセッション）: 50,000〜200,000トークン

/context コマンドでトークンの使い道の内訳を確認できる。画面下部のインジケーターも参考になる。

つまり、コンテキスト管理とは「何を窓の中に入れて、何を入れないか」の設計。窓のサイズが大きくなっても、この原則は変わらない。

CLAUDE.md が「読まれない」のはなぜ？

経験上、CLAUDE.mdが機能しない理由は大体3つに絞られる。

失敗1: ルールが多すぎる

「コーディング規約、ディレクトリ構成、禁止事項、テスト方針...」と全部書くと、Claudeはそれを全部読んだ上で文脈を把握しようとする。結果、ルールへの注意力が分散して重要なものが守られない。

失敗2: 曖昧な指示

「丁寧に書いてください」「わかりやすくしてください」は機能しない。「関数は1つの責務のみ持つ」「コメントは英語で書く」のように、機械的に判定できる形式で書く。

失敗3: プロジェクト全体に1枚だけ書く

ルートの CLAUDE.md は大きくなりがちで、プロジェクト全体の汎用ルールしか書けない。モジュールごとに異なる方針がある場合、サブディレクトリに別の CLAUDE.md を置く構成が有効だ。

実務で通用する CLAUDE.md の設計パターンは？

試行錯誤の末に落ち着いた5つのパターンを紹介する。

パターン1: ミニマル型（小規模プロジェクト向け）

markdown
# Project Rules
- Language: TypeScript strict mode
- Test: Vitest. Run `pnpm test` before committing
- Style: No inline styles. Tailwind only

必要最低限だけ書く。10行以内を目標に。余白を恐れない。

パターン2: セクション分割型（中規模プロジェクト向け）

markdown
# CLAUDE.md

## Critical Rules (必ず守る)
- 本番DBへの直接書き込み禁止
- secrets を console.log に出力しない

## Code Style
- 関数は Pure Function を優先
- 副作用は useEffect / event handler に閉じ込める

## Project Context
- Next.js 15 App Router
- Supabase (RLS有効)
- デプロイ先: Vercel

「守らないと致命的なルール」と「スタイルガイド」を明確に分ける。

パターン3: タスク特化型（特定作業セッション向け）

タスク特化型CLAUDE.mdをテンプレート化しておくと、セッション開始の摩擦がゼロになる。「今日のタスク」「触るファイル」「制約」の3セクションを毎回埋めるだけで、Claude Codeの精度が大幅に上がる。

markdown
# Current Task Context
今日のタスク: 認証モジュールのリファクタ
触るファイル: src/auth/ 以下のみ
触らないファイル: src/api/, src/components/

## 制約
- Supabase Auth は変更しない
- テストは既存のものを通す（新規追加はOK）

長期プロジェクトで「今日の作業」だけに集中させたいときに効果的。セッション開始時に書き換える。

パターン4: 階層型（大規模プロジェクト向け）

root/CLAUDE.md         # プロジェクト全体のルール（最小限）
src/api/CLAUDE.md      # API層固有のルール
src/components/CLAUDE.md  # UI層固有のルール
src/lib/CLAUDE.md      # ユーティリティ層のルール

Claude Codeはカレントディレクトリから親方向にCLAUDE.mdを検索して全部読む。階層を分けることで、各モジュールに最適化されたルールを適用できる。

パターン5: コンテキスト注入型（外部情報の参照向け）

markdown
## Architecture Decision Records
参照: docs/adr/ (重要な設計決定がここにある)

## API仕様
参照: docs/api-spec.md (エンドポイント一覧)

## 現在の既知バグ
- #234: ログアウト後にセッションが残るケースあり（対応中）

実際のドキュメントをCLAUDE.mdに全部書くのではなく、「どこを見れば何がわかるか」のインデックスとして使う。

.claudeignore で不要なファイルを除外するには？

.claudeignore は .gitignore と同じ構文で書ける。Claude Codeがファイルをインデックスする際に除外するファイルを指定できる。

# .claudeignore

# ビルド成果物（絶対に除外）
.next/
dist/
out/
node_modules/

# 大きいが読む必要がないファイル
*.lock
pnpm-lock.yaml
package-lock.json

# テストスナップショット（大量のトークンを食う）
**/__snapshots__/
**/*.snap

# 機密情報
.env*
*.pem
*.key

# 画像・バイナリ
*.png
*.jpg
*.svg
*.woff2

# ログ
*.log
logs/

特に重要なのは node_modules/ と .next/ だ。これを除外するだけでコンテキスト消費量が劇的に減る。

pnpm-lock.yaml のようなロックファイルも要注意。数千行に及ぶこともあり、誤ってコンテキストに入ると大きなトークンを無駄にする。

Plan mode はどんな時に使えばいい？

Plan mode は、実装前にClaudeに「何をするか」だけ考えさせるモードだ。Shift+Tab を2回押すとPlan modeに切り替わる。v2.1.0以降は /plan コマンドでも切り替え可能。

使うべき場面:

  • 影響範囲が広いリファクタリング（10ファイル以上）
  • データベーススキーマの変更
  • 認証・決済フローの変更
  • 「何から始めればいい？」がわからないとき

使わなくていい場面:

  • バグ修正（原因が明確な場合）
  • 新規コンポーネントの追加
  • テストの追加・修正
  • 単純なリネーム・移動

Plan modeの最大の利点は、実装に入る前に「方針のズレ」を発見できること。Claudeが「A→B→C の順で実装します」と言ったとき、「いやBより先にCをやってほしい」とフィードバックできる。これをやらないと、大量のコードを書いた後に方向転換が必要になる。

bash
# Shift+Tab を2回押す（または /plan と入力）してから指示する
> ユーザー認証をJWT→Supabase Authに移行したい。まず計画だけ立てて。

Claudeが実装計画を出したら、内容をレビューする。問題なければ Shift+Tab でPlan modeを解除して「この計画で実装して」と指示する。

/compact と /clear はどう使い分ける？

長いセッションを続けると、コンテキストが膨張して応答品質が落ちる。2つのコマンドで対処できる。

/compact — コンテキストを圧縮する

会話履歴を要約して「重要な決定」だけを残す。まだ同じセッションを続けたいが、コンテキストが重くなってきたときに使う。

bash
> /compact

/clear — コンテキストをリセットする

会話履歴を全部消して新鮮な状態にする。タスクが一区切りついたとき、または全然違う作業に移るときに使う。CLAUDE.mdは再度読み込まれる。

コンテキスト使用量の確認 — /context コマンドでシステムプロンプト・ツール・MCPサーバー・メモリ・会話履歴それぞれのトークン使用量を確認できる。Claudeの挙動がおかしくなったときの診断ツールとして最も有用。

実際の運用では「作業が1タスク分終わったら /clear」を習慣にするだけで、コンテキスト汚染が大幅に減る。

長いセッションでの具体的な対策はClaude Codeのメモリ管理：長時間セッションを生産的に保つ方法も参考にしてほしい。

Auto Memory — Claudeが自分でメモを取る時代

2026年2月末に追加されたAuto Memoryは、Claude Codeが会話中に重要な情報を自動で記録する機能だ。保存先は ~/.claude/projects/<project>/memory/ ディレクトリで、MEMORY.md がインデックスファイルとして機能する。

CLAUDE.md と Auto Memory の役割分担:

CLAUDE.mdAuto Memory
誰が書くあなたClaude自身
内容ルール・制約・プロジェクト構成ユーザーの好み・フィードバック・プロジェクト状態
読み込み毎セッション自動読み込みMEMORY.mdの先頭200行が自動注入
更新タイミング手動会話中に自動

実用例:

  • 「テストにはmockを使わないで」と伝えると、Auto Memoryがfeedbackとして記録。次のセッションでも守られる
  • プロジェクトの財務状況や締め切りなど、コードに現れない文脈を記録
  • 「このユーザーはTypeScript上級者」のような情報を保持し、説明の粒度を自動調整

CLAUDE.mdに書くべきこと は変わらない。ルール・制約・技術スタック。一方で「Claudeへのフィードバック」「プロジェクトの状態」はAuto Memoryに任せる。両者を混ぜるとCLAUDE.mdが肥大化する。

bash
# Auto Memoryの管理
> /memory          # メモリ一覧を表示

MEMORY.md は先頭200行しかコンテキストに注入されないため、メモリが増えたら古い情報を整理する必要がある。

Hooks — ルールを「お願い」から「強制」にする

CLAUDE.mdに書いたルールは、あくまで「お願い」だ。Claudeがコンテキストの圧迫で忘れる可能性がある。Hooksを使えば、特定のアクションに対してシェルスクリプトを自動実行できる。ルールを「強制」に格上げできる。

Hooksの基本構造（settings.json）:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/check-script.sh"
          }
        ]
      }
    ]
  }
}

実務で役立つ3つのHookイベント:

1. PreToolUse — ツール実行前にチェック

ファイル書き込みの前にリントを走らせる、特定ディレクトリへの書き込みをブロックするなど。

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/hooks/pre-write-check.sh $FILE_PATH"
          }
        ]
      }
    ]
  }
}

2. PostToolUse — ツール実行後に処理

コミット後にテストを自動実行、ファイル変更後にフォーマッタを走らせるなど。

3. PreCompact — コンテキスト圧縮前に重要情報を退避

Auto Compactionでコンテキストが圧縮される前に、重要な決定事項をファイルに書き出す。長いセッションで「Claudeが前提を忘れる」問題への根本対策。

Claude Codeは現在20種類以上のHookイベントをサポートしている（SessionStart、WorktreeCreate、InstructionsLoadedなど）。全部を使う必要はない。上の3つだけで実務の大半はカバーできる。

Custom Commands — 繰り返しの指示をワンコマンド化する

「毎回同じ指示を打つのが面倒」という問題には、Custom Commandsが使える。.claude/commands/ ディレクトリにMarkdownファイルを置くだけで、/ で呼び出せるコマンドになる。現在は「Skills」に統合され .claude/skills/<name>/SKILL.md が推奨形式だが、.claude/commands/ も引き続き動作する。

例: コードレビューコマンド

markdown
<!-- .claude/commands/review.md -->
以下のファイルをレビューしてください:
- 型安全性に問題はないか
- エラーハンドリングは十分か
- テストが不足している箇所はないか

対象: $ARGUMENTS

使い方:

bash
> /review src/auth/login.ts

例: コミット前チェック

markdown
<!-- .claude/commands/pre-commit.md -->
以下を順番に実行してください:
1. `pnpm typecheck` で型チェック
2. `pnpm test` でテスト実行
3. 問題があれば修正、なければ `git add` と `git commit`

Custom CommandsとHooksの使い分け:

  • Custom Commands = 人間が明示的に呼び出す（/review）
  • Hooks = 特定のイベントに自動で反応する（ファイル保存時）

大規模プロジェクトはどうセッションを分割する？

1セッションで全部やろうとしない。これがコンテキスト管理の根本的な考え方だ。

大規模プロジェクトは以下のように分割する：

分割の単位例:

  • セッション1: 認証モジュールのリファクタ
  • セッション2: APIエンドポイントの整理
  • セッション3: フロントエンドの状態管理見直し
  • セッション4: テスト追加・カバレッジ改善

各セッションの引き継ぎはMarkdownで管理する。

markdown
# session-handoff.md（セッション終了時に更新）

## 完了したこと
- src/auth/login.ts を JWT から Supabase Auth に移行
- 既存テスト全通過確認

## 次セッションでやること
- src/auth/register.ts の移行（login.ts と同じ手順）
- middleware.ts の認証チェック更新

## 注意事項
- Supabase の Row Level Security は有効のまま
- NEXT_PUBLIC_SUPABASE_URL は .env.local に設定済み

次のセッション開始時にこのファイルをCLAUDE.mdに include するか、冒頭でペーストする。セッションが途切れても文脈が失われない。

Auto Memory時代のセッション引き継ぎ: Auto Memoryが有効なら、Claudeが重要な決定事項を自動で記録してくれる。ただし、Auto Memoryは「Claudeが重要だと判断した情報」しか保存しない。プロジェクト固有の引き継ぎ（「次はこのファイルを触る」等）は引き続き手動でsession-handoff.mdに書くのが確実だ。

コンテキスト使用率をどう監視・管理する？

コンテキスト管理を意識するだけで品質が変わる。具体的に取り入れた習慣を紹介する。

セッション開始前のチェックリスト:

  • 今日のタスクは明確か？
  • CLAUDE.mdは今日のタスクに合っているか？
  • .claudeignoreで不要ファイルを除外しているか？
  • 前回セッションの引き継ぎメモはあるか？

セッション中のチェックポイント:

  • 30分ごとに /context で使用量確認
  • 「なんかズレてきた」と感じたら即 /compact
  • タスク完了ごとに /clear

セッション終了時:

  • session-handoff.md を更新
  • CLAUDE.mdに当日の決定事項を反映
  • 次セッションで使いそうなコンテキストをメモ

コンテキスト管理は「Claude Codeを使いこなす」の根幹だ。ツールの能力を100%引き出すには、使う側がアーキテクトとして設計する必要がある。CLAUDE.mdは設計図であり、コンテキストはリソースだ。適切に設計・管理することで、AI開発の生産性は別次元に上がる。

モノレポや大規模プロジェクトでCLAUDE.mdをどう分割する？

プロジェクトが大きくなると、1つのCLAUDE.mdに全ルールを書くのは現実的じゃない。Claude Codeは .claude/rules/ ディレクトリとサブディレクトリのCLAUDE.mdを階層的に読み込む仕組みを持っている。

ルートCLAUDE.md（プロジェクト全体）:

markdown
# プロジェクト共通ルール
- TypeScript strict mode必須
- テストはVitest
- コミットメッセージはConventional Commits

.claude/rules/frontend.md（フロントエンド固有）:

markdown
# フロントエンドルール
- コンポーネントはServer Component優先
- "use client" は必要な場合のみ
- Tailwind CSS v4のユーティリティクラスを使う

packages/api/CLAUDE.md（APIパッケージ固有）:

markdown
# API固有ルール
- Honoを使用
- レスポンスはzodスキーマでバリデーション
- エラーはRFC 7807形式で返す

この階層構造のポイントは3つある。

  1. ルートは共通ルールだけ — 全パッケージに適用される最小限のルール
  2. .claude/rules/ はドメイン別 — フロントエンド、バックエンド、インフラなどで分割
  3. サブディレクトリCLAUDE.mdは局所ルール — そのディレクトリ配下で作業するときだけ読み込まれる

Claude Codeは作業中のファイルパスに基づいて、関連するCLAUDE.mdを自動で読み込む。packages/api/ 配下で作業しているときは、ルートのCLAUDE.md + packages/api/CLAUDE.md が両方読み込まれる。

目安: CLAUDE.mdの合計が200行を超えたら分割のサイン。ルートに書くのは「どのファイルを触っていても守るべきルール」だけにしよう。

よくある質問

CLAUDE.mdと.claude/rules/の違いは？

プロジェクトルートのCLAUDE.mdはどのファイルを触っていても毎セッション読み込まれる。.claude/rules/ のファイルも自動読み込みだが、ドメイン別ルール（フロントエンド、バックエンド等）の分割に向いている。ルートCLAUDE.mdは全体共通ルール、.claude/rules/ はドメイン別に使い分けよう。詳しくは公式メモリドキュメントを参照。

100万トークンのコンテキスト窓でもCLAUDE.mdは重要？

むしろ100万トークンだからこそ重要になる。窓が大きいとClaude Codeが自動的に読むファイルも増え、CLAUDE.mdのルールと競合するノイズが増える。ルールを簡潔に保つことで、窓のサイズに関係なくシグナル密度を維持できる。

CLAUDE.mdは何行くらいが適切？

ルートCLAUDE.mdは10〜30行を目安に。全CLAUDE.mdファイルの合計が200行を超えたら分割のサイン。1行ごとに「これを削除したらClaude Codeがミスするか？」のテストを通そう。

モノレポでもCLAUDE.mdは使える？

使える。ルートCLAUDE.mdに最小限の共通ルールを置き、.claude/rules/ でドメイン別ルール、パッケージごとにCLAUDE.md（例: packages/api/CLAUDE.md）を追加する構成が効果的だ。

CLAUDE.mdとAuto Memoryの使い分けは？

CLAUDE.mdは自分で書いて管理するルール・制約・プロジェクト構成用。Auto MemoryはClaude自身が記録するユーザーの好み・フィードバック・プロジェクト状態用。「常にこのimportスタイルを使え」のようなルールはAuto Memoryではなく、CLAUDE.mdに書く。

.claudeignoreは本当にファイル読み込みを防げる？

一部だけ。.claudeignore はClaude Codeの自動ファイル検索（インデックス作成）をブロックするが、パスを明示指定すれば読める。トークン削減には有効。厳密なアクセス制御にはHooksや settings.json のdeny権限を使おう。

/compactと/clearはどのくらいの頻度で使う？

/clear はタスク1つ完了するたびに実行。これが最も効果的な習慣だ。/compact はタスクの途中でコンテキストが重くなったときに使う。/context で実際の使用量を確認してから判断するのがベスト。

HooksだけでCLAUDE.mdのルールを完全に置き換えられる？

置き換えられない。Hooksは特定のアクション（ファイル書き込みのブロック、リンターの実行）を強制するもので、「Pure Functionを優先する」「Server Componentsをデフォルトにする」のようなセマンティックなガイダンスには使えない。CLAUDE.mdで意図を伝え、Hooksで実行を強制する使い分けが正解。

まとめ

ポイント実践方法
CLAUDE.mdは短く、具体的に10〜30行を目標。機械的に判定できるルールのみ
階層的に配置するモジュール単位でサブCLAUDE.mdを設置
.claudeignoreでノイズ削減node_modules, .next, *.lock は最低限除外
Auto Memoryに任せるフィードバック・プロジェクト状態はClaude自身に記録させる
Hooksでルールを強制するPreToolUse / PostToolUse / PreCompact の3つから始める
Custom Commandsで省力化繰り返しの指示は .claude/commands/ にテンプレ化
Plan modeを使う10ファイル以上の変更は必ず計画から
セッションを分割する1セッション = 1タスクを基本に
引き継ぎメモを書くsession-handoff.mdで文脈を保存

CLAUDE.mdが読まれないと感じているなら、まず長さを半分にしてみることをすすめる。情報を削ることへの恐怖より、Claudeの注意力が分散することの方が損失は大きい。

関連記事: