AI駆動開発の実運用ノート

配布資料の目次　›　設定カタログ

配布資料 2404 — メモリ三層アーキテクチャ

AI の記憶は、書きすぎると壊れます。

実際、2通りの壊れ方をしました。長い作業記録を貯め込んで読み出しがサイズ超過で止まったのと、 「コミット成功」に見えるのに中身が引き継がれていなかったのとです。

だから設計するのは「何を覚えさせるか」ではなく、何を、どこに書くかになります。 ここでは実際に使っている三層と、その壊れ方を書きます。

全体像: 三層の役割分担

層 実体 書くもの 書かないもの
① 自動メモリ プロジェクト別 memory ディレクトリ（markdown・リポジトリ外） 横断ルール（feedback_*）・Epic 状況の入口・設計正本へのポインタ 逐次の作業ナラティブ
② プロジェクト記憶DB リポジトリ内 SQLite（MCP 経由・git で端末間共有） caveat / learning / 設計判断のポインタ / 最新引き継ぎ要点1件（<1500字） セッションの実装詳細・変更ファイル一覧
③ イシュートラッカー Linear のイシューコメント 実装詳細・変更ファイル・検証結果・テスト結果（正本） —

設計原理: イシュー管理ツールは AI の記憶を補って余りある外部記憶であり、この連携の設計が AI 活用の成否を分ける（本カタログの中心テーゼ）。「すべてを記憶する」は破綻する。記憶は検索コストと鮮度で階層化し、詳細は追跡可能な正本（イシュー + git 履歴）へ押し出す。

① 自動メモリ（auto-memory）

  • 実測 129 ファイル。内訳: feedback_* 51件（ユーザーの是正・教訓）/ project_session_* 55件（旧方式の名残・特定期間に集中）/ project_* 17件（Epic別）/ reference_* 3件 / 入口 MEMORY.md ほか
  • MEMORY.md 運用方針: 1エントリ1行・全体 ~24KB 以内。「入口インデックス」に徹し、本文は個別ファイルへ
  • feedback_* の書式: 事実 + Why（なぜそうするか）+ How to apply（次にどう適用するか）。是正の理由まで残すことで同種の判断に汎化する
  • 歴史的教訓: 初期は session ごとのナラティブを蓄積していた（session_* 55件が痕跡）→ 肥大して参照されなくなり、「逐次詳細はイシューコメント正本」方針へ移行した。教材ではこの失敗と移行こそを教える

② プロジェクト記憶DB（linksee-memory）

  • SQLite DB をリポジトリ内に固定し、git commit/push で別端末と記憶を共有する構成
  • git hook 4種で整合性を守る: pre-commit（WAL を main DB へ checkpoint 統合し再 stage）/ post-merge・post-checkout（DB 更新時に MCP プロセス kill して再読込）/ pre-push（WAL 未統合を検出して abort）。hook は clone で復元されないため SessionStart hook が自動取付（自己修復）
  • 事故2件が運用ルールを形成:
    • WAL 滞留事故 — SQLite WAL モードでは書込が -wal ファイルに滞留し、手動 git add memory.db では無変更に見えて取りこぼす。→ 同期は checkpoint→add→commit→push を一括する専用スクリプト経由のみに
    • recall 停止事故 — 長文の蓄積で recall 出力が 151KB を超えツールが機能停止。→ 書込は要点のみ（1500字警告 hook）+ recall は entity 名指定で絞る + session entity は最新1件のみ保持
  • 単一書込み制約: 同時に複数端末・複数セッションから書き込まない（SQLite）
  • 移植のヒント: 記憶を git で運ぶ設計は強力ですが、DB ファイルの「見かけ上無変更」問題と読み出しサイズの上限を、最初から設計に入れておいてください

③ イシュートラッカー（Linear）を記憶の正本にする

  • セッションで何をどう実装・検証したかは、記憶DBでなく該当イシューのコメントに書く（テスト項目・OK/NG・スクショ要約・変更ファイル）
  • 利点: 文脈（イシュー本文・PR リンク）と同居 / 検索可能 / 人間のレビュー動線と一致 / 記憶層が肥大しない
  • git 履歴 + イシューコメントで「いつ・なぜ・どう変えたか」が再構成できるため、AI の記憶は「入口と教訓」だけで足りる

セッション引き継ぎの実runbook（題材プロジェクトの実運用）

  1. SessionStart hook が最近更新 entity 上位8件を自動提示
  2. 記憶DBを entity 名指定で個別 recall し全件読み切ってから引き継ぎ完了とする（広い自然文 query は出力肥大で禁止）
  3. auto-memory の MEMORY.md も参照（片方だけは片落ち）
  4. セッション終了時: 記憶DBの同期スクリプト実行 + 持ち越しキュー（In Review）の整理

feedback メモリの書き方

教訓を残すときの書式がこれになります。 ポイントは、「何を怒られたか」ではなく「なぜ・次にどうするか」を書くことです。

---
name: feedback-nonstop-is-not-skip-verification
description: 「ノンストップで」は待機ゼロの意味であり、検証省略の許可ではない
metadata:
  type: feedback
---

12件の PR を連続マージする際、「ノンストップ進行」を優先して
ステージングでのブラウザ検証を省略し、3件が完了から差し戻された。

**Why:** 「ノンストップ」はタスク間の待機をゼロにする指示であって、
工程を飛ばしてよいという意味ではない。完了の定義は
「利用者に価値が届く最終画面まで実データを通し、証拠を残すこと」で変わらない。

**How to apply:** 速度を優先する指示を受けたときは、
短縮してよいのは待ち時間だけで、検証の段は減らさない。
省略する必要が本当にあるなら、省略する段を名指しして先に確認を取る。

関連: [[feedback-done-requires-evidence]]

Why の行を隠して読んでみてください。

残るのは「検証を省略して3件差し戻された」という事実だけになります。 これだけでは、まったく同じ状況が来ない限り思い出しようがありません。

理由まで書いてあるから、似た別の場面にも応用が効きます。 「怒られたことリスト」は汎化しません。

手を動かすなら

  • feedback メモリを1件、この型（事実 → Why → How to apply）で書いてみてください
  • 「どの層に書くべきか」を振り分けてみる。実装詳細・教訓・引き継ぎ要点・参照 URL の4つはどこへ行くか
  • わざと肥大させた記憶を整理する。重複・矛盾・陳腐化を除く
この資料を出典にしている回