32blogby StudioMitsu
claude-code14 min read

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

Claude Codeのコンテキスト管理を制する者がAI開発を制する。CLAUDE.md設計の5パターン・.claudeignore・Plan modeの組み合わせで生産性を35%上げた実践記録。

claude-codeCLAUDE.mdコンテキスト管理プロンプト設計生産性
目次

CLAUDE.mdを一生懸命書いたのに、Claude Codeが全然それを参照してくれない。「お前それ読んでないよね？」と思った経験が、僕には何度もあった。原因はCLAUDE.mdの書き方にあった。

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

コンテキスト窓 200,000 トークンはなぜすぐ埋まる？

Claude Codeのコンテキスト窓は現在200,000トークン。一見巨大に見えるが、実際の開発では瞬く間に埋まる。

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

コンテキストが溢れると何が起きるか。Claude Codeは古い情報から忘れていく。最悪の場合、CLAUDE.mdに書いたルールを「なかったこと」にして作業を進める。これがCLAUDE.mdが「読まれない」の正体だ。

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

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

つまり、コンテキスト管理とは「何を窓の中に入れて、何を入れないか」の設計そのものだ。

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: タスク特化型（特定作業セッション向け）

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（/plan コマンド）は、実装前にClaudeに「何をするか」だけ考えさせるモードだ。

使うべき場面:

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

使わなくていい場面:

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

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

bash
# Plan modeの実際の使い方
> /plan ユーザー認証をJWT→Supabase Authに移行する

Claudeが実装計画を出したら、それをレビューしてから /approve で実装に移る。

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

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

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

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

bash
> /compact

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

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

/context — 現在のコンテキスト使用状況を確認する

bash
> /context
# → 現在のトークン使用量と残量が表示される

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

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

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 するか、冒頭でペーストする。セッションが途切れても文脈が失われない。

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

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

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

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

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

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

セッション終了時:

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

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

まとめ

ポイント実践方法
CLAUDE.mdは短く、具体的に10〜30行を目標。機械的に判定できるルールのみ
階層的に配置するモジュール単位でサブCLAUDE.mdを設置
.claudeignoreは必須node_modules, .next, *.lock は最低限除外
Plan modeを使う10ファイル以上の変更は必ず計画から
セッションを分割する1セッション = 1タスクを基本に
引き継ぎメモを書くsession-handoff.mdで文脈を保存

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