← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0060type: adrstatus: accepted
pagemode: Standardkruchten: Property/Executivescope: platformimplementation_status: Not Startedproposed_at: 2026-05-22 18:53approved_at: 2026-05-22 19:15 (Pipeline 通常 flow v2 …deciders: [email protected] (単独)business: meta
型付き辺: 出 5 / 入 0
関連: ADR-0058 ADR-0059 ADR-0062 ADR-0063 ADR-0055全体は INDEX →

ADR-0060: Claude Code auto memory システムの運用ルール (命名規約 / stale 検出 / clean-up) を確立

  • Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Property/Executive
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-22 18:53
  • 承認日時 (JST): 2026-05-22 19:15 (Pipeline 通常 flow v2 48/50 通過)
  • Review After: 2026-08-22 (3 ヶ月), 2026-11-22 (6 ヶ月), 2027-05-22 (1 年)
  • Deciders: [email protected] (単独)

コンテキスト

1.1 背景 (Background)

Claude Code の auto memory システムは ~/.claude/projects/<project-slug>/memory/ 配下に persistent file として保存され、MEMORY.md がインデックスとして機能する。直近 2 ヶ月で nav prefix 系 ADR (ADR-0055/0058/0059) の採択により memory の stale 化事例が発生し、運用ルール明文化の必要性が顕在化した。

1.2 現状 (Current State / As-Is)

明示的な運用 ADR がなく、命名規約・stale 検出・clean-up タイミングが暗黙運用となっている。本リポは memory 14 件 (2026-05-21 時点) が蓄積している。

実例 + 発生頻度予測:

  • 実測 n=1: project_adr0039_implementation.md の本文 + MEMORY.md L9 サマリーに「サイドバー 1.A.NN/1.I.NN 体系統一」と記載されていたが、ADR-0055 (2026-05-19) で <NS>.<group_number>.<page_index> 形式に刷新されて stale 化。handover 2026-05-20 セッションで sub session 側が偶然発見し PR #881 関連で修正
  • 構造的リスクの裏付け (proxy): 本リポは memory 14 件 (2026-05-21 時点) が蓄積。直近 2 ヶ月の nav prefix 系 ADR 採択 (ADR-0055/0058/0059) で 3 件の構造変化発生 → memory への波及 proxy で 年間 5-10 件の stale 発生想定
  • 集計手順 (再現可能化):
    1. gh pr list --search 'ADR-' --state merged で ADR merge 履歴取得
    2. 各 ADR で MEMORY.md 配下を grep し参照件数を抽出
    3. stale 化候補のうち実際に発覚した件数 / 件数全体 = stale 発生率

1.3 課題 (Problem)

  • 規約欠如により stale 化が偶発的発見に依存しており、ADR-0055 起因の stale が翌日まで未検出だった (PR #881 で事後修正)
  • memory 件数増加で stale 化リスクが累積し、新規 session 開始時の方針再発見コストが発生
  • 将来 AI Agent / 第三者参加時 (Jr 入社 2026-10 想定) の引き継ぎ手順が不明確

1.4 制約・要件 (Constraints & Requirements)

  • gitignored ディレクトリのため CI lint 対象外、週次手動実行を前提とする
  • Claude Code session 固有: 他 AI Agent (Gemini / GPT-4o) は同 memory システムを参照しない
  • 副作用最小化: 検証 script は WARN 出力のみ、自動削除や移動はしない
  • 既存 14 件への破壊的変更は避け、初回 PASS 確認可能な範囲に留める

1.5 目標 (Goals / To-Be)

memory の命名規約・frontmatter 必須フィールド・stale 検出 rule・clean-up タイミングを ADR で明文化し、scripts/memory-stale-check.mjs による週次検証を確立する。Non-Goals: Claude Code 全体への汎用適用、他 AI Agent への展開、memory システム自体の廃止。

決定

memory システムの運用ルールを ADR で確立する。具体策:

  1. 命名規約: <type>_<slug>.md 形式 (type ∈ {user, feedback, project, reference})
  2. frontmatter 必須フィールド: name / description / metadata.type (欠落時は skip-with-warning、削除しない)
  3. MEMORY.md インデックス書式: - [<title>](<file>) — <one-line hook> (Markdown List)
  4. stale 検出 rule:
    • R-MEM-1 (週次 grep): memory 内の ADR-\d{4} / PR #\d+ 参照が現存するか
    • R-MEM-2 (任意, PR 影響大時): memory 本文の具体ファイル / 関数 / flag 名の現存確認
  5. clean-up タイミング:
    • (a) 関連 ADR が Superseded → memory 更新 or 削除
    • (b) memory 主題が CLAUDE.md / docs に正式採用 → memory 削除 (重複防止)
    • (c) 6 ヶ月以上アクセスなし + 関連情報が古い → 削除候補レビュー
  6. 新 memory 起票時の事前確認: CLAUDE.md / 既存 docs / 既存 memory と重複しないか grep

判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 3-5 個選定)

#軸重要度 (係数)案件特有の解釈
1#reliable[Must] (×2.0)stale memory による誤情報伝播を防止できるか
2#maintainable[Must] (×2.0)運用ルールが明文化され、第三者引き継ぎが可能か
3#suitable[High] (×1.0)memory システム本来の persistent context 価値を維持するか
4#operable[High] (×1.0)週次運用負荷が許容範囲 (≤ 15-30 min) か
5#efficient[Medium] (×0.5)ROI が許容範囲か (long-term break-even)

K.O. criterion: Must 軸 (#reliable / #maintainable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

軸係数採択案 (ADR 化)案 X1 (CLAUDE.md 追記)案 X2 (現状維持)案 X3 (memory 廃止)
#reliable×2.04315
#maintainable×2.04223
#suitable×1.04431
#operable×1.03455
#efficient×0.52454
加重和 (正規化)0.7110.6110.5890.711
K.O. 通過 (Must ≥3)✓❌ (#maintainable=2)❌ (#reliable=1)❌ (#suitable=1)

加重和では X3 が同点だが、K.O. (#suitable=1) で不採用。採択案が唯一の K.O. 通過。

検討した代替案 (Alternatives Considered)

  • 採用案 (ADR で運用ルール確立) — Good: 暗黙運用の明文化、将来 AI Agent / 第三者参加時の引き継ぎ容易 / Bad: 個別 project 固有のため Claude Code 全体への汎用適用は限定
  • 案 X1: CLAUDE.md に運用ルールを追記 (ADR 化しない) — Bad: CLAUDE.md が膨張 (~200 行)、6-12 ヶ月後の再議論ありそうな決定は ADR 適切 (起案前 checklist Q1)。K.O. 不通過: #maintainable=2
  • 案 X2: 何もしない (現状の暗黙運用継続) — Bad: memory 件数増加で stale 化リスク累積、新規 session 開始時の方針再発見コスト。K.O. 不通過: #reliable=1
  • 案 X3: memory システム自体を縮小 / 廃止し CLAUDE.md / docs に一元化 — Bad: session 跨ぎ persistent context という memory 本来価値を捨てる、Anthropic 公式機能の放棄。K.O. 不通過: #suitable=1

影響 (Consequences)

5.1 正の影響 (Good)

  • 改修対象:
    • 既存 memory 14 件: frontmatter / 命名規約チェック + 違反箇所修正 (~30-60 min one-shot)
    • 新規 script: scripts/memory-stale-check.mjs (~80 行想定、regex + frontmatter parse)
    • MEMORY.md: インデックス書式統一 (現行ですでに準拠、追加修正なし想定)
  • 暗黙運用の明文化により、stale 化事故 (~30 min/件 × 5-10 件/年 = ~2.5-5h/年) の削減
  • session 開始時の運用方針再発見コスト ~5-10 min × ~50 sessions/年 = ~4-8h/年 の削減
  • 削減効果合計 6.5-13h/年
  • Jr 入社 (2026-10) 時の onboarding コスト削減で長期 break-even (2027 想定)

5.2 負の影響 (Bad)

  • 年間総運用工数 ~19-32h/年 ((15-30 min × 52 週) + (30 min × 12 月)) → 削減効果 6.5-13h/年 を上回り 短期は net cost (運用負担増)
  • 初期実装 ~1-2h + 既存 14 件規約準拠化 ~30-60 min
  • 個別 project 固有ルールのため他 project への流用性が低い

5.3 中立・トレードオフ (Neutral / Trade-offs)

  • 検証対象: ~/.claude/projects/<slug>/memory/ 配下全 .md ファイル (14 件、件数増加に従い拡大)
  • 波及範囲:
    • Claude Code session 固有: 他 AI Agent (Gemini / GPT-4o) は同 memory システムを参照しない → 影響なし (明示)
    • scripts/ への影響: 新 script 追加のみ、既存 script 修正なし
    • CI への影響: gitignored ディレクトリのため CI lint 対象外、週次手動実行
  • Decider: 代表取締役 (単独) / 事実上のレビュアー: 月次レビュー時の sub workspace audit / 将来 stakeholder: Jr 入社 (2026-10) 時の onboarding 説明先

運用上の罠: grep pattern 誤設定時の挙動

誤設定パターン影響対処
ADR-\d+ (桁数指定なし)ADR-1 や ADR-12345 も誤マッチADR-\d{4} で 4 桁固定
PR #?\d+ (# を optional)PR 123 / Issue #123 も誤マッチPR #\d+ で # 必須
case-insensitive 未設定adr-0055 等小文字表記を見逃しgrep -iE で大文字小文字無視
改行跨ぎ参照multi-line 参照 (例: ADR-\n0055) を見逃し想定外、コミット時に lint で防止

運用上の罠: frontmatter 欠落時の挙動

  • 検証 script の振る舞い: WARN 出力のみ、削除や移動はしない (副作用最小化原則)
  • 後任が陥りやすい罠: frontmatter 内 metadata.type が metadata: { type: ... } ネストでなく metadata_type: ... フラットに書かれているケース → YAML parse error、本実装で 両形式許容 + WARN
  • 監視ポイント: 月次レビュー時に WARN 件数の前月比トレンド (急増は規約変更の兆候)

運用上の罠: Stale 検出ルールの cost / false-positive 抑制

  • R-MEM-1 false-positive: memory 内の ADR-0099 が将来 ADR を仮置きで参照しているケース → ~~ADR-0099 (仮)~~ の打ち消し書式で明示、grep で除外
  • R-MEM-2 cost 制御: PR 影響大時のみ実行 (default skip)、判断基準は「ADR Mode: Critical or Standard かつ Implementation Status: Done」

運用上の罠: script 形骸化リスク (長期視点)

週次運用が継続すると 「WARN 放置 → 形骸化 → stale 化が再発」 という負債化シナリオが発生し得る。対策:

  • 早期警戒指標: WARN 件数が 3 週連続 ≥ 5 件 → 月次レビュー繰上げ実施 (運用疲れの兆候)
  • WARN 累積防止: 月初に「先月の未処理 WARN 件数」を MEMORY.md 末尾に記録、3 ヶ月で累積 10 件超なら ADR-0060 §撤退検討 (案 B: script 削除に降格)
  • 自動エスカレーション: GitHub Actions の weekly cron で scripts/memory-stale-check.mjs 実行、3 週連続 WARN ≥ 5 件で Issue 自動起票 (将来拡張)
  • Review After (3 ヶ月後 2026-08-22) 時の確認項目: (a) 週次レビュー実施率 ≥ 80%、(b) WARN 累積 < 10 件、(c) FP 率 < 10% — どれか欠落で運用見直し

5.4 コスト試算

項目数値
初期実装scripts/memory-stale-check.mjs 新規作成 ~1-2h (regex + YAML parse + 既存 14 件初回 PASS 確認)
既存 14 件の規約準拠化~30-60 min (frontmatter 欠落 / 命名違反の修正 one-shot)
週次運用~15-30 min (script 実行 + WARN レビュー + 必要な update)
月次レビュー~30 min (clean-up candidates 評価、6 ヶ月以上未参照件のレビュー)
年間総運用工数(15-30 min × 52 週) + (30 min × 12 月) = ~19-32h/年
削減効果session 開始時の運用方針再発見 ~5-10 min × ~50 sessions/年 = ~4-8h/年 + stale 化事故回避 ~30 min/件 × 5-10 件/年 = ~2.5-5h/年 = 合計 6.5-13h/年
ROI初期 ~2h ÷ (削減 6.5-13h/年 - 継続 19-32h/年) = net cost (運用負担増) だが、Jr 入社後 onboarding コスト削減で長期 break-even (2027 想定)

5.5 検証可能な完了条件

#観測可能な指標測定方法
1初検証 PR で memory 14 件全件 PASS (規約準拠)scripts/memory-stale-check.mjs の exit 0 確認
2stale 検出率 100% (新規 stale 化を 1 週間以内に R-MEM-1 で検出)故意 stale 化テスト memory を 1 件作成 → 翌週検証
3週次レビュー所要時間 ≤ 15 min3 ヶ月運用後の所要時間ログ平均
4false-positive 率 < 10%3 ヶ月の WARN 件数のうち真の stale = N、FP = M、M / (N+M) < 0.10
5月次 clean-up: 6 ヶ月未参照 memory が < 全件の 20%アクセス log (Claude session 記録) 集計
6memory 件数トレンド: 3 ヶ月後 ≤ 25 件 / 6 ヶ月後 ≤ 30 件 (上限到達で命名 sub-category 検討)月次カウント

撤退条件 (Rollback Plan)

撤退判断指標

  • 3 ヶ月後 (2026-08-22): memory 件数 / stale 検出件数を評価、運用負荷が高すぎれば ADR を Superseded 化
  • false-positive 率 > 30% (常態化) → 検出 script revert
  • memory 件数が 30 件超 → 命名規約 sub-category 追加検討
  • Claude Code 公式が memory 運用ガイドを公開 → 本 ADR を Superseded して公式準拠

memory ファイル復旧 / 退避手順 (3 段階)

段階対象具体手順影響範囲
(A) ADR Superseded 化のみ (memory 保持)本 ADR既存 memory ファイル群は touched せず、本 ADR Status を Superseded に変更memory は引き続き Claude が参照、運用は暗黙運用に戻る
(B) 検出 script 削除 + memory 保持scripts/memory-stale-check.mjs1. script を revert (PR で削除)
2. memory ディレクトリは無変更		週次運用負荷ゼロ化、暗黙運用復帰
(C) 全 memory アーカイブ + 廃止 (X3 案発動時)~/.claude/projects/<slug>/memory/ 全件1. tar czf ~/.claude/projects/<slug>/memory.archive_$(date +%Y%m%d).tar.gz ~/.claude/projects/<slug>/memory/ で全件 backup
2. ~/.claude/projects/<slug>/memory/ を空に
3. MEMORY.md のみ「memory 廃止済、復旧手順は本 ADR §撤退」の 1 行 placeholder で保持
4. 復旧手順: tar xzf <archive>.tar.gz → MEMORY.md インデックス再生成 (各 .md の name: / description: から再構築)		Claude session 跨ぎ persistent context の喪失、CLAUDE.md / docs への一元化前提

Confirmation (準拠確認 / Fitness Function)

  • 検証手段 1 (機械): scripts/memory-stale-check.mjs 実行 (R-MEM-1 週次 / R-MEM-2 PR 影響大時)
    • R-MEM-1: memory 内の ADR-\d{4} / PR #\d+ 参照が現存するか grep + frontmatter parse
    • R-MEM-2: memory 本文の具体ファイル / 関数 / flag 名の現存確認 (PR 影響大時のみ、判断基準は ADR Mode: Critical or Standard かつ Implementation Status: Done)
  • 検証手段 2 (手動): 月次レビューチェックリスト (clean-up candidates / FP 率トレンド / 件数推移)
  • 実行頻度: R-MEM-1 週次 (cron or 手動) / R-MEM-2 PR 影響大時のみ / 月次レビュー 1 回
  • 違反時の対応: WARN で出力のみ、自動削除なし。該当 memory を起案者が手動 update or 削除候補化

参照 (References)

関連 ADR と memory への波及 (個別 Conflict 確認)

ADR採択日memory への波及対象Conflict 有無 / 整合性確認
ADR-0055 (nav prefix 刷新)2026-05-19project_adr0039_implementation (1.A.NN/1.I.NN 表記 → stale 化)✅ PR #881 で修正済、本 ADR の起案根拠
ADR-0058 (frontmatter-lint Rule Reference SSoT)2026-05-22なし (memory frontmatter とは別系統 — adr-lint Phase 4-b は docs/ 配下、memory は ~/.claude/projects/ 配下)✅ Conflict なし、別 namespace
ADR-0059 (docs-nav-lint R5)2026-05-22なし (docs/index.md / docs/_config.json 整合性検証で、memory には波及せず)✅ Conflict なし、別 namespace
将来候補: Anthropic 公式 memory 運用ガイドTBD公開時に本 ADR を Superseded、命名規約 / stale 検出基準を公式準拠化公式が公開された時点で再評価

ADR-0058/0059 は「nav prefix 系」と一括りで参照されがちだが、本 ADR の memory namespace とは 物理的に別系統 (Claude ~/.claude/ vs プロジェクト docs/)。直接の Conflict 可能性なし。

関連 PR / 外部資料

  • PR #881 (2026-05-20): stale memory project_adr0039_implementation の修正記録
  • 本セッション (2026-05-20〜21) 追加 memory 4 件: project_docs_swap_summary_index_layout / feedback_force_push_via_user_bang_prefix / reference_handover_prompt_location / project_doc_ops_backlog_section
  • CLAUDE.md §Self-improvement loop (memory → CLAUDE.md 昇格パターン)
  • 将来統合候補: Anthropic 公式 memory 運用ガイド (公開時に本 ADR を Superseded)

8. 参照: Pipeline 審査履歴 (2026-05-22 実行時, 通常 flow)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v1 (67 行) で 37/50 差し戻し → 6 採点項目に対応する改善反映 v2 → 48/50 で Standard 閾値 40 + Critical 閾値 45 双方クリア。ADR-0056 §8 / ADR-0058 §11 / ADR-0057 §8 / ADR-0059 §11 で確立した §audit history パターンの 第五適用例。デフォルトでは折りたたまれており、▶ をクリックで展開する。

📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 48 / 50, v1 37 → v2 48 +11 pt) — クリックで展開

Gate 0 Triage

  • needsAdr: true / triageMode: Standard
  • 理由: 命名規約 + stale 検出 + clean-up の 3 軸統治、memory 14 件への横断影響、CI 連動はない (gitignored) が週次運用ルール化

Gate 1 Socratic

  • pass: true (追加質問 0 件、v2 改善反映で context 十分)

Gate 2 Consistency: verdict PASS

  • 既存 ADR との整合性 OK (ADR-0055 / 0058 / 0059 への参照、Supersede なし、本 PR §References で個別 Conflict 確認を明記)
  • ADR-0058/0059 との namespace 分離 (~/.claude/ vs docs/) を §References で明示

Gate 3 Parallel Review

  • 3 vendor (Gemini Flash / Claude Sonnet / GPT-4o) からの詳細指摘は §改善余地 に要約

Gate 4 Scoring: 48 / 50

#採点項目点数コメント
1問題定義5実測 n=1 (ADR-0039 stale + PR #881) と proxy (memory 14件、年 5-10 件想定) を併記、集計手順も再現可能化。
2代替案5採用案 + X1/X2/X3 を Good/Bad/K.O. 判定明示。網羅性十分。
3判断基準5Q42 9 タグから 5 軸選定、係数 + K.O. + 加重和の正規化値まで計算済み。
4過去決定との整合性4ADR-0055/0058/0059 と PR #881 を参照、Supersede 可能性まで言及。ただし ADR-0058/0059 は「nav prefix 系」と一括りで具体的差分・整合性確認が薄く、Conflict 有無は未検証 (本 PR で §References 個別整合表を追加)。
5影響範囲5改修対象 / 波及範囲 / ステークホルダーを明示。
6運用上の罠5grep pattern 誤設定 4 パターン、frontmatter ネスト/フラット両形式許容、FP (打ち消し書式) まで具体的に検証。
7ロールバック53 段階 (A/B/C) を具体コマンド + 復旧手順付きで記載。
8コスト試算5全項目を数値化、ROI が net cost であることも誠実に明記。
9完了条件56 指標を表で整理、故意 stale テスト手順まで設計。
10長期的影響43 ヶ月評価 + Jr 入社 + break-even (2027) と時間軸あり。ただし明示的「Review After: YYYY-MM-DD」項目が無く、6 ヶ月後の負債化リスク (運用疲れで script 形骸化) の言及が薄い (本 PR で Status 直下に Review After 明示 + §5.3 script 形骸化対策追記)。

合計: 48 / 50 (Standard 閾値 40 / 50 → PASS, Critical 閾値 45 / 50 → PASS)

v1 (37/50) → v2 (48/50) 改善効果

項目v1v2改善反映
影響範囲3514 件移行 + 新 script ~80 行 + AI Agent 影響 (Claude 固有) + Decider/レビュアー明示
運用罠35grep regex 4 パターン表 + frontmatter 両形式許容 + 監視ポイント
ロールバック35A/B/C 3 段階手順 + 復旧 step
コスト試算35初期 1-2h / 週次 / 月次 / 年間 19-32h + ROI 分析
完了条件356 観測指標 (stale 検出率 100% / 週次 ≤ 15min / FP < 10% / 件数 ≤ 30 / 6 ヶ月未参照 < 20%)
問題定義45proxy 集計手順 + 年間 5-10 件想定
過去決定との整合性44(本 PR で 5 へ向上、§References 個別整合表)
長期影響44(本 PR で 5 へ向上、Review After 明示 + §5.3 script 形骸化対策)

v1 → v2 改善: +11 pt (37 → 48)。

改善余地 (本 PR で反映済)

#指摘反映先効果
1§9 ADR-0058/0059 との個別 Conflict 確認 (各 ADR でどの memory が波及対象だったかの差分整理)§References を新規 table 形式に再構成、各 ADR ごとに「波及対象 / Conflict 有無 / namespace 分離」を整理過去決定整合性 4/5 → 5/5 見込
2Status 直下に Review After 明示 + §5.3 script 形骸化リスク (運用疲れで WARN 放置) 対策追記Status header に Review After 3 段階 (3/6/12 ヶ月) 明示 + §5.3 に「script 形骸化リスク」subsection 新設 (早期警戒指標 / WARN 累積防止 / 自動エスカレーション)長期影響 4/5 → 5/5 見込

改善効果見込: 48/50 → 50/50 達成可能性。

Status 遷移

  • v1 起案 (2026-05-22 KV 投入) → Pipeline 通常 flow 37/50 差し戻し
  • v2 改善 (6 採点項目に対応) → Pipeline 再投入 → 48/50 通過 → auto-PR #910 生成 (Proposed)
  • 本 PR で Status: Proposed → Accepted に更新、改善余地 2 件 (§9 個別整合 + §Review After + §5.3 形骸化対策) を同時反映