Claude CodeのMEMORY.mdは「索引」として設計せよ──コンテキスト効率を最大化する3つの原則
出典: ojt
Claude CodeのMEMORY.mdを「全部覚える場所」として使うと、コンテキスト消費が肥大化し効率が低下します。索引として設計し直すことで、個別メモリが何十本に増えても、コンテキスト圧を抑えたまま運用できる実践的な手法を解説します。
Claude Codeのメモリ機能、使いこなせていますか?
Claude Codeのメモリ機能を導入した多くの開発者が、初期段階で共通の落とし穴にはまります。それは「MEMORY.mdにすべての情報を書き込めばAIが賢くなる」という誤解です。
実際には、MEMORY.mdの肥大化は毎回の会話で消費するトークン数を線形に増加させ、コスト増とパフォーマンス低下を招きます。この問題を解決する鍵は、MEMORY.mdの役割を根本から見直すことにあります。
MEMORY.mdは「索引」である──設計思想の転換
なぜ肥大化が問題なのか
Claude CodeのMEMORY.mdは、会話のたびに全文が読み込まれる仕組みです。つまり、このファイルに100行書けば、毎回100行分のトークンを消費します。情報を追加するほど、基本コストが積み上がっていく構造なのです。
従来のナレッジベース的な発想で「詳細に書けば書くほど良い」と考えると、すぐにコンテキストウィンドウを圧迫してしまいます。
索引としての設計パターン
正しいアプローチは、MEMORY.mdを**「どこに何があるかを示す地図」**として機能させることです。具体的には:
この設計により、個別メモリが10本でも50本でも、MEMORY.md自体のサイズは抑えられ、基本的なコンテキスト消費は一定に保たれます。
効率を最大化する3つの実装原則
1. 1行150文字以内の厳格なルール
各エントリは**150文字以内**に収めることが重要です。これは単なる目安ではなく、実装上の制約として機能させるべきです。
**良い例:**
- `docs/api-design.md`: REST API設計ガイドライン（認証方式、エラーハンドリング、バージョニング戦略）**悪い例:**
- APIの設計について: 認証にはJWTトークンを使用し、リフレッシュトークンの有効期限は7日間、アクセストークンは1時間とする。エラーコードは...詳細は個別ファイルに書き、MEMORY.mdには「何について書かれているか」だけを記載します。
2. 読み込み順序の戦略的設計
MEMORY.mdのエントリは、**アクセス頻度の高い順**に配置します。AIは上から順に読み込むため、よく使う情報を上位に置くことで:
具体的には、プロジェクト全体に関わる情報を上位に、特定機能に関する情報を下位に配置する階層構造が効果的です。
3. キャッシュを壊さない更新テクニック
Claude APIはプロンプトキャッシングを活用しています。MEMORY.mdの一部を変更すると、キャッシュが無効化され、次回の会話で全文を再読込する必要が生じます。
キャッシュを温存するためには:
この戦略により、日常的な更新でキャッシュの恩恵を最大限受けられます。
編集部の視点
ChatGPTのカスタム指示との比較
ChatGPTのカスタム指示機能も、毎回読み込まれるという点でMEMORY.mdと似た特性を持ちます。しかし、決定的な違いがあります。
ChatGPTのカスタム指示は**固定長で上限がある**ため、肥大化の問題は構造的に発生しにくい設計です。一方、Claude CodeのMEMORY.mdは**ユーザーが自由に編集できる**ため、意図的に設計しないと際限なく膨らみます。
この自由度の高さは、適切に活用すれば強力な武器になります。プロジェクトごとに最適化された索引構造を構築できるからです。しかし、設計原則を理解せずに使うと、自由度が仇となってコストとパフォーマンスの両面で損失を被ります。
メリットと注意点の両面分析
**メリット:**
**注意点:**
特に注意すべきは、**「索引の索引」を作らないこと**です。階層が深くなりすぎると、かえって情報へのアクセスが複雑化します。2階層（MEMORY.md → 個別ファイル）を基本とし、3階層までに留めるべきです。
どんな人・場面に向いているか
この手法が特に効果を発揮するのは:
逆に、個人の短期的な実験や、情報量が限られる小規模プロジェクトでは、シンプルにMEMORY.md一本で管理する方が効率的な場合もあります。設計の複雑さとプロジェクトの規模をバランスさせることが重要です。
今日から試せるアクション
アクション1: 既存MEMORY.mdの監査
現在のMEMORY.mdを開き、以下をチェックしてください:
1. 150文字を超えるエントリをハイライトする
2. 「詳細情報」が直接書かれているエントリを抽出する
3. これらを個別ファイルに分割し、MEMORY.mdには参照のみを残す
この作業だけで、トークン消費を30〜50%削減できるケースが多くあります。
アクション2: 索引テンプレートの作成
新規プロジェクト用に、以下のようなテンプレートを作成しましょう:
# MEMORY.md - Project Index
## Core Architecture
- `docs/architecture.md`: システム全体構成
- `docs/data-flow.md`: データフロー設計
## Development Guidelines
- `docs/coding-standards.md`: コーディング規約
- `docs/git-workflow.md`: Git運用ルール
## Domain Knowledge
- `docs/business-logic/`: ビジネスロジック詳細このテンプレートを起点に、プロジェクトに応じてカスタマイズしていきます。
アクション3: 週次レビューの習慣化
毎週金曜日など、定期的にMEMORY.mdをレビューする時間を設けます:
この習慣により、MEMORY.mdは常に最適化された状態を保てます。
---
この情報は @ojt さんの投稿を参考にしています。
出典: ojt
