brain/docs/adr/ADR-017-knowledge-graph-tooling.md

ADR-017: Knowledge-graph tooling formalization (graphify)

• Status: Accepted
• Date: 2026-05-27
• Deciders: Дмитрий

Context

Spike spike/graphify-2026-05-27 (worktree .claude/worktrees/graphify-spike) отработал три фазы построения knowledge-graph портала через инструмент graphify (npm-обёртка graphifyy, бинарь graphify.exe, установлен через uv tool install graphifyy v0.8.20+):

• Phase 1 (docs/): 1352 узла / 1455 рёбер / 147 communities — 271 markdown файл, deep semantic extraction через Claude subagent dispatch (~2.4M tokens, 275 messages из 5h-окна).
• Phase 2 (.claude/): 1135 узлов / 1234 рёбер / 139 communities — 262 файла (66 code + 196 docs), deep semantic, ~2.0M tokens, 11 субагентов, retry потребовался после session-limit.
• Phase 3 (app/): 3818 узлов / 4064 рёбер — 824 PHP/Vue/TS файла, pure AST extraction (БЕЗ субагентов, ~30 сек wall-clock, 0 LLM-токенов).
• Ultimate combined (через graphify merge-graphs): 6305 узлов / 6753 рёбер / 1009 communities, 93% EXTRACTED / 7% INFERRED / 0% AMBIGUOUS.

Spike дал воспроизводимую методологию: subfolder + graphify merge-graphs — безопасно строить фазами с откатом по бэкапам без потери прежних узлов. Дополнительные узлы карты Лидерры — lib/graph_node:* для трёх фаз + ultimate, провенанс-связки к источникам.

graphify — off-phase инструмент (не входит в фазовую раскладку #1-#29): для knowledge-management проекта, а не для конкретной фазы разработки. Параллельный ряду существующих off-phase подкатегорий (debug-runtime / architecture-tooling / audit-security / project-management / design-tooling / integration-tooling / ml-ai-tooling / business-process / discovery-tooling / authoring-tooling / dev-support / finance-tooling / backend-tooling / infosec-tooling / marketing-tooling), но граничит с context7 (#60), Boost (#10), openapi-mcp-server (#47), Sentry MCP (#34) и adr-kit/mermaid (#36/#37) по семантике; границы фиксируются в Decision ниже.

NB: параллельная сессия завершает раздел A10 BI-tooling (feat/a10-bi-tooling, Tasks 1-4 из 19, 5 узлов #84-#88 — узлы агентов nodes.yaml уже заняли #84/#85, BI на feature-branch без merge). Порядок merge решит финальную нумерацию подкатегории (19-я или 20-я); счётчики закрываются normative-sync агентом после merge.

Альтернативный backend Ollama — отдельный установленный для 152-ФЗ-чувствительных задач инструмент; graphify его НЕ читает (graphify читает только GEMINI_API_KEY/ GOOGLE_API_KEY или fallback на Claude Code subagent dispatch).

Decision

Graphify формализуется как узел #86 graphifyy в реестре Tooling Прил. Н в новой девятнадцатой off-phase подкатегории «knowledge-graph-tooling».

Граничные правила (locked)

1. graphify (#86) ↔ context7 (#60). Разные слои документации:

   • context7 — внешние библиотеки/SDK/фреймворки (актуальные docs от vendor). Первый выбор для «как использовать React/Laravel/Vue».
   • graphify — внутренний codebase + спеки + .claude/-артефакты Лидерры. Первый выбор для «как устроен наш модуль/где вызывается наша функция/ связан ли наш скил X с агентом Y». Не дублируют. context7 ничего не знает про наш код; graphify ничего не знает про публичные SDK.

2. graphify (#86) ↔ Laravel Boost (#10). Разный grain:

   • Boost — MCP-сервер с Eloquent/DB/Laravel-docs query-апи (например, php artisan tinker --execute, query schema, search Laravel docs). Точечный ввод/вывод по конкретному запросу к app/.
   • graphify — статический knowledge graph через все слои (docs+config+code). Cross-layer навигация и «структурные карты», не runtime queries. Boost остаётся первым выбором для «выполни SQL» / «прочитай model» / «найди в Laravel-docs»; graphify — для «покажи связи между нашим спеком и кодом» / «какие концепты связаны с X».

3. graphify (#86) ↔ openapi-mcp-server (#47). Разный объект:

   • openapi-mcp-server — introspection одного OpenAPI-спека (docs/api/ openapi.yaml), tools/resources MCP-сервера, READ-ONLY.
   • graphify — весь проект (docs+config+code), включая OpenAPI как часть более широкого графа. openapi-mcp-server остаётся первым выбором когда вопрос локализован в API- спеке («какие эндпоинты`?»); graphify — когда вопрос пересекает спек + реализацию + тесты + договорённости.

4. graphify (#86) ↔ Sentry MCP (#34). Разная плоскость:

   • Sentry — runtime ошибки (что упало в проде), READ-ONLY.
   • graphify — структурные отношения (как код связан), статика. Для post-mortem «упало X, что с чем связано» — Sentry находит X, graphify показывает blast radius.

5. graphify (#86) ↔ adr-kit (#36) + mermaid-skill (#37). Разная природа:

   • adr-kit / mermaid — manual authoring решений и диаграмм (декларативно заказчиком/Claude).
   • graphify — auto-discovery связей из исходников (deterministic AST + LLM semantic). Не пересекаются: ADR — нормативное решение; graphify-граф — наблюдаемая структура.

Узел #86 graphifyy — атрибуты

• Категория: off-phase, knowledge-graph-tooling (19-я подкатегория).
• Источник: npm graphifyy v0.8.20+ (через uv tool install graphifyy), binary graphify.exe.
• Установка: uv tool install graphifyy; работает с user-level skill ~/.claude/skills/graphify/SKILL.md (через graphify install --platform claude).
• Активация: explicit /graphify <команда>, не проактивно.
• Артефакты: graphify-out/{graph.json,GRAPH_REPORT.md,graph.html,cache/} в CWD откуда запущен. Должны быть в .gitignore (graphify-out*/), чтобы build-артефакты не попадали в diff/commit.
• LLM-backend: GEMINI_API_KEY/GOOGLE_API_KEY (если есть) или fallback на Claude Code subagent dispatch. НЕ читает ANTHROPIC_API_KEY, OPENAI_API_KEY, Ollama API.
• Ollama compliance: Ollama установлен в проекте для 152-ФЗ чувствительных задач (локальный LLM без отправки в Anthropic), но graphify Ollama НЕ использует — это два независимых инструмента.

Стратегия обновлений (locked)

• Manual update пока единственный безопасный режим: /graphify --update (LLM для doc/MD-изменений; AST-only для code-изменений).

• Auto-update post-commit hook отложен. Spike-попытка 27.05 вечером: graphify update . от широкого scope разнесло граф 6305 → 41586 узлов (38 МБ bloat), потому что подхватил tools/ + root-level .mjs + другое за пределами трёх фаз. Откат через re-merge phase-бэкапов восстановил canonical 6305/6753/1009. Перед auto-update необходимо:

  • Спроектировать узкий scope или exclude-pattern (vendor/, tools/, node_modules/).
  • Узкий manifest, корректно покрывающий все 3 фазы.
  • Smoke-test перед wire-in lefthook.

  До этого момента — никакого автоматического обновления.

Spike worktree → main стратегия

• Spike worktree (spike/graphify-2026-05-27) остаётся локально для повторяемых rebuild'ов через subfolder + merge-graphs методологию.
• На main commit'ятся: эта ADR-017, обновления нормативки (CLAUDE.md/Pravila/ PSR_v1/Tooling/nodes.yaml/routing-off-phase.md), .gitignore add graphify-out*/. Phase 1+2+3 binaries (graph.json + ультимейт ~5MB) не коммитятся — пересобираются по запросу.
• Spec/plan на main (docs/superpowers/specs/2026-05-27-graphify-spike-design.md
  • docs/superpowers/plans/2026-05-27-graphify-spike.md) — untracked, требуют revision (Ollama assumption в исходной spec ошибочен). Можно обновить post-формализации либо drop.

Consequences

+ Knowledge-graph для всего портала Лидерры — формализованный инструмент ответа на cross-layer вопросы («где наш скил X используется в коде / в каких спеках упоминается агент Y / какие концепты связаны с биллингом»).

+ Bридирует gap между документацией (docs/), конфигом (.claude/) и реализацией (app/) — единый граф для onboarding и architectural reasoning.

+ Subfolder + merge-graphs методология воспроизводима для дополнения графа без потери прежних узлов; provenance к источникам сохраняется.

+ Граничные правила фиксируют когда что использовать → нет дублирования с context7/Boost/openapi/Sentry/adr-kit.

– Первичная сборка дорогая по subagent-токенам (Phase 1+2 = ~4.4M tokens). Регенерация графа не должна быть рутинной операцией.

– Auto-update отложен → граф быстро устаревает между manual rebuild'ами. До wire-in safety review — этот риск осознанный.

– Третий канал документации проекта (после CLAUDE.md/MEMORY.md и реестра Tooling) — нагрузка на дисциплину обновлений.

– Размер canonical graph.json ~5 МБ — должен быть в .gitignore; иначе diff'ы будут шумные.

Compliance

• Узел #86 graphifyy в реестре Tooling Прил. Н, 19-я подкатегория knowledge-graph-tooling.
• CLAUDE.md §3.3 +строка #89; §0 cross-refs Pravila/PSR_v1/Tooling bumped; §6 + абзац о spike; §9 changelog entry.
• Pravila §13.2 +абзац «Off-phase knowledge-graph-tooling».
• PSR_v1 R10.1 Блок 1 note (graphifyy не UI → вне R6/R14); R15.6 +knowledge- graph-tooling в список off-phase подкатегорий.
• nodes.yaml: узел #86 graphifyy с subcategory knowledge-graph-tooling.
• routing-off-phase.md: trigger «knowledge graph / codebase structure / cross- layer concept query» → #86.
• spike worktree .gitignore update: graphify-out*/.

Cross-refs

• Spike spec (untracked, revision pending): docs/superpowers/specs/2026-05-27- graphify-spike-design.md.
• Spike plan (untracked, revision pending): docs/superpowers/plans/2026-05-27- graphify-spike.md.
• Memory (user-local): ~/.claude/projects/.../memory/project_graphify_phase3_ done.md — runtime handoff state, инцидент с auto-hook + откат.
• Skill (user-level, через graphify install --platform claude): ~/.claude/skills/graphify/SKILL.md.