Claude Codeのメモリ完全解説：3階層設計とAuto-Memory実装ガイド

Claude Codeのメモリは、開発者が明示的に記述するCLAUDE.md（リポジトリ直下やホームディレクトリに置く指示ファイル）と、セッション中の会話から重要事項を自動で保存するAuto-Memory（自動記憶機能）の2系統で構成されます。CLAUDE.mdはuser・project・localなど複数のスコープに分けて管理でき、Auto-Memoryは索引のMEMORY.mdの先頭200行（または25KB）だけが毎回読み込まれ、詳しい内容は別のファイルに分けて保存されます。両者の役割分担を理解せずに使うと、指示が反映されない・過去の会話が意図せず参照されるといった混乱が起きやすいです。

この記事は、クリスタルメソッドがClaude Codeを1年以上にわたり実運用してきた経験をもとに書いています。当初20原則から始まったCLAUDE.mdの運用ルールは、同じ間違いを繰り返す・ツール呼び出しの記法が崩れるといった具体的な失敗が起きるたびに追記され、現在は50項目を超える規模まで育ちました。ファイルが肥大化すると、AIが過去に指摘された内容を読み飛ばし同じミスを再発させる問題に直面したため、編集前のファイルを自動で退避させるPreToolUse Hookを導入し、変更内容を追跡しながらデグレを防ぐ運用に切り替えた経緯があります。

以下では、CLAUDE.mdとAuto-Memoryそれぞれの仕組み・スコープ設計・実装パターンを解説したうえで、こうした実運用で見えてきた知見にも触れます。手順の章には、2026年10月12日にClaude Code 2.1.296で実際に操作した画面と録画を入れています。

Claude Codeはセッションをまたいだ記憶をどのように実現しているのか。公式ドキュメント（code.claude.com）によれば、その答えは「開発者が書くCLAUDE.mdファイル」と「Claudeが自ら書き込むAuto-Memory」という2つの補完的な仕組みに集約されます。本記事では両機構の設計原則・運用上の注意点・チーム導入のポイントを、一次情報に基づいて体系的に解説します。

Claude Codeのメモリ（CLAUDE.md）はどう使う？

Claude Codeは会話をまたいで指示や前提を覚えるために、CLAUDE.mdというファイルを起動時に自動で読み込みます。ここにコーディング規約・使ってほしいコマンド・プロジェクトの背景を書いておくと、毎回説明し直さなくても文脈に入った状態で作業を始められます。置き場所は階層になっていて、上位ほど広く効きます。

• プロジェクト共有： リポジトリ直下の ./CLAUDE.md。チーム全員（そのリポジトリで起動した全員）に効きます。規約や標準手順はここへ。
• ユーザー個人： ~/.claude/CLAUDE.md。自分の全プロジェクトに共通で効きます。好みの言語・口調などはここへ。
• 会話中に追記する： 「これをCLAUDE.mdに追加して」とClaudeに頼むと、その内容をCLAUDE.mdに書き足せます。「今後はnpmではなくpnpmを使って」のように「覚えておいて」と頼んだ場合は、自動メモリ（Auto-Memory）のほうに保存されます。
• 肥大化に注意： 何でも書くと毎回のトークン消費が増え、優先順位も曖昧になります。効く指示に絞り、関連ファイルは @ で参照読み込みするのが実務的です。

どのCLAUDE.mdが使われているかは、入力欄で /memory と打つと確認・編集できます。2026年9月29日に確認した画面（Claude Code v2.1.284）では、「Auto-memory」のオン／オフ、「User instructions（~/.claude/CLAUDE.md に保存）」と「Project instructions（./CLAUDE.md に保存）」の選択肢、自動メモリのフォルダを開く項目が並び、選んでEnterを押すとそのファイルを編集できました。

CLAUDE.mdがまだ無いフォルダでは、入力欄で /init と打つと、Claude Codeがフォルダの中身を調べて最初の版を作ってくれます。祝日のCSVと集計スクリプトだけを置いた練習用のフォルダで実行したところ、実行方法やデータの文字コードなどをまとめた25行のCLAUDE.mdができました。できたファイルは、読んで違うところを直してから使います。

関連記事Claude CodeとObsidianを連携するには？ ／ Claude CodeでMCPを設定するには？ ／ Claude Codeのhooksの設定方法は？

Claude Codeのメモリとは何か：ステートレスLLMの制約を超える設計

LLMは本来ステートレスであり、セッションをまたいだ記憶を構造上持ちません。Claude Codeの公式ドキュメント（code.claude.com/docs/en/memory.md）は冒頭でこの制約を明確に認めたうえで、「各セッションは新鮮なコンテキストウィンドウで始まる（Each Claude Code session begins with a fresh context window）」と述べ、それを補う2つの機構を定義しています。

• CLAUDE.mdファイル：開発者が記述する永続的な指示書。技術スタック・規約・アーキテクチャ方針を記録します
• Auto-Memory：Claudeが修正や指摘をもとに自ら書き込むノート。あなたの好み・伝えた修正・コードやgitの履歴からは分からないプロジェクトの事情などを蓄積します（コードから読み取れる設計やファイルの場所は保存しません）

公式ドキュメントは、両システムはすべての会話開始時にロードされると説明しています。ただし重要な留保として、「Claudeはこれらをコンテキストとして扱うものであり、強制的な設定ではない（Claude treats them as context, not enforced configuration）」と明記されています。特定のアクションを問答無用でブロックしたい場合は、PreToolUseフックを使う必要があります。

インストールと初期設定については Claude Codeインストール完全ガイド を、ツール全体の概念整理には Claude Codeとは を参照してください。

CLAUDE.mdファイルの2系統とAuto-Memoryの比較

公式ドキュメントは、CLAUDE.mdとAuto-Memoryを以下のように対比して説明しています（code.claude.com/docs/en/memory.md）。

	CLAUDE.mdファイル	Auto-Memory
書き手	開発者（あなた）	Claude自身
内容	指示とルール	発見した知見とパターン
スコープ	プロジェクト・ユーザー・組織	リポジトリ単位（ワークツリー間で共有）
ロード方式	毎セッション	毎セッション（先頭200行または25KB）
用途	コーディング規約・ワークフロー・プロジェクト構造	あなたの好み・あなたがClaudeに伝えた修正・コードからは読み取れないプロジェクトの事情

Auto-Memoryのロード量が「先頭200行または25KB」に制限されている点は、コンテキスト管理の観点から重要です。コンテキストウィンドウの可視化シミュレーターでも、Auto-Memory（MEMORY.md）のロードトークンが示されており（code.claude.com/docs/en/context-window.md）、蓄積が進むほどこの上限が実質的な制約として機能し始めます。

公式ドキュメントはさらに「指示が具体的・簡潔であるほど、Claudeはより一貫して従う（The more specific and concise your instructions, the more consistently Claude follows them）」と明言しています。CLAUDE.mdを充実させれば回答品質が上がるという単純な話ではなく、記述の質と量のバランスが求められます。

CLAUDE.mdファイルの3つのスコープ：user / project / local

公式ドキュメントによれば、CLAUDE.mdファイルは配置場所によってスコープが異なります。コンテキストウィンドウのシミュレーターも~/.claude/CLAUDE.md（ユーザーグローバル設定）が起動時に自動ロードされることを示しています（code.claude.com/docs/en/context-window.md）。実運用上の3つのスコープを以下に整理します。

スコープ	ファイルパス	適用範囲	主な記述内容	gitコミット
User（ユーザー）	~/.claude/CLAUDE.md	全プロジェクト共通	個人の開発スタイル・言語設定・好みのコメント形式	しない（個人設定）
Project（プロジェクト）	{root}/CLAUDE.md	プロジェクト全体	技術スタック・コーディング規約・チームルール・アーキテクチャ方針	する（チーム共有推奨）
Local（ローカル）	{root}/CLAUDE.local.md	個人×プロジェクト固有	ローカル環境固有の設定・一時的な作業メモ・個人的なオーバーライド	しない（.gitignore推奨）

公式ドキュメントはさらに、.claude/rules/ディレクトリを使って特定のファイルタイプへのルール適用を細粒度で管理する方法も提供しています（code.claude.com/docs/en/memory.md）。大規模プロジェクトでCLAUDE.mdが肥大化した場合は、このディレクトリ構造による分割が有効な選択肢となります。

ファイルが読み込まれる順番と範囲

上の3つに加えて、会社の管理者が全員に配る「管理ポリシー」のCLAUDE.md（macOSは /Library/Application Support/ClaudeCode/CLAUDE.md、LinuxとWSLは /etc/claude-code/CLAUDE.md）があります。プロジェクトのCLAUDE.mdは、リポジトリ直下の ./CLAUDE.md のほか ./.claude/CLAUDE.md に置くこともできます（code.claude.com/docs/en/memory.md・2026年10月10日確認）。

• 起動時に読まれるもの：作業ディレクトリと、その上の階層すべてにあるCLAUDE.mdとCLAUDE.local.md。foo/bar/ で起動すると、foo/bar/CLAUDE.md と foo/CLAUDE.md の両方が読まれます。
• 必要になってから読まれるもの：作業ディレクトリより下のサブディレクトリにあるCLAUDE.md。Claudeがそのフォルダのファイルを読み書きしたときに読み込まれます。
• 上書きではなく連結：見つかったファイルは、どれかが優先されて他が無視されるのではなく、すべてつなげてコンテキストに入ります。内容が食い違う指示があると、Claudeがどちらかを任意に選ぶことがあります。
• 大きさの目安：1ファイル200行未満が目安です。長いほどコンテキストを消費し、守られにくくなります。4MiBを超えるファイルは読み込まれません。
• ほかのファイルの取り込み：CLAUDE.mdの中に @パス と書くと、そのファイルの内容を取り込めます。

AGENTS.mdも読み込まれる

ほかのコーディングエージェント向けに AGENTS.md を置いているリポジトリでは、Claude Code v2.1.277以降、CLAUDE.mdを追加しなくてもAGENTS.mdがプロジェクトの指示として読み込まれます。ただし条件があります。

個人用のCLAUDE.local.mdを1つ置いただけでも、AGENTS.mdは読まれなくなる点に注意が必要です。両方を読ませたいときは、/config の「Project instructions」の設定を変えるか、CLAUDE.mdからAGENTS.mdを取り込みます。読み込まれたかどうかは /memory の一覧で確認できます。

パス指定ルール：特定のファイルを触ったときだけ読み込む

CLAUDE.mdが長くなってきたら、.claude/rules/ に1テーマ1ファイルで分けるのが公式の勧める方法です。ルールのファイルの先頭に paths を書くと、そのパターンに一致するファイルをClaudeが読み書きしたときだけ読み込まれます。paths を書かないルールは、CLAUDE.mdと同じく起動時にすべて読み込まれます（code.claude.com/docs/en/memory.md）。

---
paths:
  - "src/api/**/*.ts"
---

# API開発のルール
- すべてのエンドポイントで入力値を検証する
- エラーは共通の形式で返す

練習用のフォルダにこのルール（.claude/rules/api.md）を置き、src/api/users.ts を読ませたところ、読み込みの直後に「Loaded .claude/rules/api.md」と表示されました。該当しないファイルを触るだけでは読み込まれないので、常時読み込まれる分のコンテキストを減らせます。

個人用のルールは ~/.claude/rules/ に置くと、自分のすべてのプロジェクトで使えます。ほかのプロジェクトと共有したいルールは、シンボリックリンクで .claude/rules/ に取り込めます。なお、毎回は要らない手順（複数ステップの作業など）はルールではなくスキルに分けるのが公式の整理です。

@で別ファイルを取り込む・コメントでメモを残す

CLAUDE.mdの中に @docs/git-instructions.md のように書くと、そのファイルの内容が起動時に一緒に読み込まれます。相対パスは、取り込むファイルを書いたCLAUDE.mdから見た場所です。取り込んだファイルがさらに別のファイルを取り込む入れ子は、4段までです。パスをそのまま文章に書きたいだけのときは、バッククォートで囲むと取り込まれません（code.claude.com/docs/en/memory.md）。

注意点として、取り込みは「整理のため」の機能で、コンテキストの消費は減りません。取り込んだファイルも起動時に読み込まれるためです。消費を減らしたいときは、前の項目のパス指定ルールを使います。ホームフォルダなど作業フォルダの外のファイルを取り込む場合、最初に確認のダイアログが出ます。

また、CLAUDE.mdの中の <!-- ... --> 形式のHTMLコメント（コードブロックの外のもの）は、Claudeに渡される前に取り除かれます。人間の管理者向けのメモを、トークンを使わずに残せます。

モノレポで関係ないCLAUDE.mdを除外する・別フォルダのCLAUDE.mdを読む

大きなリポジトリでは、上の階層にある他チームのCLAUDE.mdまで読み込まれることがあります。設定の claudeMdExcludes にパスまたはパターンを書くと、それらを読み飛ばせます（個人だけの設定にするなら .claude/settings.local.json）。会社の管理ポリシーのCLAUDE.mdは除外できません。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md"
  ]
}

反対に、--add-dir で追加したフォルダのCLAUDE.mdは、既定では読み込まれません。読ませたいときは、環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を付けて起動します（code.claude.com/docs/en/memory.md）。

/doctor prompt-audit で古い指示・食い違いを点検する

Claude Code v2.1.283以降では、セッション中に /doctor prompt-audit を実行すると、CLAUDE.md・CLAUDE.local.md・AGENTS.mdと、.claude/ 以下のルールやスキルなどを点検できます。古いモデル向けに書かれた指示、存在しないファイルやコマンドへの参照、互いに食い違う指示を探して、修正案つきの報告を出します。ファイルは、あなたが適用を頼むまで変更されません。CLAUDE.mdを足し続けて重くなったときの棚卸しに使えます。

CLAUDE.mdの実効的な記述パターン

CLAUDE.mdに記述すべき内容は「セッションをまたいでもClaudeに一貫して知っておいてほしい情報」に絞るのが原則です。以下は実際の運用で有効な構成例です。

# Project Memory: my-api-service

## 技術スタック
- Runtime: Node.js 22 / TypeScript 5.4
- DB: PostgreSQL 16（接続先は DATABASE_URL 環境変数）
- テストフレームワーク: Vitest 2.x

## コーディング規約
- 関数は純粋関数を優先し、副作用はモジュール境界に閉じ込める
- エラーハンドリングは Result 型で統一（throw は原則禁止）
- コミットメッセージ: Conventional Commits 形式

## アーキテクチャ制約
- src/domain/ 配下はフレームワーク非依存を維持すること
- 外部 API 呼び出しは src/infrastructure/ にのみ配置すること

## 既知の注意点
- PostgreSQL の接続プールは最大 20 を上限とすること（本番環境の制約）
- E2E テストは CI 環境でのみ実行すること（ローカルでは skip）

公式ドキュメントが強調する「具体的・簡潔な記述が一貫性を高める」という原則に従えば、上記のように箇条書きで要点を絞った記述が理想的です。冗長な説明文はCLAUDE.md自体がコンテキストウィンドウを圧迫するという逆効果を招きます。

チームでのCLAUDE.md管理フロー

チーム開発においては、CLAUDE.mdをコードと同様にプルリクエストでレビューする運用が安定しています。変更の意図が不明なまま蓄積すると、メモリの内容が実態と乖離し、Claudeの回答品質が逆に低下するリスクがあります。CLAUDE.local.mdは初期設定時に.gitignoreへ追加し、個人設定の誤コミットを防ぐことが必須です。

Auto-Memoryの仕組みと制御

Auto-Memoryは、Claudeがユーザーの修正や指摘をもとに自動でノートを書き込み、次回以降のセッションで再利用する機能です。公式ドキュメントは「CLAUDE.mdファイルを使うのはClaudeの挙動を導きたいとき。Auto-Memoryはあなたの修正からClaudeが手動の手間なしに学ぶためのものだ（Auto memory lets Claude learn from your corrections without manual effort）」と説明しています（code.claude.com/docs/en/memory.md）。

コンテキストウィンドウのシミュレーターによれば、Auto-Memory（MEMORY.md）には以下の特性があります（code.claude.com/docs/en/context-window.md）。

• セッション開始時に自動ロードされる（hidden、つまりユーザーには直接見えない形で読み込まれます）
• ロードされるのは先頭200行または25KBのいずれか先に達した方まで
• 保存されるメモは4種類：user（あなたの役割・得意分野・仕事の進め方の好み）、feedback（あなたが伝えた修正や、認めたやり方）、project（進行中の作業・期限・決定事項など、コードやgitの履歴からは分からないこと）、reference（課題管理ツールやダッシュボードなど、プロジェクトの外にある情報の場所）。設計やファイルの場所のようにコードを見れば分かることや、CLAUDE.mdにすでに書いてあることは保存されません
• スコープはリポジトリ単位で、ワークツリー間で共有されます

また公式ドキュメントは、サブエージェントも独自のAuto-Memoryを維持できることに言及しています（code.claude.com/docs/en/agent-sdk/subagents.md参照）。サブエージェントの詳細設定についてはサブエージェント設定ページを参照してください。

保存される場所とファイルの構成

自動メモリは、プロジェクトごとに ~/.claude/projects/<プロジェクト>/memory/ に保存されます。同じgitリポジトリのワークツリーやサブディレクトリは、1つのフォルダを共有します。中身は、索引の MEMORY.md と、メモ1件ごとのファイルです（code.claude.com/docs/en/memory.md）。

~/.claude/projects/<プロジェクト>/memory/
├── MEMORY.md           # 索引。1件につき1行。毎セッション読み込まれる
├── user_role.md        # メモ1件
├── feedback_testing.md # メモ1件
└── ...

セッションの開始時に読み込まれるのは MEMORY.md だけで、個別のファイルはClaudeが必要なときに読みます。保存先はそのパソコンの中だけで、別のパソコンやクラウド環境とは共有されません。画面に「Saved 2 memories」「Recalled 2 memories」のように表示されたときは、Claudeがこのフォルダに書き込んだり、読み出したりしています。

実際に、練習用のフォルダで「このフォルダでは、日付は 2026/1/1 の形で書いてください。覚えておいて」と頼みました。画面には「Read 1 file, recalled 1 memory, wrote 2 memories」と表示され、Claudeは「次回以降のセッションでも適用されます」と答えました。

終了してからフォルダを見ると、索引の MEMORY.md と、メモ1件ごとのファイルが保存されていました。MEMORY.md には、メモの題と要点が1件につき1行で並んでいます。

オン／オフの切り替え方

自動メモリは、手元のパソコンでのセッションでは最初からオンです。切り替える方法は3つあります。

上は2026年10月12日に確認した /memory の画面です。「Auto-memory true」がオンの状態で、その下に「Project instructions（./CLAUDE.md）」「User instructions（~/.claude/CLAUDE.md）」「Open auto-memory folder」が並びます。

• /memory で切り替える：セッション中に /memory を開き、Auto-memory の項目で切り替えます。設定 autoMemoryEnabled がユーザー設定（~/.claude/settings.json）に保存されます。
• 特定のプロジェクトだけオフにする：そのプロジェクトの設定ファイルに "autoMemoryEnabled": false を書きます。
• 環境変数でオフにする：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を設定します。

保存先を変えたい場合は、設定の autoMemoryDirectory に絶対パスか ~/ で始まるパスを指定します。

Auto-Memoryの運用上のリスクと対処

Auto-Memoryには明確な利点がある一方、蓄積された情報が陳腐化するリスクを内包しています。過去のアーキテクチャ決定や一時的な対処法が書き込まれ、その後もClaudeに参照され続ける状況は、回答品質の静かな劣化を招きます。具体的なリスクを列挙します。

• 廃止されたAPIエンドポイントや削除済みファイルへの参照が残存します
• 一時的なワークアラウンドが恒久的な制約として記述されます
• 蓄積が進むとAuto-Memoryの先頭200行・25KBという上限が実質的な制約として機能し始め、後から追加された重要な知見がロードされなくなります

対処としては、スプリント単位などの定期的なメモリファイルのレビューサイクルを設けることが実運用上の要件となります。保存された内容はただのMarkdownファイルなので、/memory から自動メモリのフォルダを開いて、いつでも編集・削除できます。自動メモリそのものを止めたい場合は、上の「オン／オフの切り替え方」の方法を使います。

スラッシュコマンドを活用したセッション制御の詳細は Claude Codeスラッシュコマンド一覧 を参照してください。

コンテキストウィンドウとメモリの関係：枯渇を防ぐ実装パターン

「Claude Codeのメモリ不足」として体感される現象の多くは、Claudeモデル自体のRAMの問題ではなく、コンテキストウィンドウの消費超過として発生します。公式のコンテキストウィンドウシミュレーター（code.claude.com/docs/en/context-window.md）は、セッション起動時に何がどれだけトークンを消費するかを明示しています。起動時の主要ロード項目を以下に示します。

• システムプロンプト：動作・ツール使用・応答フォーマットのコア指示。常に最初にロードされます
• Auto-Memory（MEMORY.md）：前セッションからのノート。先頭200行または25KB
• 環境情報：作業ディレクトリ・プラットフォーム・シェル・OSバージョン・gitの状態
• MCPツール：デフォルトでは名前のみリスト化し、スキーマは遅延ロード（ENABLE_TOOL_SEARCH=autoでコンテキストの10%以内に収まる場合は起動時ロードに切り替え可能）
• CLAUDE.md（ユーザーグローバル）：~/.claude/CLAUDE.mdの内容

これらの起動時コストに加え、ファイル読み込みやツール呼び出しのたびにトークンが積み上がっていきます。長時間セッション・モノレポ規模のプロジェクト・複数ツールの並行呼び出しが重なると、利用可能なトークン残量が急速に減少します。コスト・利用量の管理については Claude Code料金・プラン比較 および Claude Code APIの料金体系 を参照してください。

パターン1：CLAUDE.mdの分割管理（チャンク化）

大規模プロジェクトでは、単一のCLAUDE.mdにすべての情報を詰め込むと、ファイル自体がコンテキストを大量消費します。公式ドキュメントが提供する.claude/rules/ディレクトリ機能を活用して役割別にファイルを分割し、作業内容に応じて必要な文脈のみをロードする運用が有効です（code.claude.com/docs/en/memory.md）。

プロジェクトルート/
├── CLAUDE.md              # 全体方針・技術スタック・基本規約
├── .claude/
│   └── rules/
│       ├── api.md         # API設計・エンドポイント仕様・認証方式
│       ├── database.md    # DBスキーマ・マイグレーション方針
│       └── testing.md     # テスト戦略・カバレッジ要件・モック方針
└── CLAUDE.local.md        # 個人環境設定（.gitignore登録済み）

パターン2：セッション境界の意図的な設計

一つのセッションで複数のサブタスクをまたぐと、前半の作業コンテキストがトークンを占有し続けます。機能実装・テスト作成・コードレビューをセッション境界で区切り、各セッション冒頭でCLAUDE.mdから必要な文脈を注入する設計が安定した運用につながります。セッション設計の考え方については Claude Codeの使い方ガイド も参考になります。

パターン3：MCPツールの遅延ロードを活用する

公式シミュレーターによれば、MCPツールはデフォルトでスキーマを遅延ロードし、Claudeがタスクに必要と判断したときのみ個別スキーマをロードします（code.claude.com/docs/en/context-window.md）。多数のMCPツールを登録している場合、この挙動がコンテキスト節約に直結します。ENABLE_TOOL_SEARCH=falseに設定するとすべてのスキーマを起動時にロードするため、ツール数が多い環境では避けた方が無難です。

パターン4：Auto-Memoryの定期的な刈り込み

Auto-Memoryの先頭200行・25KBという上限を意識し、定期的に不要なエントリを削除することがコンテキスト管理の基本的な実践となります。スプリントのレトロスペクティブ等でメモリファイルの内容を確認するサイクルを組み込むことで、蓄積された情報の陳腐化を防げます。

メモリ設計の実践：チーム導入チェックリストと深掘り活用例

Claude Codeのメモリ機能をチームへ導入する際、設計段階で決定すべき事項を体系的に整理します。これらを事前に合意せずに導入すると、CLAUDE.mdの管理が属人化し、メモリの品質が急速に劣化します。

1. CLAUDE.mdのオーナーシップ設計：誰がレビュー・マージ権限を持つかをコードのPR運用と同様に定めます。変更の背景をコミットメッセージまたはPRの説明に記録する習慣を設けます
2. CLAUDE.local.mdのgitignore登録：チーム全員の開発環境セットアップ手順に含め、初回セットアップ時に必ず実施します
3. Auto-Memoryの運用方針の合意：自動書き込みを許可する範囲をチームとして決定し、方針をCLAUDE.md自体に記述しておきます
4. メモリファイルの定期棚卸し：スプリントのレトロスペクティブ等で内容の鮮度を確認するサイクルを組み込みます。特にAuto-Memoryは200行・25KB上限を念頭に置いて優先度の低い項目を削除します
5. セッション設計の標準化：タスク粒度とセッション境界のルールをチームドキュメントに記載します
6. ルールファイルの分割基準策定：CLAUDE.mdが一定量を超えた時点で.claude/rules/への分割を検討するなど、具体的な閾値をチームとして設けます

指示が守られない・消えたように見えるときの確認手順

公式ドキュメントのトラブル対処にもとづく確認の順番です。

1. 読み込まれているかを確かめる：/context を実行し、「Memory files」の一覧に目的のCLAUDE.mdが出ているかを見ます。出ていなければ、Claudeには見えていません。サブディレクトリのCLAUDE.mdは、そのフォルダのファイルを扱うまで一覧に出ません。
2. 指示を具体的にする：「きれいに整形して」より「インデントは半角スペース2つ」のほうが守られます。
3. 食い違う指示を探す：複数のCLAUDE.mdで同じことに別々の指示があると、どちらかが任意に選ばれます。
4. 必ず実行させたいことはフックにする：CLAUDE.mdはシステムプロンプトの一部ではなく、その後に渡されるメッセージとして扱われるため、厳密に守られる保証はありません。「コミットの前に必ず実行する」といった決まりは、フック（hooks）で書きます。
5. /compact のあとに消えた場合：リポジトリ直下のCLAUDE.mdは、/compact のあとにディスクから読み直されます。消えたように見える指示は、会話の中だけで伝えたものか、まだ読み直されていないサブディレクトリのCLAUDE.mdや、paths 付きのルールに書かれたものです（paths 付きのルールは、該当するファイルを再び扱うまで読み込まれません）。残したい指示はCLAUDE.mdに書いておきます。

下は、練習用のフォルダで /context を実行した画面です。「Memory files」が「2 files・547 tokens」と表示され、CLAUDE.md と MEMORY.md の2つが読み込まれていることが分かります。カテゴリ別の内訳にも「Memory files」の行があります。

AI開発プロジェクト特有のメモリ活用例

機械学習のプロジェクトでは、推論パイプラインのアーキテクチャ決定事項（モデルの入出力テンソル仕様・前処理のnormalization方針・GANで生成した拡張データのディレクトリ構造・バッチサイズとGPUメモリの制約関係）をProject層のCLAUDE.mdに記述しておくことで、セッションをまたいだ一貫したコーディング支援を受けられます。機械学習特有の「実験を重ねるうちに暗黙知になりがちな設計判断」をメモリとして明文化する場として、CLAUDE.mdは有効に機能します。これはAI開発の実務でClaude Codeを活用する中で確認されている運用上のパターンです。

他ツールとのメモリ設計の比較視点

Cursorなど他のAIコーディングツールと比較した場合、Claude Codeのメモリ設計はファイルベースであることの透明性が高く、バージョン管理システムとの親和性において優位性があります。一方で、ファイルの維持・更新をチームが能動的に行わなければならないという管理コストは否定できません。他ツールとの詳細な機能比較は Claude Code vs Cursor比較 および Claude Code vs Codex比較 を参照してください。

Claude Code全体の入門については Claude Code入門・はじめ方 を、SEOや実務活用の観点からは Claude CodeをSEOに活用する入門ガイド も参考になります。

CLAUDE.mdを1年運用してわかったこと（一次情報）

当メディアの監修者・河合継はClaude Codeを2025年2月の公開（Claude 3.7 Sonnet の時期）から1年以上、CLAUDE.mdで運用ルールを育てながら実務に使ってきました。メモリ設計は「書けば効く」ものではなく、保守の仕方で効果が大きく変わります。

• 増やし続けると、かえって守られなくなります。ルールを足し込むほど、毎セッションの読み込みが重くなるうえ、項目どうしが矛盾して優先順位が曖昧になります。実際にルールが膨らんだ際は、定期的に重複・陳腐化を削る「棚卸し」をして初めて安定しました。
• 常時必要なものだけを常駐させます。すべての前提をCLAUDE.mdに置くより、いつも効かせたい最小限だけを残し、その場限りの指示は都度渡すほうが、固定費（初期化コスト）も軽くなります。
• スコープを使い分けて衝突を避けます。本文のとおりuser／project／localの層がありますが、何でもprojectに書くと環境差で噛み合わなくなります。「全員に効かせたいか／自分の環境だけか」で置き場所を分けると、チームでも破綻しにくいです。

よくある質問

Q. Claude Codeのメモリはどんな2系統で構成されていますか？
A. 開発者が明示的に記述するCLAUDE.mdファイルと、Claudeが自分でメモを書き残すAuto-Memory（自動メモリ）の2系統です。両方とも毎セッション冒頭でロードされますが、強制的な設定ではなくコンテキストとして扱われます。

Q. CLAUDE.mdファイルには何種類のスコープがありますか？
A. 自分で管理するのは、User（~/.claude/CLAUDE.md、全プロジェクト共通）、Project（./CLAUDE.md または ./.claude/CLAUDE.md、チームで共有）、Local（./CLAUDE.local.md、個人×プロジェクト固有・.gitignore推奨）の3つです。このほか、会社の管理者が全員に配る「管理ポリシー」のCLAUDE.mdがあります。

Q. Auto-Memoryはどれくらいの分量がロードされますか？
A. MEMORY.md の先頭200行または25KBのいずれか先に達した方までが、セッション開始時に自動ロードされます。細かい内容は別のファイルに分けて保存され、必要なときにだけ読まれます。

Q. Auto-Memoryはどこに保存されますか？
A. ~/.claude/projects/<プロジェクト>/memory/ に、索引の MEMORY.md と、メモ1件ごとのファイルが保存されます。同じgitリポジトリのワークツリーやサブディレクトリは1つのフォルダを共有します。保存先はそのパソコンの中だけで、別のパソコンやクラウド環境とは共有されません。

Q. Auto-Memoryをオフにするには？
A. セッション中に /memory を開いて切り替えます（設定 autoMemoryEnabled がユーザー設定に保存されます）。特定のプロジェクトだけオフにするには、そのプロジェクトの設定に “autoMemoryEnabled”: false を書きます。環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 でもオフにできます。

Q. CLAUDE.mdとAuto-Memoryの違いは何ですか？
A. CLAUDE.mdは開発者が書く指示とルール（プロジェクト・ユーザー・組織のスコープ）、Auto-MemoryはClaudeが自分で書き残すメモ（リポジトリ単位）です。CLAUDE.mdはClaudeの挙動を導きたいときに使い、Auto-Memoryはユーザーの修正や好みを、手で書かなくてもClaudeが覚えていくための仕組みです。

Q. AGENTS.md は読み込まれますか？
A. Claude Code v2.1.277以降では、作業ディレクトリとその上の階層に CLAUDE.md（CLAUDE.local.md を含む）が無い場合に、AGENTS.md がプロジェクトの指示として読み込まれます。CLAUDE.md がある場合は CLAUDE.md だけが読まれるため、両方使いたいときは CLAUDE.md から AGENTS.md を取り込む（インポートする）か、設定の Project instructions を変更します。

Q. CLAUDE.mdに書いたのに守られないときは、何を確認すればいいですか？
A. /context を実行して「Memory files」にそのファイルが出ているかを確認します。出ていなければ読み込まれていません。読み込まれている場合は、指示をより具体的に書く、ファイル同士で矛盾する指示がないか探す、の順に確認します。必ず実行させたいことは、CLAUDE.mdではなくフック（hooks）で書きます。

Q. 特定の操作を強制的にブロックしたい場合はどうすればいいですか？
A. CLAUDE.mdの記述はコンテキストとして扱われるだけで強制的な設定ではないため、特定のアクションを確実にブロックしたい場合はPreToolUseフックを使う必要があります。

Q. 「メモリ不足」と感じる問題の主な原因は何ですか？
A. 多くはパソコンのメモリ（RAM）の問題ではなく、コンテキストウィンドウの消費超過として発生します。システムプロンプト・Auto-Memory・環境情報・MCPツール・CLAUDE.mdなどが起動時にロードされ、長時間のセッションや大きなプロジェクトでは、使えるトークンの残りが急速に減ります。

Q. CLAUDE.mdが肥大化した場合はどう対処すればいいですか？
A. 1ファイル200行未満が目安です。それを超えるとコンテキストの消費が増え、指示が守られにくくなります。.claude/rules/ ディレクトリを使って役割別にファイルを分け（例：api.md、database.md、testing.md）、該当するファイルを扱うときだけ読み込まれるようにします。

Q. Auto-Memoryを運用する上でのリスクと対処法は？
A. 古くなった情報（廃止されたAPIや一時的な回避策）が残り、参照され続けるおそれがあります。保存された内容はただのMarkdownファイルなので、/memory から自動メモリのフォルダを開き、定期的に内容を確認して不要なものを編集・削除します。

---

まとめ：Claude Codeメモリ設計の要点と実装上の留意点

Claude Codeのメモリ機能は、LLMのステートレス性という根本的な制約を、ファイルベースの永続化とAuto-Memoryの自動化によって構造的に補う仕組みです。公式ドキュメント（code.claude.com/docs/en/memory.md）に基づいて本記事で論じた要点を以下に整理します。

• メモリにはCLAUDE.mdファイル（開発者が記述）とAuto-Memory（Claudeが自動書き込み）の2系統があります。いずれも毎セッション冒頭でロードされるが、強制的な設定ではなくコンテキストとして扱われます
• CLAUDE.mdはユーザーグローバル（~/.claude/CLAUDE.md）・プロジェクト（{root}/CLAUDE.md）・ローカル（{root}/CLAUDE.local.md）の3スコープで管理します。チームで共有すべきはプロジェクトスコープのファイルであり、ローカルスコープは.gitignoreで管理します
• Auto-MemoryはリポジトリごとのMEMORY.mdとして管理され、先頭200行または25KBがコンテキストにロードされます。蓄積が進むとこの上限が実質的な制約になるため、定期的な刈り込みが必要です
• 特定のアクションをCLAUDE.mdの記述で無条件にブロックすることはできません。アクションを強制的に制御したい場合はPreToolUseフックを使います
• 「メモリ不足」として体感される問題の多くはコンテキストウィンドウの枯渇です。.claude/rules/によるルールファイルの分割、セッション境界の設計、MCPの遅延ロード活用によって緩和できます
• CLAUDE.md自体がコンテキストを消費するという逆説を常に意識し、指示の簡潔さと情報の密度のバランスを取ることが大規模プロジェクトでの実用上の鍵となります

---

参考文献

• Anthropic「How Claude remembers your project」（code.claude.com）
  https://code.claude.com/docs/en/memory.md
• Anthropic「Explore the context window」（code.claude.com）
  https://code.claude.com/docs/en/context-window.md
• Anthropic「How the agent loop works」（code.claude.com）
  https://code.claude.com/docs/en/agent-sdk/agent-loop.md
• Anthropic「Subagents in the SDK」（code.claude.com）
  https://code.claude.com/docs/en/agent-sdk/subagents.md
• DevelopersIO「[2026年版] Claude Code を知る。」（2026/03/20）
  https://dev.classmethod.jp/articles/shoma-2026-claude-code-know-use-leverage/
• speakerdeck.com/oikon48「Claude Code 2026年最新アップデート」（2026/03/12）
  https://speakerdeck.com/oikon48/claude-code-0312
• Serverworks Blog「【2026/2/22〜28】Claude Code更新情報」（2026/03/01）
  https://blog.serverworks.co.jp/2026/03/01/170000
• note.com/kazu_t「【2026年3月版】Claude Codeがどれだけ進化したかまとめ」
  https://note.com/kazu_t/n/n1a207262b51c
• zenn.dev/takna「Claude Code 追加機能タイムライン（2025/07〜2026/03）」（2026/03/29）
  https://zenn.dev/takna/articles/claude-code-added-features-jul2025-mar2026
• app-tatsujin.com「Claude Codeの使い方と2026年版新機能徹底ガイド」（2026/05/09）
  https://app-tatsujin.com/claude-code-usage-guide-2026/
• ai-souken.com「【2026年版】Claude Codeのアップデート・最新情報まとめ」
  https://www.ai-souken.com/article/claude-code-updates-2026

関連記事

• Claude Codeとは
• Claude Codeのベストプラクティス
• Claude Code Skillsとは？作り方と一覧
• Claude Codeのセキュリティと安全な使い方
• Claude Codeで自動化・定期実行する方法