Communitygithub.com

jau123/claude-memory-manager

プロジェクトの記憶ライブラリを監査可能にし、一貫した命名を維持し、長期間にわたって情報の劣化を防ぐClaude Codeスキルです。

claude-memory-manager とは?

このスキルは、Claude Codeの自動記憶機能(auto-memory)とCLAUDE.mdを体系的に管理し、プロジェクトの知識ベースを検索可能で信頼性の高い状態に保つための包括的なフレームワークを提供します。開発者は、単なるメモ作成ではなく、「何を記憶する価値があるか」を判断するための意思決定木や、記憶の種類(フィードバック、リファレンス、プロジェクト)に応じた適切な保存先(コードコメント、` .claude/rules `、メモリファイル、CLAUDE.md)を選択する4段階のルーティングを利用できます。主要な機能として、曖昧なリクエストから記憶すべき項目を抽出する「候補評価モード」、既存の記憶を更新して断片化を防ぐ「更新優先モード」、記憶インデックス(MEMORY.md)のサイズ制限(200行/25K文字)を監視し静かな切り捨てを防止するルール、そしてオプションの監査スクリプトによるコンプライアンスチェックが含まれます。このスキルはClaude Codeでの使用を想定して設計されており、プロジェクトが成長しても知識が散逸せず、長期にわたって一貫したアクセスを実現します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add jau123/claude-memory-manager

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

メモリ管理

Claude Codeの自動記憶とCLAUDE.mdへの書き込み方法。プロジェクトが成長してもライブラリが検索可能な状態を保つための手順。

クイックリファレンス

ユーザーの発言実行すること
「記一下」(曖昧、複数候補)/「复盘(ふりかえり)」/「開發完了看看有什麼值得記的」→ モード1:候補評価(複数候補の絞り込み)
「記一下今天那個 X 坑」(具体的な1件)/ 重大バグ修正後 / セキュリティインシデント対応後 / 単一の意思決定で自明ではない結論が出た場合→ モード2:新規メモリ作成(直接実行)
「更新這個 memory / 修正 X 的結論」→ モード3:既存メモリの更新(新規作成より優先)
追加するセクションが100行を超える、またはファイルが既に4つ以上のH2トピックを持つ場合→ ルール6:分割優先(更新しない)
「改 schema / 加新 type / 改記憶結構」→ モード4:構造変更(既知の問題リストを必読)
「新項目零記憶起步 / 如何開始」→ モード5:ゼロ記憶ブートストラップ
「記憶系統看起來亂了 / audit」→ プロジェクトルートに scripts/audit-memory.sh があれば実行、なければ templates/audit-memory.template.sh を参考に自作

重要なルール

ルール1:事実はmemoryへ、方法はskillへ

memoryファイルには「Xの落とし穴を踏んだ」「業界Yのデータ」「プロジェクトZの状態」を格納。本skillには「何を記憶するか / どう書くか / どう整理するか」の方法を格納。スキーマ規範をmemoryに書いてはいけない(カテゴリエラー)。

ルール2:まず「記録する価値があるか」を判断し、次に「どこに記録するか」を判断する

すべての発見を記録すべきではない。判断ツリー:

シグナル記録すべきか
同じ落とし穴を2度踏んだ✅ 必ず記録
レビューで自明でない判断が見つかった✅ 判断の「Why」を記録
業界比較 / 実測数値(再利用可能なベースライン)✅ 記録
1回限りのデバッグで、修正済みで再利用価値なし❌ 記録しない(コミットメッセージで十分)
一時的な状態で変化する⚠️ 持続性を見極め、長期のものだけ記録
低頻度だが致命的(半年読まれていないが唯一の真実)✅ 残す —— 30日未アクセス ≠ 時代遅れ。削除基準は「トピックが消滅/置き換えられたか」であり、「どれだけ読まれていないか」ではない

「どこに記録するか」の判断 —— 近接性トリガー4段階ルーティング:

まず直交する質問をする:「将来この事実が必要になる時、あなたは特定のコード位置を見つめていますか、それともファイルを横断する決定/特定のエラーの調査をしていますか?」

トリガー条件格納先メカニズム
特定の行/ブロックに注目しており、Whyが一言で説明できるインラインコードコメント(その行のすぐ上)ファイル変更時に100%遭遇、インデックスコスト0
特定のファイル群に紐づく複数箇所の契約/チェックリスト.claude/rules/<x>.md + paths: frontmatter一致するパスに遭遇すると自動でcontext注入
トリガーがシナリオ/エラー/特定の問題、または複数ファイルにまたがる、または単一のリポジトリファイルに属さない(プラットフォーム/SDKの落とし穴)memory(本システム)descriptionの一致
すべてのセッションで守るべきルール(コマンド、技術スタック、協業の好み)CLAUDE.md常駐

特定ファイルに紐づくfeedbackはデフォルトでSPLIT:ファイルローカルな核心はインラインコメントへ(書く前にそのコードをgrep、多くの場合既に同等のコメントあり)。memoryには「ファイル横断で再利用可能な原則 + そのファイルへのポインタ」のみ残す。

過剰な移行を防ぐ3つのガードレール(デフォルトでmemory、移行は最小限に):

  1. 特定のファイルを取り除いても汎用的な教訓が残る → memoryに残す(例:「optionalフィールドをクリティカルパスの判断に使うな」。特定ファイルは単なる例、原則は移行可能)
  2. プラットフォーム/SDKの振る舞いが複数ファイルにまたがって再現する → memoryに残す(コードに意味がある場合でも)
  3. 墓石(Xは廃止→Yを見よ)/ 調査SOP / ビジネス経済的推論 → memoryに残す(トリガーはアーキテクチャ/シナリオ層)

実証(175ファイルのプロダクションコードベースの全監査):約15%のエントリのみが単一ファイルに紐づいており、そのうちのほとんどはファイルローカルな核心が既にコードコメントに存在していた —— 「移行」とは大抵memoryの冗長コピーを削除することであり、本当の移動ではない。

.claude/rules/*.md の書き方(プロジェクト .claude/rules/ に配置、git管理 → マシン間/worktree間で共有):

---
description: このルールが何を管理するか一文で
paths:
  - src/components/SomeDialog.tsx
  - src/lib/providers/*.ts          # glob対応
---
上記パスに一致したときに自動注入される契約/チェックリストの本文(多箇所gotcha)。

⚠️ ネイティブルール注入の既知の制限(2026-07確認、anthropics/claude-code issues):paths: ルールはRead時のファイル一致でのみ注入され、Write/新規ファイル作成時には注入されない(#23478)。ユーザーレベルの ~/.claude/rules/ の paths: は無視され、プロジェクトレベルのみ有効(#21858)。「新規ファイル作成時にも必ず有効にすべき」契約はCLAUDE.mdに残し、rulesだけに頼らない。


ルール3:既存のメモリを優先的に更新し、新規作成は避ける

トピックに関連する既存ファイルがあれば、そのファイルを更新する(セクション追加またはchangelogセクション追加)。トピックが完全に直交する場合のみ新規作成。新規作成はトピックの断片化を招き、情報を見つけにくくし、忘却につながる。


ルール4:memoryは自動ロードされない、descriptionがヒット率を決める

topicファイル(memory/*.md)はセッション起動時にロードされない。ClaudeはMEMORY.mdインデックスのdescriptionを読み、読むかどうかを判断する。descriptionにはシナリオキーワードと核心結論を混在させること。そうでなければClaudeは印象でどのmemoryを読むか決めてしまう。

ネイティブメカニズムの確認(2026-07、公式docs/en/memory):ベクター/セマンティック自動検索はない —— 発見はすべて「MEMORY.mdのインデックス行 + ファイル名」に依存。ClaudeはReadでオンデマンドに読み込む。読み込み時にharnessは「このmemoryはN日前のものです」という期限情報を注入する。インデックス行のフックの質 = ヒット率のすべて。これはネイティブの動作であり、本skillの規約ではない。


ルール5:skill自身も自身が教える規範に従うこと

本skillが ## Why セクションを書くように指示するなら、本skill自身も各ルールのWhyを説明すべき(それらはすべてこのファイルにインラインで記載されている)。

スコープ注意:ルール5の適用範囲は「方法/書き方/Quick Referenceの形式など」であり、スキーマルールには再帰的に適用されない。スキーマ(命名/frontmatter/Whyセクション)はmemoryファイルのためのものであり、skill自身には適用されない。Skillはmemoryファイルではない。


ルール6:いつ分割して更新しないか(単一ファイル/単一グループの過負荷防止)

ルール3は更新を優先するが、閾値がある。分割をトリガーするシグナル(ファイルレベル):

シグナルアクション
既存ファイルが100行超で、追加する内容が元のトピックと直交する新しいファイルに分割、詰め込まない
既存ファイルが既に4つ以上のH2トップレベルセクションを持ち、新しい内容が5つ目の独立トピックに該当する新しいファイルに分割
セクション追加後の total 行数が150行を超える分割するか評価(トピックの独立性を確認)
追加する内容が元のファイルのタイトル/descriptionと一致しない新しいファイルに分割(元のファイルは宣言されたトピックに集中すべき)

グループの過負荷(インデックスレベル):

シグナルアクション
MEMORY.mdの特定の大グループのエントリ数が15以上hub memory(セクションインデックス)の作成を検討し、フラットなインデックスを置き換え、新しいエントリはhubにぶら下げる
グループのdescriptionをすべて読むと25行を超える同上
MEMORY.mdが23,000文字(wc -m)または190行を超える🔴 ネイティブのハードリミット = 先着200行または25K文字(公式docsでは「25KB」と表現されるが、実測ではstring length=文字数で動作:27,972文字/37.9KBのインデックスがちょうど25,000文字で切り捨てられた。バイトベースでは約35%早く切り捨てられる)。超過分は静かにロードされない。⚠️ wc -c(バイト)で見積もらないこと:中国語UTF-8は1文字3バイトのため、約35%過大評価する。上限に近づくとharnessが警告を注入する。Only part of it was loaded が表示されたら、既にインデックスが失われている。
単一のインデックス行が ~160 文字を超えるdescriptionに詳細を詰め込みすぎ → topicファイルに移動するかコードコメントに落とす。インデックスには「シナリオキーワード + 核心結論」のみ残す

なぜグループの過負荷も管理する必要があるのか:ClaudeはMEMORY.mdのインデックスでdescriptionをスキャンしてヒットする。グループ内に20以上のdescriptionがあると、1回のスキャンで見逃す可能性がある。hubを作成後、グループインデックスは1行でhubを指すようになり、hub内でトピックマップを提供する。

なぜインデックス全体が最も危険なのか:単一ファイル/グループの過負荷は「ヒット率の低下」に過ぎない。しかしインデックス全体が切り捨てられると、末尾のエントリ全体がロードされずヒット率はゼロになり、静かにエラーも発生しない。したがって ⭐⭐⭐ クラウンのエントリはMEMORY.mdの上部に配置すべき(切り捨てに対する保険)。

制限超過/肥大化時のスリム化優先順位(descriptionの圧縮は最も悪い最初の手段であり、ヒット率を自ら損なう):

  1. まず移行:ファイルローカルなエントリ → インラインコメント / .claude/rules(インデックスが小さくなりかつヒット率が向上、ルール2の4段階ルーティング参照)
  2. 次に削除:真の墓石(トピックが消滅/置き換えられ、復活防止価値もないもの)
  3. 次に並び替え:⭐⭐⭐ をMEMORY.mdの上部に移動
  4. 次に階層化:インデックス行を重要度で予算配分 — クラウンエントリ ≤160文字、通常エントリ ≤110文字、長尾低頻度エントリは1行に複数リンクを集約(サブトピック → [a](f1.md) · [b](f2.md)、1行で5-10ファイルを収容)。また、リンクラベルはtypeプレフィックスを除いた短い名前を使用([foo-bar](feedback_foo_bar.md))、完全なファイル名を繰り返さない。各行12-45文字節約。
  5. 最後に単一のdescriptionの情報量を圧縮

歴史的な失敗事例(参考、ルールの一部ではない)

  • 単一ファイルの過負荷:1つのreferenceファイルが130行以上になり、7-8個の独立したサブトピック(インフラ、cronリスト、障害マニュアルなど)を詰め込んでいた。MEMORY.mdのインデックス説明が不十分で、Claudeが特定のサブトピックにヒットできなかった。5つの独立したmemoryに分割後、各トピックが正確にヒットするようになった。
  • グループの過負荷:あるグループに20以上のエントリが蓄積され、新しいセッションでClaudeがインデックスをスキャンする際に見過ごし、タスク処理で車輪の再発明を繰り返した。hub memoryを作成して関連エントリを集約 → 解決。
  • インデックス全体の過負荷:MEMORY.mdが43KB(約31K文字、25K文字上限超過)になり、93のdescriptionがそれぞれ400-900文字。起動時に静かに切り捨てられ、末尾の ⭐⭐⭐ エントリが読み飛ばされ、ある調査で設計通りに動作しているメカニズムをバグと誤判断した。教訓:descriptionは詳細であればあるほど良いわけではない。詳細すぎるとインデックスを圧迫し、かえってヒット率を損なう。
  • バイト/文字の混同による誤調整:過負荷対策として警告ラインをバイト(wc -c)で32KBに設定したが、harnessは文字で実行(中国語1文字3バイト)→ バイトラインではまだ余裕があると思い込み、再びインデックスが切り捨てられた。教訓:harnessと合わせるには同じ単位を使用し、監視は wc -m を使うこと。

ワークフローモード

モード1:候補評価(複数候補、絞り込みが必要)

トリガーシナリオ(複数候補 → モード1の絞り込みが必要):

  • 機能開発完了 / 長時間デバッグ完了 / レビュー完了
  • 不正利用対応完了(複数の判断ポイント+教訓がある可能性)
  • セキュリティインシデント対応完了 / 障害特定完了
  • ユーザーが「記一下」(曖昧で、特定の落とし穴を指していない)

単一の具体的な内容は直接モード2へ:ユーザーが「記一下今天那個 wildcard bug」/「記一下連接泄漏的故障手册」と言った場合 → 既に単一の項目が明確 → モード2でありモード1ではない。

手順:

  1. 今回のセッションの重要なポイントを振り返る(ユーザーの修正、レビューでの発見、予想外のバグ、業界比較の問い合わせ、単一意思決定の自明でない結論)
  2. 個別にルール2の判断ツリーを適用し、記録に値するものを抽出する
  3. 各候補について、以下を判断:
    • 既にmemoryファイルがカバーしているか?(MEMORY.mdインデックスをgrep)→ あればモード3の更新へ、なければモード2の新規作成へ
    • 追加する内容がルール6の分割トリガーラインを超えていないか?→ 超えていれば新しいファイルに分割
    • CLAUDE.mdに入れるべきか、memoryに入れるべきか?(下記テーブル参照)
  4. ユーザーにリストを確認:「新規提案 / 更新提案 / 分割提案」の候補を列挙し、ユーザーの確認を待ってから書き込む

memory vs CLAUDE.md の境界:

内容の性質格納先
学んだ具体的な落とし穴(SDKバグ、プラットフォーム制限、業界データ)memory feedback_*
トピックの詳細なリファレンス / 標準手法 / プロセスドキュメントmemory reference_*
状態的な事実(進行中の作業、一時的な設定、現在のアーキテクチャスナップショット)memory project_*
すべてのセッションで守るべきルール(コマンド、技術スタック、協業の好み)CLAUDE.md
特定のファイル操作時にのみ必要なルール.claude/rules/*.md に paths frontmatter を追加

モード2:新規メモリ作成(標準フロー)

ステップ0:まず近接性トリガーを確認(ルール2の4段階ルーティング)

書き込む前に、それが本当にmemoryに入れるべきかを確認する:単一ファイルに注目 → インラインコメント。特定のファイル群の契約 → .claude/rules + paths。シナリオ/ファイル横断/プラットフォームの落とし穴 → 初めてmemoryに入れる。特定ファイルに紐づくfeedbackはデフォルトでSPLIT(核心はコメントへ、memoryには横断原則+ポインタのみ)。詳細はルール2を参照。

ステップ1:typeを決定

Typeいつ使うか必須情報
feedback学んだ落とし穴(SDKバグ / プラットフォーム制限 / ユーザー好み)理由(なぜその結論か)+ いつ再利用するか(トリガーシナリオ)
referenceトピックの詳細リファレンス / 標準手法 / 業界比較 / 再利用可能なパイプライン理由セクションは必須ではない(記述的)
project状態的な事実(アーキテクチャスナップショット、進行中の作業、経済分析)理由セクションは必須ではない(状態的)

feedbackの必須情報の表現形式(いずれかで可):

  • 独立したセクション:## Why または同義の中語 ## 根因 / ## 原因 / ## 教訓 / ## 為什麼(監査で受け付け)
  • 太字インライン:**Why**: / **根因**: (短い結論の場合も可)
  • descriptionまたは##タイトルにインライン(結論自体が既に理由+いつ再利用するかを暗示している場合、例:❌/✅ 比較表)

いつ再利用するかの情報:単独の ## How to apply セクションでも、descriptionにシナリオキーワードが含まれていても可(例:tab 切替 / mutation が既にトリガーシナリオを示している)

ステップ2:ファイル命名

<type>_<topic>[_<modifier>].md すべて小文字、アンダースコア区切り:

  • ✅ feedback_supabase_from_deadlock.md
  • ✅ reference_supabase_egress_favorites_refactor.md
  • ❌ feedback-supabase-deadlock.md(ハイフンを使用)
  • ❌ FeedbackSupabaseDeadlock.md(キャメルケース)
  • ❌ _schema.md(アンダースコア始まりは隠しファイルとして扱われ、Claudeが自発的に読まない)

ステップ3:frontmatterを書く

---
name: kebab-case-slug
description: シナリオキーワード + 核心結論
type: feedback | reference | project       # フラット(推奨)
# または:
# metadata:
#   type: feedback | reference | project   # ネスト(互換性のある書き方)
---

type フィールドの位置:type: フラット(推奨)または metadata.type: ネストのどちらでも受け付け。監査スクリプトは両方を認識する。新規ファイルはフラットを優先し、既存の大多数と揃える。

descriptionのスタイル判定:

✅ 良いdescription❌ 悪いdescription
ブラウザ側supabase.from() mutationがタブ切替後にデッドロック、fetch()でREST APIを呼ぶ必要があるSupabase関連の問題
CF Image Transformations 失敗 7日間キャッシュ / cf-resized err= / FavoriteCard retry pattern画像が時々表示されない
RLSポリシーは (SELECT auth.uid()) でラップする必要がある、さもないと行ごとに再評価されるRLSパフォーマンス最適化

判定基準:Claudeがdescriptionを読んだときに、「これはXシナリオで参照すべきY結論だ」と即座にわかるかどうか。

ステップ4:本文を書く

feedbackクラス(理由+いつ再利用するかを必須):

# タイトル(What — 一文で)

[核心結論 + 1-2段落の背景]

## Why(または同義:## 根因 / ## 原因 / ## 教訓 / ## 為什麼)

[なぜこの結論か — 踏んだ具体的な落とし穴、レビューでの発見、ユーザーの好み]
**なぜ必須か**:理由セクションがないと、同じ判断を次回再議論する際に同じ誤った結論に達する可能性がある。

## How to apply(省略可、descriptionに既にシナリオキーワードが含まれている場合)

[いつこの情報を再利用するか — トリガーシナリオ、チェックリスト、回避手順]

reference / projectクラス:セクション構造は必須ではない。トピックに応じて自然に構成。

ステップ5:MEMORY.mdインデックスに追加

  • 既存の大グループを選択し、新しいグループは作成しない
  • descriptionをグループ内の適切な位置に追加(重要度が高いものは ⭐⭐ / ⭐⭐⭐ で太字に)
  • クロストピック:descriptionの末尾に (亦見 [[other-file]]) を追加

モード3:既存メモリの更新(新規作成より優先)

ステップ1:grepで既存のトピック帰属を確認

grep -l "<キーワード>" memory/*.md

ステップ2:更新方法を決定

状況更新方法
新しいデータ / 新しい事例が既存の結論を補強する本文にセクションまたはchangelogセクションを追加
既存の結論が覆された古いファイルの先頭に ⚠️ Superseded by [[new-file-slug]] を追加、新しいファイルの本文に「[[old]] のどの部分を置き換える」と記述
descriptionの説明が不明確なだけMEMORY.mdのインデックスを変更、ファイル自体は変更しない(内容も追加する場合は除く)

ステップ3:MEMORY.mdを同期

descriptionが変更された場合、MEMORY.mdの該当行も変更する。


モード4:構造変更(スキーマ変更 / 新しいtype追加 / グループ変更)

既に踏んだ落とし穴のリストを必読:

  • if: "Write(memory/*.md)" glob構文を試さないこと — if: はパーミッションルールでありファイルglobではない。無効であることが確認済み
  • exit 2でフックをブロックしないこと — pre-deploy batchフローを壊すことが確認済み(Claudeに自動リトライメカニズムはない)
  • スキーマの権威ソースを _schema.md のようなアンダースコア始まりのファイルに置かないこと — Claudeはtopicファイルを自発的に読まない
  • プロジェクトの .claude/settings.json にフックを設定しないこと — このディレクトリは通常 .gitignore に含まれ、git管理されずworktree間で共有されない
  • 新しい必須フィールドを追加する際は3箇所を同期する:(a) 本skillのセクション「モード2→ステップ3」 (b) MEMORY.md上部のクイックリファレンスセクション (c) audit-memory.shスクリプトのフィールドリスト
  • フックの修正/制約の追加前に bash scripts/audit-memory.sh を実行して現在のコンプライアンス率を確認 — <95%ならハードな対策が必要、≥95%ならソフトな警告を維持
  • MEMORY.mdのサイズ監視は文字(wc -m)で行い、バイト(wc -c)では行わない — ネイティブ上限は200行/25K文字を文字数でカウント。中国語1文字3バイトのため、バイトで較正すると静かな切り捨てが発生する(ルール6の歴史事例参照)

スキーマ変更のフロー:

  1. auditを実行して現在のベースラインを取得
  2. 変更を設計(本skill + プロジェクトhubの変更)
  3. 既存のmemoryが新しいルールに大規模に違反していないか確認(>10% → 一旦保留し、新しいルールに従って移行)
  4. MEMORY.mdのクイックリファレンスセクションを同期更新
  5. auditスクリプトのフィールドリストを変更
  6. auditを再実行して新しいコンプライアンス率を確認

モード5:ゼロ記憶ブートストラップ(新規プロジェクト)

ユーザーがmemoryシステムのないプロジェクトで「記憶を構築し始めて」と言った場合:

ステップ1:auto memoryディレクトリパスを確認

Claude Codeは自動的に ~/.claude/projects/<project-slug>/memory/ を作成する。ここで <project-slug> = プロジェクトの絶対パスを / を - に置き換えたもの。例:

  • プロジェクト /Users/alice/Project/myapp → slug -Users-alice-Project-myapp

Claude Codeが既にそのプロジェクトのauto memoryを作成している場合、ディレクトリは存在する。確認:ls ~/.claude/projects/ | grep <プロジェクト名>。

ステップ2:MEMORY.mdインデックスを作成

上部テンプレート(約25行に圧縮可能):

# <プロジェクト名> プロジェクト記憶

## ⭐⭐⭐ memory書き方クイックリファレンス(ハードルール)
- ファイル名:`<type>_<topic>.md` すべて小文字、アンダースコア区切り。type ∈ {feedback, reference, project}
- 必須 frontmatter:name / description / type
- feedback には ## Why セクション(または同義の中語 ## 根因 / ## 教訓 / ## 原因)が必須
- descriptionスタイル:シナリオキーワード + 核心結論(1行 ≤160文字)
- 同一トピックに既存ファイルがある場合は更新、新規作成しない(ルール6の閾値を超える場合は分割)
- 本インデックスのハード上限:先着200行または25K文字(どちらか早い方)、超過分は静かにロードされない
- 詳細な方法:memory-management skill

## ⭐ プロジェクトトピック一覧
(なし — 後続のトピックに応じてグループを追加)

ステップ3:グループ進化の閾値(ファイル数で構造を決定)

memoryファイル数推奨構造
< 15 エントリフラットリスト、グループなし(単一リストで十分、グループ化は断片化を招く)
15-25 エントリ3-5の大グループを導入(トピックで集約)
> 25 エントリグループ化が成熟し、グループを凍結して新規作成禁止。新しいエントリは既存グループにぶら下げる(クロストピックは (亦見 X) を使用)

ステップ4:CLAUDE.mdの上部にMemoryプロトコルを追加(3-5行)

## Memory 管理
memoryへの書き込み / 更新 / スキーマ調整が必要な場合 → `memory-management` skillを使用。
- クイックリファレンスルール:MEMORY.md上部の ⭐⭐⭐ セクション
- ヘルスチェックコンプライアンス率:`bash scripts/audit-memory.sh`(オプション、skill templates/参照)

ステップ5:本skillの汎用メソッドを再利用

skillの内容をプロジェクトにコピーしないこと。skillはユーザーレベルにあり、すべてのプロジェクトで1つのメソッドを共有する。プロジェクトにはプロジェクト固有の状態(グループリスト / TODO / プロジェクト固有の落とし穴)のみ配置する。


スキーマ規範(権威ソース)

ファイル命名

<type>_<topic>[_<modifier>].md すべて小文字、アンダースコア区切り。type ∈ {feedback, reference, project}

必須 frontmatter

---
name: kebab-case-slug
description: シナリオキーワード + 核心結論
type: feedback | reference | project       # フラット(推奨)
# または:
# metadata:
#   type: feedback | reference | project   # ネスト(互換性)
---

auditスクリプトは両方を認識する。新規ファイルはフラットを優先。

feedback必須情報

理由セクション(いずれか):

  • ## Why または同義の中語タイトル ## 根因 / ## 教訓 / ## 原因 / ## 為什麼 / ## Root cause(英語の : または中国語の : でも可)
  • 太字インライン **Why**: / **Why**: / **根因**: など

いつ再利用するか(いずれか):

  • 単独の ## How to apply セクション
  • descriptionにシナリオキーワードが含まれている(トリガーシナリオが暗示されていれば可)

descriptionスタイル

混合(シナリオキーワード + 核心結論)。Claudeがdescriptionを頼りに「XシナリオでY結論を参照」できるようにする。1行 ≤ ~160 文字 —— 詳細はtopicファイルまたはコードコメントへ(インデックスのハード上限 = 先着200行/25,000文字、超過分は静かにロードされない)

インデックス行のフォーマット

- [短いラベル](完全なファイル名.md) — hook。短いラベル = typeプレフィックスを除いたハイフン区切りの名前(例:[supabase-from-deadlock](feedback_supabase_from_deadlock.md))。長尾低頻度エントリは集約行を使用(サブトピック → [a](f1.md) · [b](f2.md))

グループの凍結

既存の大グループから選択し、新しいグループの作成は禁止。帰属が曖昧な場合は (亦見 hub-X) でクロスリファレンス。


よくある間違い

誤正
印象でdescription「Supabaseの問題」と書くシナリオキーワード + 結論「supabase.from() タブ切替デッドロック、fetchを使用」と書く
feedbackに「何か」だけ書くfeedbackには必ず ## Why を付け、将来の再質問を防ぐ
同じトピックで2つ目のファイルを新規作成するまず既存を更新、新規作成は断片化を招く
新しい「ネットワーク問題」グループを作成して1つのエントリを置く既存グループを使用し、クロストピックは (亦見 X) を使用
スキーマ規範をmemoryファイルに書くスキーマは本skillに、memoryには事実を格納
hook exit 2で強制ブロックするソフト警告(stderr + exit 0)または監査による事後チェックを使用

セルフチェック(書き終えたら)

  • タイプは正しいか(feedback/reference/project)?
  • ファイル名は <type>_<topic>.md のすべて小文字、アンダースコア区切りか?
  • frontmatterの3フィールドは揃っているか(name / description / type)?
  • feedbackクラスに理由セクション(## Why または同義の中語 / 太字インライン)があるか?
  • descriptionにシナリオキーワード + 核心結論が含まれているか?
  • MEMORY.mdインデックスの正しい大グループの下に追加したか?
  • 新しいグループを作成していないか?(作成した場合は取り消し、既存グループに配置する)
  • クロストピックに (亦見 X) のヒントを追加したか?
  • ルール6チェック:新しいファイルは < 100行 かつ < 5つのH2セクションか?(既存ファイルを更新して閾値を超える場合は、新しいファイルに分割に変更する)
  • 近接性トリガーチェック(ルール2):このエントリは特定のファイルに紐づいているか?もしそうなら、ファイルローカルなWHYは既に/将来コードコメントにあるべきで、memoryには横断原則のみ残すか?
  • インデックスレベルのチェック:descriptionの新規追加/変更後、MEMORY.mdはまだ < 23,000文字(wc -m、バイトではない!)かつ < 190行、さらに各行 ≤ ~160文字か?
  • トリガー力のヘルスチェック:将来問われる可能性のあるシナリオキーワードを3つ挙げ、「Claudeはdescriptionを見てこのmemoryを読むだろうか?」とシミュレーションする(シナリオが想像できない場合、descriptionは不合格)。

ツール連携

auditスクリプトはオプションのプロジェクトツール。

プロジェクトルートに scripts/audit-memory.sh がある場合 → 実行:

bash scripts/audit-memory.sh  # コンプライアンス率 / 違反一覧 / 30日未アクセスを表示

出力:総ファイル数 / frontmatter欠落 / Why欠落 / MEMORY.mdのリンク切れ / 30日未アクセス / MEMORY.mdサイズ(文字数+行数、ネイティブ上限200行/25K文字と比較) / コンプライアンス率%。 目標コンプライアンス率 ≥ 95%。

auditスクリプトがない場合 → テンプレートから自作:

# ユーザーレベルのskillに付属する汎用テンプレート
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
   <あなたのプロジェクト>/scripts/audit-memory.sh
# MEMORY_DIRをあなたのプロジェクトのauto memoryディレクトリに変更
chmod +x <あなたのプロジェクト>/scripts/audit-memory.sh
bash <あなたのプロジェクト>/scripts/audit-memory.sh

デフォルトのauto memoryパスを参照:~/.claude/projects/<project-slug>/memory/。詳細はモード5のステップ1を参照。

関連スキル