Claude Codeのメモリ・コンテキスト管理｜CLAUDE.md設計からプロジェクト知識の永続化まで

——Claude Codeを複数のセッションにまたがって使っていると、ある問題に直面します。「前のセッションで説明したルール、もう一度言わなきゃいけないのか」。AIとのやり取りはセッション単位でリセットされるため、プロジェクトの文脈やルールを毎回伝え直す必要が生じます。AI活用完全ガイドで、AI活用の全体像を把握できます。

この課題を解決するのが、Claude Codeのメモリ・コンテキスト管理の仕組みです。CLAUDE.md、instructions.md、memory/ディレクトリを適切に設計することで、プロジェクトの知識をセッションを超えて永続化できます。詳しくは「Claude Codeでチーム開発を効率化する方法」で解説しています。

ただし、「すべてをメモリに書き込めばいい」というわけではありません。コンテキストウィンドウには容量の上限があり、不要な情報を読み込みすぎるとAIのパフォーマンスが低下します。何を記憶させ、何を記憶させないかの設計こそが、Claude Codeの生産性を左右する最大のポイントです。詳しくは「Claude Codeの企業導入セキュリティガイド」で解説しています。

本記事では、コンテキスト設計の原則から、メモリの分類体系、大規模プロジェクトでの運用設計まで、実践的なノウハウを体系的に解説します。詳しくは「Claude Code × CI/CD」で解説しています。

関連する記事の一覧はClaude Code実践ガイドをご覧ください。

この記事でわかること

• CLAUDE.md / instructions.md / memory/ の役割の違いと、情報の適切な配置先
• コンテキスト設計の3原則（階層化・分離・参照）と、情報過多を防ぐための設計パターン
• 大規模プロジェクトや複数人開発での、メモリ運用のベストプラクティスと陥りがちな失敗

Claude Codeのコンテキスト階層

Claude Codeには、情報を読み込む階層が複数あります。各階層の読み込みタイミングと目的を正しく理解することが設計の出発点です。

ここが結構ミソなのですが、L1〜L3は「常に読み込まれる」ため、ここに書く情報はコンテキストウィンドウを常に消費するということです。コンテキストウィンドウの容量は有限です。L1〜L3には「セッションの90%で必要になる情報」だけを記述し、特定のタスクでしか使わない情報はL4やL5に分離するのが最適な設計です。

CLAUDE.mdの設計原則

CLAUDE.mdは、Claude Codeがセッション開始時に最初に読むファイルです。プロジェクトの「地図」として機能し、AIがプロジェクト全体を俯瞰するための情報を提供します。

含めるべき情報

含めるべきでない情報

• 特定のタスクの手順: カスタムコマンドに分離
• 変更頻度が高いデータ: メモリに分離
• 大量のコード例: 参照ファイルに分離
• 個人の好み: ユーザーメモリに分離

CLAUDE.mdの構成テンプレート

# プロジェクト名

## 概要
[2〜3行でプロジェクトの目的を説明]

## ディレクトリ構造
[主要フォルダのツリー図と各フォルダの役割]

## 技術スタック
[使用技術の一覧]

## 共通ルール
[全作業に適用される規約・禁止事項]

## ワークフロー
[主要な作業フローの概要]

## 参照先
[詳細ドキュメントへのポインタ]

今枝（StartLink代表）の実体験として、CLAUDE.mdの設計で最も重要なのは「書かないことを決めること」です。情報を詰め込みすぎたCLAUDE.mdは、AIのパフォーマンスを低下させるだけでなく、人間にとっても読みにくいドキュメントになります。

instructions.mdの活用

instructions.mdは、CLAUDE.mdを補完する「詳細な行動指針」です。CLAUDE.mdがプロジェクトの全体像を示すのに対し、instructions.mdは具体的な「こうしてほしい」「こうしてはいけない」を列挙します。

CLAUDE.mdとinstructions.mdの使い分け

instructions.mdに書くべき内容の例:

# 行動指針

## 記事制作ルール
- です/ます調を統一
- テーブルは2つ以上必須
- FAQ は5つ以上、JSON-LD構造化データ付き
- 匿名の「A社」「B社」は絶対禁止
- チェックボックス記法（[ ] [x]）禁止

## コード品質
- TypeScript strict modeを前提にする
- any型の使用は原則禁止
- 関数名はcamelCase、コンポーネントはPascalCase

## API操作
- PATCH後は必ずGETで検証
- 大量API呼び出し（10件以上）はユーザー承認必須
- レート制限: HubSpot API は100リクエスト/10秒

出典: Anthropic公式ドキュメント: Memory and context

memory/ディレクトリの設計

memory/ディレクトリは、セッションをまたいで蓄積されるナレッジベースです。CLAUDE.mdやinstructions.mdが「静的なルール」を定義するのに対し、memoryは「動的に学習した知識」を保存します。

メモリの分類体系

メモリに保存する情報は、以下の4カテゴリに分類できます。

メモリファイルの構成例

~/.claude/projects/{project-hash}/memory/
├── MEMORY.md          ← メインメモリ（要点だけ記載）
├── mistakes.md        ← ミスログ（再発防止台帳）
├── feedback.md        ← ユーザーからの改善要望
├── architecture.md    ← アーキテクチャ決定の記録
└── api_notes.md       ← API仕様の補足メモ

効果的なメモリの書き方

メモリに書く情報は、未来の自分（= 次のセッション）への申し送りメモとして設計します。

良い例:

## HubSpot API注意点
- Blog Posts APIのPATCHでは、slugフィールドを含めると403エラーが返る場合がある
- 対策: slugの変更は個別のAPIコールで実行する
- 確認日: 2026年3月

悪い例:

## メモ
HubSpotのAPIで問題があった。直した。

良いメモリは「何が起きたか」「なぜ起きたか」「どう対処したか」を含んでいます。

大規模プロジェクトでのコンテキスト設計

プロジェクトが大きくなると、CLAUDE.mdが肥大化しがちです。以下の戦略で対処します。

戦略1: ポインタ方式

CLAUDE.mdには概要とポインタだけを記述し、詳細は別ファイルに委譲します。

# プロジェクト概要
[3行で説明]

## 詳細ドキュメント
| 分野 | ファイル |
|------|---------|
| API仕様 | docs/api.md |
| DB設計 | docs/database.md |
| デプロイ | docs/deploy.md |
| コーディング規約 | docs/coding-standards.md |

作業対象のドキュメントを適宜読み込んでください。

戦略2: モジュール別CLAUDE.md

大規模なモノレポでは、サブディレクトリごとにCLAUDE.mdを配置できます。

project/
├── .claude/CLAUDE.md          ← 全体の概要
├── frontend/CLAUDE.md         ← フロントエンド固有のルール
├── backend/CLAUDE.md          ← バックエンド固有のルール
└── docs/CLAUDE.md             ← ドキュメント固有のルール

Claude Codeは、作業対象のディレクトリに近いCLAUDE.mdを優先的に参照します。

戦略3: 動的読み込み

カスタムコマンドの中で、タスクに必要なコンテキストだけを動的に読み込む設計です。

# /deploy-check コマンド

以下のファイルを読み込んでください:
- docs/deploy.md（デプロイ手順）
- .env.example（環境変数一覧）
- package.json（依存関係）

これらの情報に基づいて、デプロイ前の最終チェックを実行してください。

この方法であれば、デプロイ作業のときだけデプロイ関連のドキュメントが読み込まれ、普段の開発セッションではコンテキストウィンドウを消費しません。

詳しいカスタムコマンドの設計パターンは、Claude Codeカスタムコマンドガイドで解説しています。

複数人開発でのメモリ運用

チームでClaude Codeを使う場合、メモリの管理にはいくつかの注意点があります。

共有すべきもの vs 個人で管理するもの

並列作業時の競合回避

複数のClaude Codeエージェントが同時に作業する場合、同じファイルへの書き込み競合が発生するリスクがあります。

対策としては:

• AGENT_SYNC.md: エージェント間の作業状況を記録するファイルを用意し、作業開始時・完了時に更新する
• ファイルロック: 重要なファイル（マスターデータなど）は、作業中であることを明示する
• 担当範囲の分離: エージェントごとに作業対象のディレクトリやファイルを分離する

これはClaude Codeマルチエージェント開発の記事で詳しく解説しています。

コンテキスト最適化のためのチェックリスト

以下の観点で、定期的にコンテキスト設計を見直してください。

CLAUDE.md:

• 200行以内に収まっているか
• 「常に必要な情報」だけが記載されているか
• ポインタ方式で詳細を外部ファイルに分離しているか

instructions.md:

• ルールが具体的で、曖昧な表現がないか
• 矛盾するルールがないか
• 不要になったルールが残っていないか

memory/:

• 「何が起きたか」「どう対処したか」が明記されているか
• 古くなった情報が残っていないか
• ファイルが肥大化していないか（目安: 各ファイル100行以内）

正直な限界と注意点

コンテキストウィンドウの制約

Claude Codeが1セッションで処理できるコンテキスト量には上限があります。CLAUDE.md + instructions.md + memory/ の合計が大きすぎると、実際の作業に使えるコンテキスト領域が圧迫されます。目安として、常時読み込まれるファイルの合計は500行以内に収めることを推奨します。

メモリの信頼性

memoryに記録された情報が古くなっていると、AIが誤った前提で作業を進めるリスクがあります。月1回程度の棚卸しで、古い情報や不正確な記述を削除・更新してください。

プライバシーと機密性

memory/には業務上の判断根拠やAPIの挙動メモが含まれることがあります。チームで共有するリポジトリにmemory/を含める場合は、機密情報が混入していないかを確認してください。

出典: Anthropic セキュリティに関するホワイトペーパー

StartLinkのAI開発環境構築支援

StartLinkでは、CRM運用のためのAI開発環境構築を支援しています。Claude CodeのCLAUDE.md設計、カスタムコマンド整備、HubSpot MCP連携の設定まで、CRMを中心としたAI活用基盤の構築をワンストップで提供します。

「AIツールを導入したが、チーム全体で活用しきれていない」というお悩みがある方は、お気軽にお問い合わせください。

よくある質問（FAQ）

Q1. CLAUDE.mdとREADME.mdの違いは何ですか？

README.mdは人間の開発者向けのドキュメントで、プロジェクトのセットアップ手順や使い方を説明します。CLAUDE.mdはClaude Code（AI）向けのドキュメントで、AIがプロジェクトを理解し適切に作業するための情報を提供します。両方を用意するのが理想的で、それぞれの読み手に最適化した内容を記述してください。

Q2. メモリはどのくらいの頻度で更新すべきですか？

メモリの更新タイミングは主に3つです。(1)新しい技術的な発見やルールが確定したとき、(2)ミスが発生して再発防止策を記録するとき、(3)プロジェクトの方針が変わったとき。日常的な作業の度に更新する必要はありません。「次のセッションで知っておくべきか」を基準に判断してください。

Q3. コンテキストウィンドウの使用量を確認する方法はありますか？

Claude Codeのセッション中に /cost コマンドを実行すると、そのセッションのトークン使用量を確認できます。また、Claude Codeは長いセッションでコンテキストが溢れそうになると自動的に要約（compaction）を行います。頻繁にcompactionが発生する場合は、常時読み込みファイルが大きすぎるサインです。

Q4. 既存プロジェクトにCLAUDE.mdを導入するにはどうすればよいですか？

まず .claude/ ディレクトリを作成し、CLAUDE.mdに以下の最小限の情報を記述することから始めてください。(1)プロジェクトの一言説明、(2)ディレクトリ構造、(3)技術スタック、(4)最も重要なルール3つ。最初から完璧なCLAUDE.mdを作ろうとせず、作業しながら徐々に情報を追加・整理していくアプローチが効果的です。

Q5. CLAUDE.mdの内容がセッション中に反映されないことがあります。原因は？

CLAUDE.mdはセッション開始時に読み込まれるため、セッション中に変更しても即座には反映されません。変更を反映するには、セッションを再起動する（/exit → claude で再起動）か、セッション中に「CLAUDE.mdを再読み込みしてください」と明示的に指示してください。また、CLAUDE.mdが極端に長い場合、一部が省略されることがあります。