——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 Codeには、情報を読み込む階層が複数あります。各階層の読み込みタイミングと目的を正しく理解することが設計の出発点です。
| 階層 | ファイル | 読み込みタイミング | 対象範囲 | 主な用途 |
|---|---|---|---|---|
| L1: プロジェクト | .claude/CLAUDE.md |
セッション開始時に自動 | プロジェクト全体 | アーキテクチャ、ルール、ディレクトリ構造 |
| L2: ユーザー指示 | .claude/instructions.md |
セッション開始時に自動 | プロジェクト全体 | 詳細な行動指針、制約事項 |
| L3: メモリ | ~/.claude/projects/*/memory/ |
セッション開始時に自動 | ユーザー×プロジェクト | 蓄積されたナレッジ、ミスログ、学習 |
| L4: カスタムコマンド | .claude/commands/*.md |
/コマンド名 実行時 |
コマンド単位 | タスク固有のプロンプト |
| L5: 参照ファイル | 任意の .md / .json |
コマンド内で明示指示時 | タスク単位 | 技術仕様、API定義、マッピング |
ここが結構ミソなのですが、L1〜L3は「常に読み込まれる」ため、ここに書く情報はコンテキストウィンドウを常に消費するということです。コンテキストウィンドウの容量は有限です。L1〜L3には「セッションの90%で必要になる情報」だけを記述し、特定のタスクでしか使わない情報はL4やL5に分離するのが最適な設計です。
CLAUDE.mdは、Claude Codeがセッション開始時に最初に読むファイルです。プロジェクトの「地図」として機能し、AIがプロジェクト全体を俯瞰するための情報を提供します。
| カテゴリ | 内容 | 例 |
|---|---|---|
| プロジェクト概要 | 何をするプロジェクトか | 「CRM特化型コンサル企業のブログ500記事管理」 |
| ディレクトリ構造 | 主要フォルダの役割 | src/ → ソースコード、docs/ → ドキュメント |
| 技術スタック | 使用している技術 | Next.js / TypeScript / Supabase / Vercel |
| 共通ルール | 全作業に適用される規約 | 命名規則、コーディング規約、禁止事項 |
| 仕様書へのポインタ | 詳細情報の参照先 | 「API仕様は docs/api.md を参照」 |
# プロジェクト名
## 概要
[2〜3行でプロジェクトの目的を説明]
## ディレクトリ構造
[主要フォルダのツリー図と各フォルダの役割]
## 技術スタック
[使用技術の一覧]
## 共通ルール
[全作業に適用される規約・禁止事項]
## ワークフロー
[主要な作業フローの概要]
## 参照先
[詳細ドキュメントへのポインタ]今枝（StartLink代表）の実体験として、CLAUDE.mdの設計で最も重要なのは「書かないことを決めること」です。情報を詰め込みすぎたCLAUDE.mdは、AIのパフォーマンスを低下させるだけでなく、人間にとっても読みにくいドキュメントになります。
instructions.mdは、CLAUDE.mdを補完する「詳細な行動指針」です。CLAUDE.mdがプロジェクトの全体像を示すのに対し、instructions.mdは具体的な「こうしてほしい」「こうしてはいけない」を列挙します。
| 観点 | CLAUDE.md | instructions.md |
|---|---|---|
| 目的 | プロジェクトの地図 | 行動の制約ルール |
| 粒度 | 概要レベル | 具体的・詳細 |
| 更新頻度 | 月1回程度 | 週1回程度 |
| 誰が書くか | プロジェクトリーダー | 作業者本人 |
| 配置場所 | .claude/CLAUDE.md |
.claude/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/ディレクトリは、セッションをまたいで蓄積されるナレッジベースです。CLAUDE.mdやinstructions.mdが「静的なルール」を定義するのに対し、memoryは「動的に学習した知識」を保存します。
メモリに保存する情報は、以下の4カテゴリに分類できます。
| カテゴリ | 内容 | 例 | 更新頻度 |
|---|---|---|---|
| Project | プロジェクト固有の知識 | アーキテクチャの決定事項、技術選定の理由 | 月数回 |
| User | 個人の好み・設定 | 出力フォーマットの好み、コードスタイル | 数ヶ月に1回 |
| Feedback | フィードバックの記録 | 修正依頼の内容、改善点 | 都度 |
| Reference | 参照データ | API仕様、マッピングテーブル | 変更時 |
~/.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が肥大化しがちです。以下の戦略で対処します。
CLAUDE.mdには概要とポインタだけを記述し、詳細は別ファイルに委譲します。
# プロジェクト概要
[3行で説明]
## 詳細ドキュメント
| 分野 | ファイル |
|------|---------|
| API仕様 | docs/api.md |
| DB設計 | docs/database.md |
| デプロイ | docs/deploy.md |
| コーディング規約 | docs/coding-standards.md |
作業対象のドキュメントを適宜読み込んでください。大規模なモノレポでは、サブディレクトリごとにCLAUDE.mdを配置できます。
project/
├── .claude/CLAUDE.md ← 全体の概要
├── frontend/CLAUDE.md ← フロントエンド固有のルール
├── backend/CLAUDE.md ← バックエンド固有のルール
└── docs/CLAUDE.md ← ドキュメント固有のルールClaude Codeは、作業対象のディレクトリに近いCLAUDE.mdを優先的に参照します。
カスタムコマンドの中で、タスクに必要なコンテキストだけを動的に読み込む設計です。
# /deploy-check コマンド
以下のファイルを読み込んでください:
- docs/deploy.md（デプロイ手順）
- .env.example（環境変数一覧）
- package.json（依存関係）
これらの情報に基づいて、デプロイ前の最終チェックを実行してください。この方法であれば、デプロイ作業のときだけデプロイ関連のドキュメントが読み込まれ、普段の開発セッションではコンテキストウィンドウを消費しません。
詳しいカスタムコマンドの設計パターンは、Claude Codeカスタムコマンドガイドで解説しています。
チームでClaude Codeを使う場合、メモリの管理にはいくつかの注意点があります。
| 情報 | 管理場所 | 理由 |
|---|---|---|
| コーディング規約 | .claude/CLAUDE.md（Git共有） |
チーム全員が同じルールに従うべき |
| アーキテクチャ決定 | .claude/CLAUDE.md（Git共有） |
プロジェクトの知識として共有 |
| 個人のミスログ | memory/mistakes.md（個人） |
個人の学習記録 |
| 出力フォーマットの好み | memory/（個人） |
個人の好み |
| API仕様の補足 | docs/（Git共有） |
チーム全員が参照する |
複数のClaude Codeエージェントが同時に作業する場合、同じファイルへの書き込み競合が発生するリスクがあります。
対策としては:
これはClaude Codeマルチエージェント開発の記事で詳しく解説しています。
以下の観点で、定期的にコンテキスト設計を見直してください。
CLAUDE.md:
instructions.md:
memory/:
Claude Codeが1セッションで処理できるコンテキスト量には上限があります。CLAUDE.md + instructions.md + memory/ の合計が大きすぎると、実際の作業に使えるコンテキスト領域が圧迫されます。目安として、常時読み込まれるファイルの合計は500行以内に収めることを推奨します。
memoryに記録された情報が古くなっていると、AIが誤った前提で作業を進めるリスクがあります。月1回程度の棚卸しで、古い情報や不正確な記述を削除・更新してください。
memory/には業務上の判断根拠やAPIの挙動メモが含まれることがあります。チームで共有するリポジトリにmemory/を含める場合は、機密情報が混入していないかを確認してください。
出典: Anthropic セキュリティに関するホワイトペーパー
StartLinkでは、CRM運用のためのAI開発環境構築を支援しています。Claude CodeのCLAUDE.md設計、カスタムコマンド整備、HubSpot MCP連携の設定まで、CRMを中心としたAI活用基盤の構築をワンストップで提供します。
「AIツールを導入したが、チーム全体で活用しきれていない」というお悩みがある方は、お気軽にお問い合わせください。
README.mdは人間の開発者向けのドキュメントで、プロジェクトのセットアップ手順や使い方を説明します。CLAUDE.mdはClaude Code（AI）向けのドキュメントで、AIがプロジェクトを理解し適切に作業するための情報を提供します。両方を用意するのが理想的で、それぞれの読み手に最適化した内容を記述してください。
メモリの更新タイミングは主に3つです。(1)新しい技術的な発見やルールが確定したとき、(2)ミスが発生して再発防止策を記録するとき、(3)プロジェクトの方針が変わったとき。日常的な作業の度に更新する必要はありません。「次のセッションで知っておくべきか」を基準に判断してください。
Claude Codeのセッション中に /cost コマンドを実行すると、そのセッションのトークン使用量を確認できます。また、Claude Codeは長いセッションでコンテキストが溢れそうになると自動的に要約（compaction）を行います。頻繁にcompactionが発生する場合は、常時読み込みファイルが大きすぎるサインです。
まず .claude/ ディレクトリを作成し、CLAUDE.mdに以下の最小限の情報を記述することから始めてください。(1)プロジェクトの一言説明、(2)ディレクトリ構造、(3)技術スタック、(4)最も重要なルール3つ。最初から完璧なCLAUDE.mdを作ろうとせず、作業しながら徐々に情報を追加・整理していくアプローチが効果的です。
CLAUDE.mdはセッション開始時に読み込まれるため、セッション中に変更しても即座には反映されません。変更を反映するには、セッションを再起動する（/exit → claude で再起動）か、セッション中に「CLAUDE.mdを再読み込みしてください」と明示的に指示してください。また、CLAUDE.mdが極端に長い場合、一部が省略されることがあります。