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: “где используется” (явные ссылки обратно на индексы/хабы)

1. Если в проекте есть _generated/ или другие generated-секции: не редактируй руками, правь генератор или исходный узел.
2. Если есть сомнения/риски: подсвечивай и задавай вопросы (лучше уточнить, чем зацементировать неверную семантику).

Рекомендованная схема 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/ (или другой явно согласованный каталог).

1. Найди, есть ли уже документация/конвенции (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 (в зависимости от структуры репозитория)

1. Зафиксируй соглашения:

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

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

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

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

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

1. Найди артефакт релиза: release note / tag / changelog / merge commit.
2. Вычисли git range (обычно между коммитами релиз-нот или тэгами).
3. Сними “список сущностей”:

- задачи/тикеты - измененные пути (модули/подсистемы) - новые/измененные экранные формы/контракты/DB миграции

1. Создай узел ревью релиза (type release_review) и список сущностей.
2. Для каждой DEV-задачи:

- создай/обнови узел dev_task - добавь source_paths (минимальный список якорей) - свяжи с семантическими узлами (project/*)

1. Обнови индексы и backlinks.

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

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

Важно: “сущности” должны быть универсальными. В WMS это могут быть экраны/RF-процедуры, а в вебсайте страницы/API, в CRM объекты/воронки, в шине данных топики/схемы/коннекторы.

Алгоритм:

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

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

1. Поверхности взаимодействия (entrypoints):

- Web/UI: страницы, роуты, ключевые компоненты, формы. - API: endpoints, controllers/handlers, публичные контракты. - CLI/Jobs: команды, cron/quartz, воркеры, фоновые задачи. - Events/Streams: топики, события, consumers/producers.

1. Операции/команды/сценарии (actions):

- “что система делает”: use-cases, сервисные методы, команды, workflow-степы.

1. Данные и контракты (data/contracts):

- DB таблицы/модели, миграции, схемы сообщений, DTO, OpenAPI/AsyncAPI, JSON schema.

1. Интеграции (integrations):

- внешние системы, протоколы (HTTP/JMS/Kafka/SFTP), ретраи, таймауты, idempotency.

1. Конфиги и флаги (config/feature flags):

- runtime настройки, feature flags, параметры окружений, секреты (только “где берется”, не значения).

1. Безопасность и доступ (security):

- authn/authz, роли/права, SSO, аудит.

1. Надежность и эксплуатация (ops):

- метрики/логи/трейсинг, алерты, SLO, деградации, recovery-процессы.

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

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

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

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

1. Определи затронутые сущности (по diff/путям/ключевым словам).
2. Обнови соответствующие узлы, не расширяя лишний контекст:

- добавь 1-3 предложения “что изменилось” - добавь ссылки на контракт/код/DB - обнови backlinks/индексы

1. Прогони быстрые проверки:

- дубликаты 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).

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.