はじめに
Claude Code を長期プロジェクトで使っていると、「前回のセッションで分かったこと」が次回に引き継がれない問題 に必ずぶつかります。
Anthropic 公式の auto memory 機能は便利ですが、
- 対応モデル・環境が限定される
- どこに何が保存されているか不透明
- プロジェクト横断では使いにくい
そこで、Markdownファイルベースの自作 memory システム をプロジェクトに組み込むと、Claude Code のセッションを越えてナレッジが育っていきます。
この記事では、自分が複数プロジェクトで実運用している設計パターンを紹介します。
設計の全体像
project-root/
├── CLAUDE.md # プロジェクトのメイン指示（不変）
├── .claude/
│ ├── rules/ # カテゴリ別のルール・設定
│ │ ├── project-info.md
│ │ ├── workflow.md
│ │ └── data-update.md
│ └── skills/ # カスタムスキル
└── memory/ # ← ここが auto memory の核
├── MEMORY.md # 索引（常に context に読ませる）
├── user_role.md
├── feedback_xxx.md
└── project_xxx.md
ポイントは3つです。
-
CLAUDE.mdは不変の設定。頻繁に変わる情報は置かない -
memory/は「学びの蓄積」。セッションで得た知見をここに書く -
MEMORY.mdは索引だけ。本文はサブファイルに書いて Read で取りに行かせる
4種類の memory タイプ
自分の運用では、memory を 4種類に分類 しています。Claude Code が「何を保存すべきか」を判断できるよう、カテゴリを明示するのが肝です。
1. user 型 — ユーザーの役職・スキル・嗜好
---
name: ユーザー役職
type: user
description: ベンチャー企業CTO、Go歴10年、React初心者
---
- CTOとしてフルスタック開発を10年
- Go に深い知見、React は今月から触り始めた
- 技術説明は「Go の慣習とどう違うか」で例えると伝わりやすい
Claude Code はこれを読んで「この人には Go の慣習を引き合いに出して説明する」と判断できます。
2. feedback 型 — 過去に指摘された振る舞い
---
name: テストでモックを使わない
type: feedback
description: 統合テストは本物のDBを使う
---
**ルール**: 統合テストではDBをモックしない
**Why**: 昨Q、モックテストはグリーンなのに本番マイグレーションが壊れた事例あり
**How to apply**: `test/integration/**` のテストを書くときは testcontainers で本物のPostgresを立てる
重要なのは Why と How to apply の2行を必ず添えること。理由が書いてあれば、エッジケースで「この場合は適用すべきか？」を Claude が自分で判断できます。
3. project 型 — プロジェクトの動的な状態
---
name: 次スプリントのマージ凍結
type: project
description: 3/5からモバイル版リリース前の凍結期間
---
**事実**: 2026-03-05 からマージ凍結（mobile-v2 リリースブランチ切り出しのため）
**Why**: モバイルチームのリリースが最優先
**How to apply**: 3/5 以降の非クリティカルPRは flag 立てて保留扱いにする
日付は 必ず絶対日付で書く。「来週」「Thursday」のような相対表現は時間が経つと意味不明になります。
4. reference 型 — 外部リソースのポインタ
---
name: 障害トラッカー
type: reference
description: パイプライン関連のバグは全てここに集約
---
Linear プロジェクト: `INGEST`
- URL: https://linear.app/xxx/project/INGEST
- パイプライン関連のバグ・改善要望はここを読む
MEMORY.md（索引）の設計
# Memory
## プロジェクト: X自動運用Bot
- 仕様書: `99_ツール/bot仕様書/docs/`
- Supabase Project: `xxxxx`
- 完了済み: pg_cron 5ジョブ稼働中
## 技術メモ
- [feedback_use_cmux.md](feedback_use_cmux.md) ブラウザ操作はcmux、mcpは使わない
- [feedback_qiita_no_retry.md](feedback_qiita_no_retry.md) Qiita投稿は1回失敗でスキップ
## ユーザー
- [user_role.md](user_role.md) ベンチャーCTO、テンポ重視、確認最小限
索引は最小限のメタ情報＋サブファイルへのリンク に留めます。本文を MEMORY.md に書き込むと、肥大化して context を圧迫します。
Claude に「memory を更新して」と指示する運用
セッション中に新しい学びがあったら、明示的に更新させます。
/memory save
「今回の発見：pg_cron は `net.http_post` でJWTハードコード必須。
`current_setting` は使えない」
→ technical_notes.md に追記してください
自動化するなら、hooks で session end 時に memory update を走らせる方法もあります（.claude/settings.json）:
{
"hooks": {
"SessionEnd": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "claude /memory-review" }
]
}
]
}
}
運用で気をつけるポイント
1. memory は腐る前提で書く
プロジェクト状態系は2週間で陳腐化します。日付を必ず添え、参照時に「まだ有効か」を Claude 自身に判定させましょう。
2. 索引はフラットに保つ
階層が深くなると Claude が見つけられません。MEMORY.md は最大で2階層、基本フラットで運用します。
3. 「保存すべき」判定を甘くしない
何でも memory に書くと、次回読むときのノイズになります。
- 保存する: サプライズがあった学び、非自明な制約、ユーザー嗜好
- 保存しない: コードから derivable な事実、git log で追える変更
まとめ
auto memory は、Claude Code のセッション寿命を超えてプロジェクト知識を育てる仕組みです。
- 4つの type（user / feedback / project / reference）で分類する
- 索引（MEMORY.md）と本体（サブファイル）を分離する
- 書くたびに
WhyとHow to applyを添える
この設計で運用し始めてから、プロジェクト横断での「あの時の判断、なぜだっけ？」が激減しました。
AI時代のエンジニア学習サポートを MENTA で提供しています。
YouTube でもAI×プログラミングを発信中 → チャンネル