- CLAUDE.mdはプロジェクト固有の知識をClaude Codeに伝える最重要ファイル。設計パターン次第で出力品質が劇的に変わる
- コンテキストウィンドウの上限を意識し、コンパクション戦略を使えばトークン消費を50%以上削減できる
- メモリの階層設計（グローバル→プロジェクト→タスク）で、チーム全体の開発効率が向上する
Claude Codeを使い込んでいくと、ある壁にぶつかります。**「なぜ同じ説明を毎回しなければならないのか」**という問題です。プロジェクトのコーディング規約、使用しているフレームワークの慣習、チーム独自のディレクトリ構造——これらを毎セッション伝え直すのは非効率です。
この問題を根本的に解決するのが、Claude Codeのメモリ・コンテキスト管理機能です。特にCLAUDE.mdファイルを適切に設計し、コンテキストウィンドウを最適化することで、セッション間の知識を永続化し、出力品質を安定させることができます。
本記事では、CLAUDE.mdの設計パターンからコンテキスト圧縮テクニック、チーム運用まで、メモリ管理の全体像を実践コード付きで解説します。
- CLAUDE.mdの階層設計と効果的な記述パターン
- コンテキストウィンドウの仕組みと最適化戦略
- コンパクション（自動圧縮）の活用方法
- チームでメモリを共有・運用するベストプラクティス
CLAUDE.mdとは？プロジェクト記憶の核心
CLAUDE.mdの役割と仕組み
CLAUDE.mdは、Claude Codeがセッション開始時に自動的に読み込むプロジェクト設定ファイルです。いわば「AIへのオンボーディングドキュメント」であり、以下の情報を伝えます。
- プロジェクトの技術スタック・アーキテクチャ
- コーディング規約・命名規則
- ディレクトリ構造とファイルの役割
- よく使うコマンド（ビルド、テスト、デプロイ）
- 避けるべきパターン・既知の制約
CLAUDE.mdが存在しない状態でClaude Codeを使うことは、新人エンジニアにプロジェクト説明なしでコードを書かせるのと同じです。毎回「うちはTypeScriptで書いて」「テストはVitestを使って」と指示する手間が発生します。
# CLAUDE.md
## プロジェクト概要
ECサイトのバックエンドAPI。TypeScript + Hono + Drizzle ORM。
## 技術スタック
- Runtime: Bun 1.2
- Framework: Hono v4
- ORM: Drizzle ORM
- Database: PostgreSQL 16
- Test: Vitest + Supertest
## ディレクトリ構造
src/
routes/ # APIルート定義
services/ # ビジネスロジック
models/ # Drizzleスキーマ
middleware/ # 認証・バリデーション
utils/ # ユーティリティ
## コーディング規約
- 関数はアロー関数で統一
- エラーは Result型パターン（neverthrow）で処理
- 型定義は models/ にまとめる
- テストファイルは *.test.ts で同じディレクトリに配置
## よく使うコマンド
- `bun run dev` — 開発サーバー起動
- `bun test` — テスト実行
- `bun run build` — ビルド
- `bun run db:migrate` — マイグレーション実行CLAUDE.mdの読み込み階層
Claude Codeは複数の場所からCLAUDE.mdを読み込みます。この階層構造を活用することで、グローバル設定からプロジェクト固有の設定まで効率的に管理できます。
| 階層 | パス | 用途 |
|---|---|---|
| グローバル | ~/.claude/CLAUDE.md | 全プロジェクト共通の好み・スタイル |
| プロジェクトルート | ./CLAUDE.md | プロジェクト全体の設定 |
| サブディレクトリ | ./packages/api/CLAUDE.md | パッケージ固有の設定 |
| ローカル（gitignore） | .claude/CLAUDE.local.md | 個人設定（共有しない） |
階層が深い設定ほど優先度が高くなります。monorepo構成では、各パッケージに専用のCLAUDE.mdを配置することで、パッケージ固有のコンテキストを効率的に伝えられます。
my-monorepo/
├── CLAUDE.md # 共通設定（TypeScript, ESLint設定等）
├── packages/
│ ├── api/
│ │ └── CLAUDE.md # API固有（Hono, DB設定等）
│ ├── web/
│ │ └── CLAUDE.md # フロントエンド固有（Next.js設定等）
│ └── shared/
│ └── CLAUDE.md # 共通ライブラリ固有
└── .claude/
└── CLAUDE.local.md # 個人設定（gitignore対象）効果的なCLAUDE.mdの設計パターン
パターン1: ルールベース設計
最もシンプルで効果的なパターンです。**「やること」と「やらないこと」**を明確にリスト化します。
## ルール
### 必ず守ること
- 全ての関数にJSDoc / TSDocコメントを付ける
- エラーハンドリングにはResult型を使う（try-catchは最外層のみ）
- APIレスポンスは必ず型定義してから返す
- テストカバレッジは80%以上を維持
### やってはいけないこと
- any型の使用（unknownを使う）
- console.logでのデバッグ出力の残留
- 環境変数の直接参照（config.tsを経由する）
- default exportの使用（named exportに統一）このパターンの利点はClaude Codeが判断に迷わないことです。曖昧な記述（「できれば型を付けてください」）よりも、明確なルール（「全関数にTSDocを付ける」）の方が遵守率が格段に高くなります。
パターン2: コンテキスト補完設計
プロジェクト固有の暗黙知を明文化するパターンです。Claude Codeがコードだけでは推測できない情報を補完します。
## ビジネスコンテキスト
### ドメイン知識
- 「テナント」= 企業顧客アカウント。マルチテナントSaaS。
- 「ワーカー」= バックグラウンドジョブ実行プロセス。Workerではない。
- 価格は全て税抜き。表示時に消費税10%を加算。
### データフロー
1. クライアント → API Gateway → Hono Route
2. Route → Service（ビジネスロジック）
3. Service → Repository（DB操作、Drizzle ORM）
4. 非同期処理 → SQSキュー → Worker Lambda
### 既知の技術的負債
- users テーブルの email カラムにUNIQUE制約がない（移行予定）
- legacy_orders テーブルは読み取り専用（新システムでは orders を使用）
- 認証はJWT v1形式。v2への移行は2026Q3予定パターン3: ワークフロー定義設計
Claude Codeに作業手順を教えるパターンです。特に複雑な開発フローがある場合に効果的です。
## 開発ワークフロー
### 新しいAPIエンドポイントを追加する手順
1. `src/models/` にリクエスト/レスポンスの型定義を作成
2. `src/services/` にビジネスロジックを実装
3. `src/routes/` にルートハンドラを作成
4. `src/routes/index.ts` にルートを登録
5. テストファイルを作成（`*.test.ts`）
6. `bun test` で全テスト通過を確認
### PRを作成する際の注意
- コミットメッセージは Conventional Commits 形式
- PR本文にはJiraチケット番号を含める（例: `PROJ-123`）
- 破壊的変更がある場合は BREAKING CHANGE をコミットメッセージに含める
コンテキストウィンドウの最適化
コンテキストウィンドウの仕組み
Claude Codeのコンテキストウィンドウは、1つのセッション内でAIが「覚えている」情報の総量を制限します。2026年時点でClaude 4 Sonnetは200Kトークン、Claude 4 Opusは200Kトークンのコンテキストウィンドウを持ちます。
しかし、実際に使えるコンテキストは以下のように分配されます。
| 用途 | トークン消費の目安 |
|---|---|
| CLAUDE.md | 500〜3,000トークン |
| 会話履歴 | セッション長に比例して増加 |
| 読み込んだファイル | 1ファイルあたり100〜5,000トークン |
| ツール実行結果 | コマンド出力に依存 |
| AIの応答 | 1回あたり500〜3,000トークン |
長時間のセッションでは会話履歴が蓄積され、コンテキストウィンドウの上限に達すると古い情報が失われます。これを防ぐのが「コンパクション」です。
コンパクション（自動圧縮）の活用
Claude Codeには、コンテキストが上限に近づいたときに自動的に会話を要約・圧縮する「コンパクション」機能があります。
コンテキストコンパクションの詳細で解説していますが、ここでは実践的な活用のポイントを整理します。
# コンパクションを手動で実行
/compact
# 要約のフォーカスを指定してコンパクション
/compact 認証機能の実装に関する部分を重点的に残してコンパクションを効果的に使うためのベストプラクティスは以下のとおりです。
タスクの区切りでコンパクションを実行する
1つの機能実装が完了したら、次のタスクに移る前に /compact を実行します。これにより、不要な試行錯誤の履歴が削除され、重要な決定事項だけが残ります。
コンパクション前にメモを残す
重要な設計判断や決定事項は、コンパクション前に明示的にAIに伝えておきます。
「ここまでの設計判断を整理してからcompactしたい。
1. 認証方式はJWTのRS256を採用した
2. リフレッシュトークンはRedisに保存する方針にした
3. rate limitは /api/auth/* に対して100req/min
これらを覚えた状態でcompactして」コンテキストの効率的な使い方
コンテキストウィンドウを節約するテクニックを紹介します。
1. ファイル読み込みを最小限にする
# ❌ 非効率: ファイル全体を読み込む
「src/services/user.ts を読んで」
# ✅ 効率的: 必要な部分だけを指定
「src/services/user.ts の createUser 関数だけ見て」2. コマンド出力を制限する
大量のログ出力がコンテキストを圧迫します。必要な部分だけを取得しましょう。
# ❌ 非効率: 全ログを出力
npm test 2>&1
# ✅ 効率的: 失敗したテストだけ
npm test 2>&1 | grep -A 5 "FAIL"3. 中間結果をファイルに書き出す
長い分析結果はコンテキストに残さず、ファイルに書き出します。
「分析結果を analysis.md に書き出して。
コンテキストには結論だけ残して」メモリの永続化テクニック
/memory コマンドの活用
Claude Codeの /memory コマンドを使うと、セッションを超えて情報を保持できます。これはCLAUDE.mdに自動追記される仕組みです。
# メモリに追加
/memory 「このプロジェクトではPrettierのセミコロンをfalseに設定している」
# メモリの確認
/memory/memory で保存された情報はCLAUDE.mdのメモリセクションに追記され、次のセッションでも自動的に読み込まれます。ただし、無制限にメモリを追加するとCLAUDE.mdが肥大化するため、定期的な整理が必要です。
Autodreamパターンによる記憶管理
Autodream メモリ管理で紹介されている手法を応用し、構造化されたメモリ管理を実現できます。
## メモリ（自動更新）
### 技術的決定事項
- [2026-03-15] 認証方式: JWT RS256 + Redis セッション管理
- [2026-03-20] キャッシュ戦略: CloudFront + Redis 2層キャッシュ
- [2026-03-25] ログ基盤: CloudWatch Logs → S3 → Athena
### 過去のトラブルと解決策
- [2026-03-18] Drizzle ORMのJOINでN+1問題 → with句で解決
- [2026-03-22] Bunのメモリリーク → v1.2.3で修正済み
### 今後のTODO
- [ ] OpenAPI仕様書の自動生成
- [ ] E2Eテストの追加
- [x] CI/CDパイプラインの構築セッション間の引き継ぎ戦略
長期プロジェクトでは、セッション終了時に次のセッションへの引き継ぎ情報を残すことが重要です。
「今日の作業を要約して CLAUDE.md のメモリセクションに追記して。
含めてほしい情報:
1. 完了したタスク
2. 途中のタスクと進捗
3. 次のセッションでやるべきこと
4. 発見した問題点」この習慣を続けることで、プロジェクトの進行状況がCLAUDE.mdに蓄積され、新しいセッションでもスムーズに作業を再開できます。
チームでのメモリ管理運用
CLAUDE.mdのバージョン管理
CLAUDE.mdはGitで管理し、チーム全員が同じコンテキストを共有するのが基本です。
# CLAUDE.mdをGitに追加
git add CLAUDE.md
git commit -m "docs: CLAUDE.md初期設定を追加"ただし、個人的な好み（エディタ設定、プロンプトスタイル等）は.claude/CLAUDE.local.mdに記述し、.gitignoreに追加します。
# .gitignore
.claude/CLAUDE.local.mdチーム向けCLAUDE.mdテンプレート
新しいプロジェクトで使える汎用テンプレートを用意しておくと、チーム全体の効率が上がります。
# CLAUDE.md
## プロジェクト概要
[プロジェクト名]: [1行説明]
## 技術スタック
- Language:
- Framework:
- Database:
- Test:
- CI/CD:
## ディレクトリ構造
[主要なディレクトリと役割を記載]
## コーディング規約
[チームの規約をリスト化]
## コマンド一覧
- 開発サーバー:
- テスト実行:
- ビルド:
- デプロイ:
## ルール
### 必ず守ること
-
### やってはいけないこと
-
## メモリ
[セッション間で引き継ぐ情報を自動追記]レビューでCLAUDE.mdを更新する文化
コードレビューと同様に、CLAUDE.mdもレビュー・更新の対象にすることが重要です。以下のタイミングでCLAUDE.mdを見直しましょう。
- 新しいライブラリを導入したとき: 技術スタックの更新
- コーディング規約を変更したとき: ルールの更新
- チームで繰り返し同じ指示をしていることに気づいたとき: 暗黙知の明文化
- バグの原因が「AIの理解不足」だったとき: コンテキスト補完の追加
CLAUDE.mdのアンチパターン
アンチパターン1: 情報の詰め込みすぎ
CLAUDE.mdに全ての情報を詰め込むと、コンテキストウィンドウの無駄遣いになります。
# ❌ 悪い例: APIリファレンスを全て記載
## API一覧
### GET /api/users
レスポンス: { id: string, name: string, email: string, ... }
### GET /api/users/:id
...（以下数百行のAPI仕様）代わりに、参照先を示す方が効率的です。
# ✅ 良い例: 参照先を示す
## API仕様
- OpenAPI仕様書: `docs/openapi.yaml`
- 必要に応じて上記ファイルを読み込んでくださいアンチパターン2: 曖昧な記述
# ❌ 悪い例
- なるべくきれいなコードを書く
- テストはちゃんと書く
- パフォーマンスに気をつける# ✅ 良い例
- 関数は30行以内。超える場合は分割する
- 全publicメソッドにユニットテストを書く（カバレッジ80%以上）
- N+1クエリを避ける。JOINまたはバッチ取得を使用するアンチパターン3: 古い情報の放置
CLAUDE.mdにすでに使われていないライブラリや過去の設計判断が残っていると、Claude Codeが混乱します。定期的（月1回程度）にCLAUDE.mdを棚卸しし、陳腐化した情報を削除しましょう。
実践: effortパラメータとメモリ管理の組み合わせ
メモリ管理をeffortパラメータと組み合わせることで、さらなる効率化が可能です。
| 作業 | effort | メモリ活用 |
|---|---|---|
| 定型コード生成 | low | CLAUDE.mdのルールに従い自動生成 |
| 設計検討 | high | メモリに残った過去の設計判断を参照 |
| コードレビュー | medium | プロジェクト規約との整合性チェック |
| リファクタリング | medium→high | 技術的負債の記録を参照して優先度判断 |
CLAUDE.mdが充実していれば、lowやmediumでも高品質な出力が得られます。なぜなら、Claude Codeがプロジェクトの文脈を理解した上でタスクに取り組めるからです。
SES現場での活用シナリオ
シナリオ1: 新規参画時のオンボーディング
SES案件に新規参画する際、プロジェクトのCLAUDE.mdが整備されているとキャッチアップ時間を大幅に短縮できます。
# プロジェクトに参画したら最初にやること
cat CLAUDE.md # プロジェクト概要を把握
claude # Claude Codeを起動
# 「このプロジェクトの全体像を教えて」と聞くだけで
# CLAUDE.mdの情報をもとに詳細な説明が得られるシナリオ2: 複数プロジェクト並行時
SESエンジニアは複数のプロジェクトを同時に担当することがあります。プロジェクトごとにCLAUDE.mdを整備しておけば、コンテキストスイッチのコストが激減します。
# プロジェクトAの作業
cd ~/projects/project-a
claude # CLAUDE.mdが自動読込 → project-aのコンテキスト
# プロジェクトBに切り替え
cd ~/projects/project-b
claude # CLAUDE.mdが自動読込 → project-bのコンテキストシナリオ3: チーム引き継ぎ時
SES案件では担当者が交代することも多いです。CLAUDE.mdに設計判断の経緯が記録されていれば、引き継ぎドキュメントとしても機能します。
まとめ: メモリ管理で実現する持続的な開発効率
Claude Codeのメモリ・コンテキスト管理を適切に設計することで、以下の効果が得られます。
- セッション間の知識断絶がなくなる: 毎回同じ説明をする無駄が消える
- 出力品質が安定する: プロジェクト固有のルールが一貫して適用される
- チーム全体の効率が向上する: 全員が同じコンテキストを共有できる
- コストが削減できる: 少ないeffortでも高品質な出力が可能に
メモリ管理は「一度設定して終わり」ではなく、プロジェクトとともに育てていくものです。日々の開発で得た知見をCLAUDE.mdに反映し続けることで、Claude Codeはますます頼れるペアプログラマーになっていきます。
関連記事
- CLAUDE.md活用ガイド — CLAUDE.mdの基本的な使い方を解説
- コンテキストコンパクション — コンテキスト圧縮の詳細テクニック
- Autodreamメモリ管理 — 記憶の自動化パターン
- プロンプトエンジニアリング — 効果的な指示の出し方
- effortパラメータ最適化 — コスト削減テクニック
- ワークスペース管理 — プロジェクト構成の最適化
