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) Проход по релизам/тегам (release-driven)

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

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

1. Найди артефакт релиза: release note / tag / changelog / merge commit.
2. Вычисли git range (обычно между коммитами релиз-нот или тэгами).
3. Сними “список сущностей”:
   • задачи/тикеты
   • измененные пути (модули/подсистемы)
   • новые/измененные экранные формы/контракты/DB миграции
4. Создай узел ревью релиза (type release_review) и список сущностей.
5. Для каждой DEV-задачи:
   • создай/обнови узел dev_task
   • добавь source_paths (минимальный список якорей)
   • свяжи с семантическими узлами (project/*)
6. Обнови индексы и 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.
2. Операции/команды/сценарии (actions):
   • “что система делает”: use-cases, сервисные методы, команды, workflow-степы.
3. Данные и контракты (data/contracts):
   • DB таблицы/модели, миграции, схемы сообщений, DTO, OpenAPI/AsyncAPI, JSON schema.
4. Интеграции (integrations):
   • внешние системы, протоколы (HTTP/JMS/Kafka/SFTP), ретраи, таймауты, idempotency.
5. Конфиги и флаги (config/feature flags):
   • runtime настройки, feature flags, параметры окружений, секреты (только “где берется”, не значения).
6. Безопасность и доступ (security):
   • authn/authz, роли/права, SSO, аудит.
7. Надежность и эксплуатация (ops):
   • метрики/логи/трейсинг, алерты, SLO, деградации, recovery-процессы.

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

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

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

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

1. Определи затронутые сущности (по diff/путям/ключевым словам).
2. Обнови соответствующие узлы, не расширяя лишний контекст:
   • добавь 1-3 предложения “что изменилось”
   • добавь ссылки на контракт/код/DB
   • обнови backlinks/индексы
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).

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.