TL;DR
- Claude Code でセッションを跨ぐ長期作業を成立させるには、コンテキストウィンドウを超える「外部記憶」の設計が必須
- 記憶には3つの層がある：永続 memory・プロジェクト規約（CLAUDE.md / AGENTS.md）・セッション内 Plan
- 3層を混同すると、永続化したい知見が消えたり、不要な情報がコンテキストを圧迫したりする
- failure mode は「永続化忘れ」「Plan の更新忘れ」「CLAUDE.md の肥大化」の3つが典型
- 設計の起点は「次セッションが cold start でも読める形」で書くこと
この記事の目的と成功基準
- 目的: Claude Code を長期プロジェクトで使う際の記憶設計を、3層構造とアンチパターンの両面から整理する
- 想定読者: Claude Code を業務で日常的に使うエンジニア、Vibe Coding の運用を改善したい人
- 成功基準: 「Claude Code 記憶」「Claude Code メモリ」関連クエリでの流入、Vibe Codingトークン経済学 への回遊
なぜ「記憶」が問題になるのか
Claude Code のセッションは長いが有限だ。コンテキストウィンドウは1M token あっても、実用上は数百K token を超えると要約圧縮が走り、初期の文脈が薄まる。さらにセッション終了で揮発する。
Qiita のトレンド議論 でも、Claude Code を本格運用するチームほど「次セッションが何を覚えていないか」という観点での設計に時間を割いている。覚えていないと、毎回ゼロから状況説明し直すコストが乗り、Vibe Coding の生産性メリットが相殺される。
3層の記憶設計
層1: 永続 Memory（user / feedback / project / reference）
Claude Code には auto memory 機構があり、~/.claude/projects/<project>/memory/ 配下に .md ファイルとして記憶を蓄積できる。
層1で保持すべきもの：
- ユーザーの役割・コラボスタイル
- 反復的に指摘される feedback（コーディング規約・禁止事項）
- プロジェクトの目的・制約・重要イベント
- 外部システムへのポインタ（Linear・Slack channel など）
層1で保持してはいけないもの：
- コード構造（git で読める）
- 直前の変更履歴（git log で読める）
- 一時的な作業ステート（次のセッションでは無意味）
層2: プロジェクト規約（CLAUDE.md / AGENTS.md）
リポジトリにチェックインする規約文書。
- コーディングスタイル
- ディレクトリ構成のルール
- ビルド・テスト・デプロイの定型コマンド
- 触ってはいけないファイル
層2は「リポジトリ全体に効く前提」をまとめる場所。個別 PR の方針や進捗は含めない。肥大化すると毎回コンテキストを圧迫するので、200行を超えたら分割を検討する。
層3: セッション内 Plan / タスクリスト
plan.md や TaskCreate で管理する作業内ステート。
- 現セッションの目標
- 進行中のタスク
- 次セッションへの引き継ぎ事項
層3は「揮発前提」で書く。セッション終了時に必要なら層1・層2に昇格させる。
3層を分けないと何が起きるか
failure mode 1: 永続化忘れ
ユーザーから受けた重要 feedback を Plan に書いて、セッション終了で消える。次セッションで同じ間違いを繰り返す。
→ feedback を聞いたら即座に層1（memory）に書く運用を徹底する。
failure mode 2: Plan が古い
セッション中に方針が変わったのに Plan ファイルを更新せず、後半の判断が古い前提に引きずられる。
→ 方針変更があったら Plan を編集 or TaskUpdate で必ず反映する。
failure mode 3: CLAUDE.md の肥大化
「次セッションが忘れないように」と全部 CLAUDE.md に書いていく。やがて400行超になり、毎セッション cold start で大量の token を消費する。
→ CLAUDE.md には「リポジトリ普遍の規約」だけを置く。プロジェクト固有の進捗は docs/working/ 配下に分離する。
設計のチェックリスト
セッション開始時のセルフチェック：
- 層1 memory に「今のユーザー / プロジェクト状態」が反映されているか
- CLAUDE.md / AGENTS.md は200行以下に保たれているか
- 前セッションの Plan の引き継ぎ事項が現セッションの TaskCreate に取り込まれているか
- 「次セッションが cold start で読めるか」の目線で書いているか
実装パターン: Growth Lab での運用
このリポジトリ（notionnext-blog）では以下の運用にしている：
MEMORY.md一覧で memory ファイルへのリンクを管理feedback_*.mdで繰り返し指摘された運用ルールを保存project_*.mdでセッション毎の進捗スナップショットCLAUDE.mdは90行以下、リポジトリ普遍の規約に限定docs/working/STRATEGY-XXXX/status.mdでプロジェクト毎の進捗を分離
このパターンは Vibe Codingトークン経済学 で扱った cache 戦略とも相性が良い。層2は cache 対象として安定、層3はセッション内で動的に進化する、という分業ができる。
チームでの記憶共有
個人開発と違い、チーム開発では「特定の人のローカル memory」に依存すると、他メンバーが Claude Code を使う時に同じ前提を持てない。
- リポジトリ内（層2）に書ける情報は層1から優先昇格
- 個人の好みに関する記憶（user memory）はチームには出さない
- プロジェクト方針の変更は CLAUDE.md / AGENTS.md の PR で記録（履歴が残る）
FAQ
Q. Cursor や Codex でも同じ3層モデルは通用しますか？ A. 通用します。永続記憶機構が違っても、「永続規約・セッション内ステート・cold start 対応」の3軸は共通です。
Q. memory の量が増えすぎるとどうなりますか？
A. cold start 時の読み込みコストが膨らみます。MEMORY.md 索引の200行制限など、上位インデックスを軽量に保つ運用が必要です。
Q. CLAUDE.md と AGENTS.md の使い分けは？ A. Growth Lab では AGENTS.md を SSoT、CLAUDE.md を Claude 固有の最小差分とする運用。プロジェクトに応じて統一しても問題ありません。
まとめ
Claude Code でセッションを跨ぐ長期作業は、永続 memory・プロジェクト規約・セッション内 Plan の3層構造を意識した記憶設計で支える。3つを混同しないこと、failure mode（永続化忘れ・Plan 古化・規約肥大化）を回避することが、Vibe Coding の生産性を実値に変える鍵になる。
