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