1. 課題：メモリの肥大化と陳腐化が AI の精度を損なう
Claude Code でエージェント運用を始めると、誰もが同じ問題に直面する。会話が終わったら、AI は何も覚えていない。
「先週直したルールをまた破られた」「同じ失敗を何度も繰り返す」「コンテキストウィンドウが埋まってしまう」——これらは AI の能力不足ではなく、記憶設計の欠落が原因だ。CLAUDE.md と memory/ ディレクトリが存在するのはそのためだが、「覚えておいてほしいことは全部 CLAUDE.md に書く」という運用を続けると、別の問題が出てくる。
肥大化による検索性の低下
エージェントがコンテキストウィンドウに読み込む情報量には上限がある。CLAUDE.md が肥大化すると、重要なルールが埋もれて実際には参照されなくなる。「書いてあるのに守られない」という状況は、たいていメモリの肥大化が原因だ。
AI は情報量が多すぎるコンテキストでは、本来参照すべきルールを見落とす。テキストサーチで見つかることと、実際に判断に影響することは別だ。情報は多いほど良いのではなく、必要なものが必要なときに参照できるかが勝負になる。
陳腐化による誤判断
もうひとつの問題は古い情報が消されないまま残ることだ。3 ヶ月前に正しかったルールが今は間違っているかもしれない。その古い情報を AI が参照すると、自信を持って誤った判断をする。「書いてあるから従った」と AI は説明するが、元の情報が古ければ出力も間違っている。
メモリの品質は追加の数ではなく、精度と鮮度で決まる。定期的な棚卸しなしにメモリを増やし続けると、やがてシステムの信頼性が低下する。
これらふたつの問題——肥大化と陳腐化——を防ぐためには、何を・どこに・どの頻度で置くかの戦略が必要になる。
2. パターン：4 分類メモリ設計
AI に渡す情報を保管場所と更新頻度で整理する設計。「この情報は変わるか、変わらないか」という一点の基準で、4 つのカテゴリに分類する。
| 分類 | 内容 | 保管場所 | 変更頻度 | 揮発性 |
|---|---|---|---|---|
| user | 本人の行動様式・判断傾向・優先事項 | memory/user-*.md | 低（数ヶ月単位） | 低（長期保持） |
| feedback | 過去の失敗・修正ルール・行動変容 | memory/feedback-*.md | 高（随時） | 中（定期削除） |
| project | 進行中プロジェクトの状態・方針・直近決定 | memory/project-*.md | 高（随時） | 高（完了で削除） |
| reference | 恒久的な仕様・ドメイン知識・ポリシー | CLAUDE.md / docs/*.md | 低（変更時） | 低（長期保持） |
分類の本質は単純だ：「変わる情報は memory に、変わらない情報は docs に」。これだけを基準に置くと、肥大化と陳腐化の両方に対処できるようになる。
3. 設計の核：各分類の役割と更新ルール
user — 本人の行動傾向を記録する
仕事の癖や優先事項がある。「見出しは動詞で始める」「金額は最初に見積もってから説明する」「長い説明より�条書きを好む」——こういった個人ルールは対話のたびに説明しなくても AI が知っていると、意思疎通の速度と精度が上がる。
更新頻度: 低。自分の判断基準が本質的に変わったタイミング（数ヶ月単位）でのみ更新。
具体例:
# memory/user_communication_style.md
---
name: 通信スタイル
description: 本人の文章・説明・判断の癖
type: user
---
- 説明は「背景 → 問題 → 解決策」の順で述べることを好む
- 形容詞は 3 個までに制限する（それ以上あると軸がブレたように見える）
- 数値と定性を混ぜて説明しないこと（別の段落に分ける）削除タイミング: 判断基準が本質的に変わったら古いエントリを削除。
feedback — 失敗と学習のパターンを記録する
AI が同じ間違いを繰り返したとき、その修正内容を記録する。「GitHub のリポジトリデフォルトブランチを確認してから push してください。main とは限らない」「Google Drive に書き込む前に、必ず共有ドライブ配下かマイドライブかを確認してください」——一度経験した失敗パターンへの対処が典型だ。
更新頻度: 最も高い。問題が起きるたびに追加。
発生日の明記が必須。いつ起きた問題かが分かると、その後に運用や環境が変わった場合に「この feedback はまだ有効か」を判断できる。
具体例:
# memory/feedback_drive_auth.md
---
name: Drive 書き込み時の認証確認
description: 意図しない場所への書き込みを防ぐルール
type: feedback
---
ルール: Google Drive に create/copy/update するとき、必ずフォルダの親チェーンを遡って「このフォルダは共有ドライブ配下か、マイドライブか」を確認する。
Why: 2026-04-15、AI が誤ってマイドライブの共有できないフォルダに書き込み、チーム全体が参照できないドキュメントが生成された。以後、確認ステップを明示化した。
How to apply: Drive に `files.create/copy/update` する予定ならすべてこのルール対象。事前に `files.get` で `parents` を確認する。削除タイミング: 運用フローが変わって該当シーンが消えたら削除。feedback を「過去を振り返る材料」ではなく「現在の指針」として管理する。
project — 進行中の文脈を記録する
活動中のプロジェクトの状態——「このクライアントの提案方針を X から Y に転換した」「このプロダクト開発は Q2 で重点化」「このタスクは保留中」——といった直近の意思決定を置く。
更新頻度: 随時。状態が変わったら即座に更新。
揮発性が高い。プロジェクトが完了したら削除するか、アーカイブに移す。使い終わった project 情報を残し続けると、AI が古い方針を参照して誤った判断をする。
具体例:
# memory/project_client_alpha.md
---
name: 案件 Alpha の進行状況
description: 2026-05-10 時点での意思決定と方針
type: project
---
案件: クライアント Alpha との受託開発
現在の方針:
- スコープ: API 実装 + 管理画面、フロント側は後期ステージで統合
- 優先度: 高（Q2 コミットメント）
- リスク: クライアント側のデータベース移行が 2 週間遅延中
最近の決定 (2026-05-08):
- 仮 API に Zod でバリデーション層を追加することに合意
- 提案日程を 5/15 から 5/22 に延伸
次のアクション:
- 2026-05-15 までに管理画面のマックアップを確認削除タイミング: プロジェクト完了時。納品後は project ファイルそのものを削除し、必要な知見だけ feedback や reference に転記。
reference — 恒久的な仕様と方針を置く
アーキテクチャ方針・命名規則・外部ツール API の使い方・料金設定のルール——一度決めたら頻繁には変わらない情報だ。これは CLAUDE.md 本体や docs/ に置く。
更新頻度: 低。方針や仕様が本当に変わったときだけ。
具体例（CLAUDE.md から）:
## API 設計ルール
- REST エンドポイントは複数形で設計（/users, /documents）
- タイムゾーンはすべて UTC で保持、フロントで変換
- 金額は整数型（セント単位）で格納、表示時のみ 100 で除算
- 認証は Bearer token のみ（basic auth は禁止）削除タイミング: ほぼない。実装が本当に変わったときに更新する。
4. 実運用の落とし穴
分類を迷う情報の扱い
「これは feedback か project か」と悩む情報が必ず出てくる。「新しい客単価モデルに変わった」という情報は、運用方針なら reference だし、特定クライアント向けなら project だし、失敗から学んだルールなら feedback だ。
対処法: ルールはシンプルにしておく。「失敗から生まれた行動ルール は feedback、現在進行中の状態は project」と割り切る。完璧な分類を追求するより、どれかに置いて運用する方が効率的だ。迷ったら project に置いて、後で必要に応じて reference に昇格させる、くらいの柔軟性があってよい。
メモリの肥大化を防ぐサイズ感
分類があっても、各カテゴリが肥大化すれば同じ問題が再発する。対処法: 1 ファイル 1 トピック原則を守る。複数の関連 feedback があれば統合する。feedback/project ファイルのサイズに上限を設ける。目安として、「定期レビューで全体像が短時間に掴める量」がちょうどいい。
古い feedback と現在のギャップ
「2026-01 に起きた問題だが、2026-04 に運用フローが変わったので実は現在も有効か判断できない」という状態が出てくる。feedback を置きっぱなしにするとこれが積まる。
対処法: 発生日を明記したら、定期的に memory ぜんぶを読み返す習慣をつける。その時点で「この feedback はまだ有効か」「この project は完了したか」を判定し、古い情報を削除する。定期レビューを calendar に予定として組み込むと習慣化しやすい。
reference が変わったときの feedback との整合
ルール（reference）が変わったのに、それに対応した feedback が残ると矛盾が出る。「従来はこのルールだったから feedback があったが、もう不要」という情報は、reference 更新のたびに掃除が必要だ。
対処法: reference を更新するときは、関連する feedback があるか確認して整合を取る。「API 設計ルールを変更したなら、関連する feedback も削除 or 更新」という手順を明示化する。これを CLAUDE.md に「reference 更新時のチェックリスト」として記載するといい。
メモリの置き場の複雑性
「これは memory か docs か」という迷いも出てくる。specs/ に仕様書があるのに、同じ内容を memory/reference_*.md にも置く状態。
対処法: reference は CLAUDE.md 本体と既存の docs/ に寄せ、memory/reference_*.md は作らない。新しい知見が出たら、まず docs/ に置いて、docs のサイズが大きくなったら抽出する、くらいの流れでいい。memory ディレクトリは user / feedback / project だけで管理するとシンプルに保ちやすい。
5. Yakumo の適用例
八雲では業務横断的なエージェント基盤「Synapse」を Claude Code で運用している。複数の責任者エージェント（@director / @sales-director / @dev-director）が判断を下し、複数のスキル（営業自動化・書類生成・レポート集計など）が実行を担当する構成だ。
このシステムを安定させるために、4 分類メモリを活用している。
user には、ユーザー（CEO / 営業リーダー / 開発リーダー）の判断基準を記録している。「営業提案は金額と導入期間を必ずセットで説明する」「開発レビューのポイントは実装より設計の判断根拠を見る」——こうした個人スタイルが memory/user_*.md に入っていると、責任者エージェントがより正確な判断を下せる。
feedback には、過去に起きた自動化の失敗パターンを記録している。同じミスを繰り返さないためのルールが積まれている。「Google Apps Script で sheet.getRange().setValues() を使う前に、必ず行列の次元を確認する」「Gmail 下書き作成時は、必ず件名を 50 字以内に制限する（それ以上だと Slack 通知が切れる）」——これらはすべて feedback ファイルに発生日付とともに記録されている。
project には、進行中の案件や重点プロダクト開発の状態を置いている。「Q2 中は新規営業を抑制、既存クライアントの長期化に注力」「medallion（金融データ基盤）の日次自動化を安定稼働させる」——こうした方針が古いまま残ると、過去の優先度で判断が動く。完了したプロジェクトや優先度が変わったタスクの project ファイルは即座に削除する。
reference には、八雲のプロダクト定義・スキル仕様・API 設計ルールを CLAUDE.md に記録している。「Synapse スキルは config/ 駆動とし、ハードコードを禁止」「Google Drive の共有ドライブ配下にのみファイルを作成、マイドライブは使用禁止」——これらは運用が始まってから現在まで変わっていない基本ルールだ。
このような分類があると、「メモリが大きくなってもどの情報が古い可能性があるか」が見える。定期レビューのときは project ファイルをすべて削除対象にし、feedback は発生日が一定期間以上前なら運用変更がないか確認してから保持判定する。
6. メモリ品質の長期維持
分類設計があっても、運用を怠ると効果は薄れる。長期的にメモリの品質を保つには、いくつかの習慣が必要だ。
定期レビューの習慣化：定期的（）にすべての memory ファイルを読み返し、以下を判定する。
- project ファイル：案件は完了したか。方針は変わったか。削除対象か。
- feedback ファイル：発生後の運用フローが変わったか。ルールは今も有効か。
- user ファイル：記述された判断基準は今も当てはまるか。
古い情報の積極的削除：「念のため残しておく」という考え方は避ける。確実に不要な情報は削除し、memory のシグナル・ノイズ比を高く保つ。
reference への昇格プロセス：feedback や project の中で「これは一般的なルールでは」と気付いたら、reference（CLAUDE.md / docs/）に移す。一度参照レイヤーに上がった情報は、めったに削除されない。
矛盾の検出と解消：reference が更新されたときに、関連する feedback/project に矛盾がないか確認。矛盾したルールが混在していると、AI の判断は不安定になる。
7. まとめ
AI のメモリ設計は、システム全体の信頼性を支えるインフラだ。「覚えていてほしいことを書いておく」という受動的な発想では足りない。何を・どこに・いつまで置くかの戦略が必要だ。
4 分類メモリ設計（user / feedback / project / reference）は、更新頻度と揮発性に基づいて情報を整理する方法だ。分類すること自体よりも、古い情報を定期的に削除する勇気が、長期的な精度を保つ鍵になる。
AI が「同じ失敗を繰り返さない」「古い判断に引きずられない」「判断のコンテキストが常に最新」という状態を保つには、メモリの更新と削除を習慣化することが不可欠だ。定期的に memory ディレクトリ全体を読み返し、肥大化と陳腐化を意識的に防ぐ。
地味な作業だが、この設計が積み重なってエージェント運用の安定性が生まれる。Claude Code の信頼性は、プロンプトの上手さより メモリの品質 に依存する場面が多い。