Claude Codeのメモリシステムには4つのレイヤーがあり、それぞれが異なる役割を持っています。各レイヤーの仕組みの概要はメモリ永続化ガイドに詳しくあります。本記事が扱うのは別の問題です：継続的なメンテナンスを必要とせず、長期間のブランクを乗り越え、時間とともに劣化でなく改善されるメモリ設定をどう構築するかです。
CLAUDE.mdとMEMORY.mdの実例はギャラリーで確認できます。
ほとんどのメモリ設定が失敗する理由
多くの開発者は2つのどちらかをします：
- 丁寧にCLAUDE.mdを書いて、そのまま放置する
- Auto Memoryに完全に依存して、Claudeが重要なことを記録してくれることを期待する
どちらのアプローチも機能しなくなります。Option 1は、プロジェクトが進化するにつれてファイルに古いコンテキストが残ります。Option 2は、6ヶ月前の古い情報と現在の情報が混在したメモリディレクトリを生み出し、どちらが正しいのかの判断ができません。
機能するメモリシステムには必要なものがあります：明確なメンテナンスタイミング、「ルール」（CLAUDE.md）と「知識」（MEMORY.md）の明確な分離、そしてAuto Memoryのキュレーション戦略です。
3ファイルアーキテクチャ
アクティブなプロジェクトで最もうまく機能するパターンは3ファイル構成です。
CLAUDE.md — 変更頻度の低い安定したルール。規約、ツールの好み、Claudeが常にすること・絶対にしないこと。目標：1,000トークン未満。四半期ごとにレビュー。
MEMORY.md — 現在のプロジェクト状態。アーキテクチャの決定とその理由、最近の変更、既知の問題、進行中の作業。このファイルは頻繁に変更されます。2〜4週間ごとにレビュー。
CONTEXT.md — セッション固有の引き継ぎ。このセッションで達成したこと、残っている課題、次のセッションで着手すること。毎セッション変更されます。セッション終了時にClaudeが更新。
この分離が重要なのは、各ファイルのメンテナンスサイクルが異なるからです。安定したルールと現在の状態を1つのCLAUDE.mdに混ぜると、最も速く変化するコンテンツのペースで全体が古くなります。
MEMORY.md：何を書くか
有用なMEMORY.mdの内容：
# プロジェクトメモリ
最終更新: [日付]
## アーキテクチャ
### データレイヤー
- Prisma ORMを通じたPostgreSQL
- マイグレーションはprisma/migrations/ — 実行: npx prisma migrate dev
- サービス境界を越えたPrismaのリレーションクエリは使わない
（サービス間の呼び出しはHTTP APIを経由、直接DB共有アクセスは禁止）
### 認証
- JWTトークン、15分ごとに更新
- httpOnlyクッキーに保存（localStorageではない）
- 認証ミドルウェア: src/middleware/auth.ts
- 管理者ルートはトークンペイロードにrole: "admin"が必要
### 主要な設計上の決定
- Next.js App Router採用（2026年4月）: サーバーコンポーネントのサポートが優れているため
- 全リスト操作にオプティミスティックアップデートを使用 — これなしではUXが壊れていた
- メール送信はResend（SESではなく） — 開発体験が良いため
## 既知の問題（修正しないこと）
- src/lib/legacy-import.tsのTypeScriptエラー: 意図的、@ts-ignoreで抑制
理由: サードパーティライブラリの型定義が誤っている、上流の修正待ち
- `products.sync()`関数のテストで競合状態のように見える問題
— テストのアーティファクト、実際のバグではない。リファクタリング禁止
## 最近の変更（直近30日）
- 2026年4月: 決済処理をStripeの新PaymentElementに移行
- 2026年4月: 全パブリックAPIエンドポイントにレート制限を追加（10リクエスト/分）
- 2026年3月: クライアントサイドのデータ取得をreact-queryからSWRに移行
## 進行中の作業
- レビュー中PR: マルチテナントサポート追加 (#234)
- 進行中: 通知システム（ブランチ: feature/notifications）
- ブロック中: メールテンプレートがデザインレビュー待ち「既知の問題（修正しないこと）」セクションは特に重要です。これがないと、Claudeは毎セッション意図的な特性を「バグ」として修正しようとし、時間が無駄になります。
CONTEXT.md：セッション引き継ぎパターン
セッション引き継ぎパターンはClaude Codeのメモリ管理で最も活用されていないテクニックです。各作業セッションの終わりにClaudeにCONTEXT.mdを更新させます：
CONTEXT.mdを以下の内容で更新してください：
1. 今日完了したこと（関数名、ファイルパスを具体的に）
2. 未完了のこととその理由
3. MEMORY.mdにまだ記録されていない決定事項
4. 次のセッションで始めるべきこと結果はこうなります：
# セッションコンテキスト
前回セッション: 2026年4月11日
## 完了
- src/services/notifications.tsにcreateNotification()を実装
- notification_eventsテーブルを追加（マイグレーション: 20260411_add_notifications）
- 通知サービスのユニットテスト通過（15件）
- ヘッダーコンポーネントにリアルタイム通知カウントを接続
## 未完了 / 進行中
- 通知のメール配信: サービスは作成済み、実際の送信にはまだ接続していない
→ 次のステップ: src/lib/email.tsにResendを統合
- 通知設定UIはプレースホルダー
→ FigmaからのデザインSpec待ち
## 決定事項
- 通知カウント更新にWebSocketではなくポーリング（5秒間隔）を選択
理由: WebSocketはデプロイの複雑性を増す。このユースケースにはポーリングで十分
→ MEMORY.mdに追加済み
## 次のセッション：ここから始める
1. Resendを通じた通知メール送信の接続（src/lib/email.ts）
2. 次に: 通知設定ページの構築（FigmaのデザインはX: [リンク]）
3. 優先度低: 通知の既読/未読一括更新エンドポイント追加次のセッション開始時には：
CONTEXT.mdを読んで、通知の作業を続けましょう。
メール送信の接続から始めます。これにより毎セッション冒頭の「何をしていたか再説明」のオーバーヘッドがなくなります。
Auto Memoryのキュレーション戦略
Auto Memoryは意識的な管理なしに蓄積し続けます。キュレーションがなければ、2年分のプロジェクト履歴にまたがる数百のノートが、現在の情報と古い観察が混在した状態になります。
月次レビュー
月に1回、メモリディレクトリ（~/.claude/projects/<プロジェクトハッシュ>/memory/）をスキャンします。以下を探します：
- 現在のMEMORY.mdと矛盾するノート（古くなっている）
- 削除したパターンや依存関係についてのノート
- 同じトピックについての重複ノート
古いノートは削除します。Auto Memoryは包括的だが古いより、正確だが小さい方が効果的です。
重要なノートをMEMORY.mdに昇格させる
Auto Memoryが本当に重要なことを記録した場合（学習した好み、発見したアーキテクチャ上の制約）、それをMEMORY.mdに移動してフォーマットを制御し、明確に見えるようにします。その後、重複を避けるためAuto Memory版を削除します。
Auto Memoryに任せるべきこと
Auto Memoryは修正を通じてClaudeが学んだ行動の好みを記録するのに最適です：
- 「ユーザーはネストした条件より早期リターンを好む」
- 「ユーザーは常にTypeScript strictモードを使う」
- 「このプロジェクトでは名前付きエクスポートのみ」
これらはCLAUDE.mdに手動で書くには細かすぎますが、セッション間で失うには有用すぎる情報です。
チーム vs 個人開発者のパターン
個人開発者の設定
CLAUDE.md → 個人の安定した好み + プロジェクトルール
MEMORY.md → プロジェクト知識 + アーキテクチャ状態
CONTEXT.md → セッション別引き継ぎ（Claudeが管理）
Auto Memory → 学習した好み（月次キュレーション）チームの設定
チームでは個人の好みと共有設定を分離します：
~/.claude/CLAUDE.md → 個人の好み（リポジトリには含めない）
./CLAUDE.md → チームの規約（リポジトリに含める、PRでレビュー）
./MEMORY.md → プロジェクト知識（リポジトリに含める、チームが管理）ルール：「自分がどう作業するか」に関することは~/.claude/CLAUDE.mdに。「プロジェクトがどう動くか」に関することは./MEMORY.mdに。「チームがどうコーディングするか」に関することは./CLAUDE.mdに。
精度を時間と共に維持する
ほとんどのメモリシステムの失敗パターンはドリフトです：メモリがプロジェクトの「現在」ではなく「過去」を表すようになります。3つの習慣が防止します。
変更時に更新する、レビュー時ではなく。 重要なアーキテクチャ上の決定をした直後にMEMORY.mdを更新します。四半期レビューまで待ちません。決定は今が最も新鮮で、6週間後には古くなります。
プロジェクトの転換点でレビューする。 大きな機能開発を始める前や大幅なリファクタリング後に、MEMORY.mdを読んで古くなった部分を更新します。転換点での15分のレビューは、その後のClaudeの誤解を修正するよりコスト効率が良いです。
ClaudeにMEMORY.mdの一貫性チェックを依頼する。 定期的にこう依頼します：
MEMORY.mdをレビューして、現在のコードベースと比較して
古くなっているまたは矛盾していると思われる箇所を指摘してください。
更新が必要なものをリストアップするだけで、まだ変更は加えないでください。Claude Codeのメモリレイヤーの概念的な概要についてはメモリ永続化ガイドを参照してください。マルチファイルメモリ設定と組み合わせるトークン最適化戦略はCLAUDE.mdトークン予算ガイドで確認できます。実際のCLAUDE.mdとMEMORY.mdの例はギャラリーにあります。