graph-memory-bank

Graph Memory Bank

Цель

Сформировать и поддерживать графовую память проекта (как в Obsidian), чтобы ИИ-агенты быстро собирали точный минимальный контекст:

• много маленьких файлов, каждый про одну сущность/идею;
• связи через обычные markdown-ссылки;
• у каждого узла есть краткий YAML frontmatter (машиночитаемый);
• есть обратные ссылки (backlinks), чтобы граф был двунаправленным.

Результат (что должно получиться)

Обычно: docs/graph/ в репозитории, где есть 3 слоя:

1. tasks/ (история изменений: релизы/задачи/коммиты, “что менялось”)
2. project/ (семантика: архитектура, ключевые сущности, контракты, API, БД, интеграции, “куда смотреть в коде”)
3. processes/ или process/ (процессы: правила ведения графа, как обновлять, как читать, качество, генераторы)

Важно: если в репозитории уже есть один из вариантов (process/ или processes/) или другая устоявшаяся структура, не переименовывай “ради красоты”. Подстраивайся под текущую структуру, а в индексах дай явные ссылки.

Если слой процессов пока не нужен, начинай с первых двух, но держи место под третий слой.

Инварианты (жесткие правила)

1. Дроби информацию: один файл = одна сущность/идея/контракт.
2. Держи узлы короткими: как правило, до 200-300 строк; если разрастается, выноси подузлы.
3. У каждого узла есть YAML frontmatter (минимум: id, type, title, description, status, tags).
4. Всегда добавляй связи:
   • outbound links: “см. также”, “используется в”, “зависит от”
   • backlinks: “где используется” (явные ссылки обратно на индексы/хабы)
5. Если в проекте есть _generated/ или другие generated-секции: не редактируй руками, правь генератор или исходный узел.
6. Если есть сомнения/риски: подсвечивай и задавай вопросы (лучше уточнить, чем зацементировать неверную семантику).

Рекомендованная схема frontmatter (минимум)

Делай frontmatter максимально стабильным (для индексирования агентами):

• id: глобально уникальный идентификатор узла
• type: тип узла (project, dev_task, release_review, screen, rf_procedure, db_table, ...)
• title: человекочитаемое имя
• description: 1 предложение “зачем этот узел”
• status: stub | curated | generated
• tags: плоский список тегов (короткие)

Опционально (если реально помогает): releases, source_paths, owner, risk_level.

Как оформлять индексы (важно)

В индексах пиши не только ссылки, но и микро-аннотацию, чтобы не открывать каждый файл:

• - [DEV-12345](...): 6-10 слов, что внутри.

Что НЕ делать

• Не тащи секреты/токены/пароли в docs/ (максимум: “ищется в переменных окружения X/Y”).
• Не дублируй большие куски кода/SQL: вместо этого “якоря” + короткая выжимка + ссылка на файл.

Быстрый workflow (универсальный)

0) Подготовка

1. Создай отдельную ветку (например graph+memory).
2. Уточни ограничение записи:
   • по умолчанию пиши только в docs/ (или другой явно согласованный каталог).
3. Найди, есть ли уже документация/конвенции (docs/, ADR, mkdocs, docusaurus).

1) Сбор каркаса (bootstrap)

1. Создай docs/graph/index.md (входная точка).
2. Создай индексы:
   • docs/graph/tasks/index.md
   • docs/graph/project/index.md
   • docs/graph/processes/index.md или docs/graph/process/index.md (в зависимости от структуры репозитория)
3. Зафиксируй соглашения:
   • схема id (обычно префикс + путь, например graph:project/<slug>)
   • статусы: stub | curated | generated
   • теги: короткие, стабильные (не плодить)

Шаблоны и чек-листы: см. references/templates.md и references/quality-bar.md.

2) リリース／タグごとの確認（リリース主導）

目的：「重要なエンティティ」のうち、実際に変更されたものをすばやく見つけます。

各リリースについて：

1. リリース成果物を見つけます：リリースノート／タグ／変更履歴／マージコミット。
2. git の範囲を算出します（通常はリリースノートのコミットまたはタグ間）。
3. 「エンティティの一覧」を作成します：
   • タスク／チケット
   • 変更されたパス（モジュール／サブシステム）
   • 新規または変更された画面フォーム／コントラクト／DB マイグレーション
4. リリースレビューのノード（type release_review）とエンティティの一覧を作成します。
5. 各 DEV タスクについて：
   • dev_task ノードを作成／更新します
   • source_paths を追加します（最小限のアンカーパスの一覧）
   • セマンティックノード（project/*）にリンクします
6. インデックスとバックリンクを更新します。

3) エンティティごとの確認（エンティティ主導）

目的：リリースに含まれたものだけでなく、「すべての重要なエンティティ」を対象に、把握できていない箇所をなくします。

重要：「エンティティ」は汎用的なものにします。WMS では 画面/RF 手順、Web サイトでは ページ/API、CRM では オブジェクト/ファネル、データバスでは トピック/スキーマ/コネクタ などが該当します。

手順：

1. プロジェクトにとって本当に重要なエンティティのカテゴリを 5～12 個選びます。
2. カテゴリごとにカタログ（インデックス／ハブ）を作成し、その後ノードを 1 つずつ追加します。
3. 各エンティティに「相互リンク」を設けます：UI／操作／データ／統合／設定。

推奨カテゴリ（関連するものを選択し、すべてを選ぶ必要はありません）：

1. インタラクションの入口（entrypoints）：
   • Web/UI：ページ、ルート、主要コンポーネント、フォーム。
   • API：エンドポイント、コントローラー／ハンドラー、公開コントラクト。
   • CLI/Jobs：コマンド、cron/quartz、ワーカー、バックグラウンドタスク。
   • Events/Streams：トピック、イベント、コンシューマー／プロデューサー。
2. 操作／コマンド／シナリオ（actions）：
   • 「システムが実行すること」：ユースケース、サービスメソッド、コマンド、ワークフローのステップ。
3. データとコントラクト（data/contracts）：
   • DB テーブル／モデル、マイグレーション、メッセージスキーマ、DTO、OpenAPI/AsyncAPI、JSON schema。
4. 統合（integrations）：
   • 外部システム、プロトコル（HTTP/JMS/Kafka/SFTP）、再試行、タイムアウト、冪等性。
5. 設定とフラグ（config/feature flags）：
   • ランタイム設定、機能フラグ、環境パラメーター、シークレット（「取得元」のみを記載し、値は記載しません）。
6. セキュリティとアクセス（security）：
   • 認証／認可、ロール／権限、SSO、監査。
7. 信頼性と運用（ops）：
   • メトリクス／ログ／トレース、アラート、SLO、縮退動作、復旧プロセス。

最も重要なルール：「すべてを手作業で説明する」ことを目指さないでください。以下を行います：

• カタログとハブ（ファミリー／モジュール／ドメイン）。
• 根拠を備えたアトミックなノード。
• カテゴリ間のリンク（例：ページ -> API -> サービス -> テーブル -> イベント）。

4) 変更に応じた保守（段階的なメンテナンス）

main への新しいコミットごとに：

1. 影響を受けるエンティティを特定します（差分／パス／キーワードから）。
2. 余計なコンテキストを広げずに、該当するノードを更新します：
   • 「変更内容」の説明を 1～3 文追加します
   • コントラクト／コード／DB へのリンクを追加します
   • バックリンク／インデックスを更新します
3. 簡易チェックを実行します：
   • 重複した id
   • frontmatter の欠落
   • ノード間のリンク切れ
   • orphan nodes（docs/graph 内に被リンクのないノード）
   • 壊れた相対リンク（時間があれば）

基本的なチェックには scripts/graph_memory_lint.py を使用できます。

例：

python3 scripts/graph_memory_lint.py --root docs/graph

必要に応じて、一部のチェックを無効にできます：

python3 scripts/graph_memory_lint.py --root docs/graph --no-check-links
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-orphans

skill のリソース

• references/templates.md：ノードの簡易テンプレート。
• references/quality-bar.md：品質基準と「危険信号」。
• scripts/graph_memory_lint.py：簡易リンター（frontmatter + 重複した id）。

適切な用途： テンプレート、ボイラープレートコード、ドキュメントテンプレート、画像、アイコン、フォント、またはコピーや最終出力での使用を目的としたファイル。

---

すべての skill で、3 種類すべてのリソースが必要になるわけではありません。