Graph Memory Bank

Цель

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

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

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

Обычно:

docs/graph/

в репозитории, где есть 3 слоя:

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

Важно: если в репозитории уже есть один из вариантов (

process/

или

processes/

) или другая устоявшаяся структура, не переименовывай “ради красоты”. Подстраивайся под текущую структуру, а в индексах дай явные ссылки.

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

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

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

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

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

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

Что НЕ делать

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

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

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

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

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

Создай
```
docs/graph/index.md
```
(входная точка).

Создай индексы:

```
docs/graph/tasks/index.md
```
```
docs/graph/project/index.md
```
```
docs/graph/processes/index.md
```
или
```
docs/graph/process/index.md
```
(в зависимости от структуры репозитория)

Зафиксируй соглашения:
- схема
```
id
```
  (обычно префикс + путь, например
```
graph:project/<slug>
```
  )
- статусы:
```
stub | curated | generated
```
- теги: короткие, стабильные (не плодить)

Шаблоны и чек-листы: см.

references/templates.md

references/quality-bar.md

2) Проход по релизам/тегам (release-driven)

Цель: быстро нащупать “важные сущности”, которые реально менялись.

Для каждого релиза:

Найди артефакт релиза: release note / tag / changelog / merge commit.
Вычисли git range (обычно между коммитами релиз-нот или тэгами).
Сними “список сущностей”:
- задачи/тикеты
- измененные пути (модули/подсистемы)
- новые/измененные экранные формы/контракты/DB миграции
Создай узел ревью релиза (type
```
release_review
```
) и список сущностей.
Для каждой DEV-задачи:
- создай/обнови узел
```
dev_task
```
- добавь
```
source_paths
```
  (минимальный список якорей)
- свяжи с семантическими узлами (
```
project/*
```
  )
Обнови индексы и backlinks.

3) Проход по сущностям (entity-driven)

Цель: закрыть белые пятна “по всем ключевым сущностям”, а не только по тем, что попали в релизы.

Важно: “сущности” должны быть универсальными. В WMS это могут быть

экраны/RF-процедуры

, а в вебсайте

страницы/API

, в CRM

объекты/воронки

, в шине данных

топики/схемы/коннекторы

Алгоритм:

Выдели 5-12 категорий сущностей, которые реально важны для проекта.
Для каждой категории собери каталог (index/hub) и дальше добирай узлы по одному.
Для каждой сущности обеспечь “кросс-связность”: UI/операции/данные/интеграции/конфиги.

Рекомендованные категории (выбирай релевантные, не все):

Поверхности взаимодействия (entrypoints):
- Web/UI: страницы, роуты, ключевые компоненты, формы.
- API: endpoints, controllers/handlers, публичные контракты.
- CLI/Jobs: команды, cron/quartz, воркеры, фоновые задачи.
- Events/Streams: топики, события, consumers/producers.
Операции/команды/сценарии (actions):
- “что система делает”: use-cases, сервисные методы, команды, workflow-степы.
Данные и контракты (data/contracts):
- DB таблицы/модели, миграции, схемы сообщений, DTO, OpenAPI/AsyncAPI, JSON schema.
Интеграции (integrations):
- внешние системы, протоколы (HTTP/JMS/Kafka/SFTP), ретраи, таймауты, idempotency.
Конфиги и флаги (config/feature flags):
- runtime настройки, feature flags, параметры окружений, секреты (только “где берется”, не значения).
Безопасность и доступ (security):
- authn/authz, роли/права, SSO, аудит.
Надежность и эксплуатация (ops):
- метрики/логи/трейсинг, алерты, SLO, деградации, recovery-процессы.

Главное правило: не пытайся “описать всё вручную”. Делай:

каталоги + хабы (семейства/модули/домены);
атомарные узлы с evidence;
связи между категориями (например: страница -> API -> сервис -> таблицы -> события).

4) Поддержка по мере изменений (incremental maintenance)

На каждый новый коммит в

main

Определи затронутые сущности (по diff/путям/ключевым словам).
Обнови соответствующие узлы, не расширяя лишний контекст:
- добавь 1-3 предложения “что изменилось”
- добавь ссылки на контракт/код/DB
- обнови backlinks/индексы
Прогони быстрые проверки:
- дубликаты
```
id
```
- отсутствие frontmatter
- битые ссылки между узлами
- orphan nodes (узлы без входящих ссылок внутри
```
docs/graph
```
  )
- сломанные относительные ссылки (если есть время)

Для базовой проверки можно использовать

scripts/graph_memory_lint.py

Пример:

bash

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

Опционально можно отключать части проверок:

bash

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
```
).

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

Not every skill requires all three types of resources.

graph-memory-bank

NPX Install

Tags

SKILL.md Content