Claude Code メモリシステム徹底解説——CLAUDE.md・auto memory・コンテキスト最適化の実践テクニック

はじめに

Claude Codeを使っていて、こんな経験はありませんか？

Claude Codeは毎回新しいセッションを始めるたびに「初対面」の状態からスタートします。前回のセッションで教えたことは、明示的にメモリに保存しない限り引き継がれません。

しかし、Claude CodeにはCLAUDE.md（あなたが書く指示書）とauto memory（Claudeが自分で書くメモ）の2層メモリ構造があり、適切に設定すればセッション間の一貫性を劇的に向上できます。

この記事を読み終わると、以下ができるようになります：

• CLAUDE.mdの4つのスコープと優先順位を理解し、適切に配置できる
• 200行ルールに基づいて効率的なCLAUDE.mdを設計できる
• path-specificルールでファイルごとの指示を分離できる
• auto memoryの仕組みを理解し、定期メンテナンスを行える
• コンテキスト圧縮への対策を構築できる

メモリシステムの全体像

2層構造

各層の役割

事前準備

必要なもの

/initで始める

まだCLAUDE.mdがない場合は、/initコマンドで自動生成できます。

claude
# セッション内で
/init

Claude Codeがプロジェクト構造を分析し、CLAUDE.mdのひな形を生成してくれます。

ハンズオン 1: CLAUDE.mdの設計と配置

架空の業務システム「KanriPro」を例に、効果的なCLAUDE.mdを設計します。

Step 1: スコープの理解

CLAUDE.mdは4つのスコープで設定でき、上位が優先されます。

Step 2: 200行ルールを守る

CLAUDE.mdの長さとルール適用率には明確な相関があります。

200行以内に収めるのが鉄則です。

Step 3: KanriProのCLAUDE.mdを書く

# KanriPro — プロジェクトルール

## 技術スタック
- Next.js 15 (App Router) + TypeScript 5.7
- Tailwind CSS v4 (CSS-first configuration)
- Firebase (Firestore, Auth, Hosting)
- Vitest + React Testing Library

## パッケージマネージャー
yarn を使用。npm は使用禁止。

## コーディングルール
- インデント: 2スペース
- セミコロン: 省略（Prettier統一）
- コンポーネント: FC型でnamed export
- any型の使用禁止
- import順: React → 外部 → 内部 → 型

## コミットメッセージ
Conventional Commits形式:
- feat: 新機能
- fix: バグ修正
- refactor: リファクタリング

## ディレクトリ構成
- src/app/ — ページ (App Router)
- src/components/ — UIコンポーネント
- src/lib/ — ユーティリティ
- src/types/ — 型定義

## テスト
- テストファイル: *.test.ts で co-locate
- カバレッジ目標: 80%以上

## 詳細ルール
@.claude/rules/api-conventions.md
@.claude/rules/component-rules.md

ポイント:

• 具体的で簡潔（「インデント: 2スペース」のように一目で分かる）
• @構文で詳細ルールを外部ファイルに分離
• 全体で50行以内に収まっている

Step 4: @importで詳細を分離

<!-- .claude/rules/api-conventions.md -->
---
paths:
  - "src/app/api/**/*.ts"
  - "src/lib/api/**/*.ts"
---

# API実装ルール
- レスポンスは ApiResponse<T> 型でラップ
- エラーハンドリングは AppError クラスを使用
- バリデーションは zod スキーマで実装
- 認証が必要なエンドポイントは authMiddleware を適用

<!-- .claude/rules/component-rules.md -->
---
paths:
  - "src/components/**/*.tsx"
---

# コンポーネント実装ルール
- Props型は interface で定義
- デフォルトエクスポート禁止（named export のみ）
- Tailwind CSSのみ使用（CSS Modules禁止）
- aria属性を適切に設定（WCAG 2.1準拠）

YAMLフロントマターのpaths:で、対象ファイルパターンにマッチした場合のみルールが読み込まれます。APIファイルを編集中にコンポーネントルールが混ざることがなくなり、コンテキストの効率が上がります。

ハンズオン 2: Auto Memoryの活用

Step 1: Auto Memoryの仕組みを理解する

Auto Memoryは、Claude Codeがセッション中に学んだことを自動的に記録する機能です。

~/.claude/projects/<project-hash>/memory/
├── MEMORY.md          # インデックス（先頭200行がロードされる）
├── debugging.md       # デバッグで学んだこと
├── api-conventions.md # API実装のパターン
└── patterns.md        # プロジェクト固有のパターン

Step 2: 何が記録されるか

たとえば、セッション中に「KanriProのFirestoreはkanri-pro-prodコレクションを使う」とClaudeが学習すると、次のセッションでもその情報を活用できます。

Step 3: MEMORY.mdの最適化

MEMORY.mdは先頭200行のみがセッション開始時にロードされるため、重要度の高い情報を上部に配置します。

<!-- MEMORY.md -->
# KanriPro プロジェクトメモ

## ビルド & デプロイ
- `yarn dev` で開発サーバー起動（ポート3000）
- `yarn build` で本番ビルド
- `firebase deploy --only hosting` でデプロイ
- Firestore: kanri-pro-prod（本番）/ kanri-pro-dev（開発）

## よく使うパターン
- 詳細は [patterns.md](./patterns.md) を参照

## デバッグ知見
- 詳細は [debugging.md](./debugging.md) を参照

## 注意点
- src/lib/legacy/ 配下は触らない（移行予定）
- Firestoreのセキュリティルールは firebase/firestore.rules で管理

ポイント: MEMORY.mdはインデックスとして使い、詳細は別ファイルへリンクします。

Step 4: 手動で記憶させる

Claude Codeに直接「これを覚えて」と伝えることもできます。

KanriProではFirestoreのバッチ書き込みは500件を超えないようにしてください。
これを覚えておいてください。

Claude Codeは自動的にMEMORY.mdまたは関連ファイルに記録します。

Step 5: 定期メンテナンス

月1回程度、メモリファイルを確認して整理しましょう。

# メモリファイルの場所を確認
ls ~/.claude/projects/*/memory/

# MEMORY.mdを確認
cat ~/.claude/projects/*/memory/MEMORY.md

古くなった情報や誤った記録を削除・更新します。特にライブラリのバージョンアップやアーキテクチャ変更後は確認が重要です。

ハンズオン 3: コンテキスト圧縮（Compaction）対策

長いセッションではコンテキストウィンドウが圧縮されることがあります。このときCLAUDE.mdは完全に保持されますが、会話中の指示は失われる可能性があります。

何が残り、何が消えるか

対策1: 重要な指示はCLAUDE.mdに書く

会話中に「このルールを守って」と伝えるだけでは、コンパクション後に忘れられます。永続化したい指示は必ずCLAUDE.mdに記載しましょう。

対策2: Hooksで文脈を再注入

Hooksの記事で解説したSessionStartフックを使います。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "type": "command",
        "command": "cat .claude/context-reminder.md",
        "description": "コンパクション後にコンテキストを再注入"
      }
    ]
  }
}

.claude/context-reminder.md に、コンパクション後に失われがちな文脈を書いておきます。

## コンパクション後リマインダー
- 現在のタスク: 経理モジュールのインボイス機能実装
- 重要: テストは必ずVitestで書くこと
- 重要: Firestoreのバッチは500件制限

対策3: /compactで能動的に圧縮

コンテキストが膨らんできたと感じたら、自動圧縮を待たずに/compactコマンドで能動的に圧縮します。タイミングをコントロールすることで、重要な情報を失うリスクを減らせます。

モノレポでの活用

大規模なモノレポでは、claudeMdExcludesで不要なCLAUDE.mdの読み込みをスキップできます。

{
  "claudeMdExcludes": [
    "packages/legacy-app/**",
    "packages/mobile-app/**",
    "node_modules/**"
  ]
}

また、.claude/rules/ディレクトリでシンボリックリンクを使えば、複数パッケージで共通ルールを共有することも可能です。

# packages/web-app/.claude/rules/
ln -s ../../../shared-rules/typescript.md typescript.md

Tips・注意点

CLAUDE.md vs Auto Memory の使い分け

原則：チームで共有すべきルールはCLAUDE.md、個人的な学習はAuto Memoryです。

よくあるミス

ワークツリーでのメモリ共有

同じGitリポジトリのワークツリー間では、Auto Memoryが自動的に共有されます。ブランチAで学んだことがブランチBのセッションでも活用されるため、並行開発時に知見が分散しません。

まとめ

次のアクションとしておすすめ：

1. /initでCLAUDE.mdを生成する — まだない場合はここから
2. 200行以内に収めているか確認する — wc -l CLAUDE.mdで行数チェック
3. path-specificルールを1つ作る — .claude/rules/に分離を始める
4. Auto Memoryを確認する — ~/.claude/projects/*/memory/を見てみる
5. コンパクション対策のHookを設定する — SessionStart + compactマッチャー

メモリシステムを適切に活用することで、「Claudeが毎回忘れる」問題から解放され、セッションをまたいでも一貫した品質のコードを生成できるようになります。

---

参考リンク：

• Claude Code公式ドキュメント — Memory
• CLAUDE.md Memory System — Deep Dive（SFEIR Institute）
• Anthropic Just Added Auto-Memory to Claude Code（Medium）

---

関連記事：

• Claude Code Hooks完全ガイド——pre/postフックでAI開発ワークフローを自在にカスタマイズ
• AGENTS.mdでAIエージェントの精度を劇的に上げる——Vercelが実証した「パッシブコンテキスト」戦略
• Claude Code Skills完全ガイド——カスタムスキルの書き方とベストプラクティス