Дмитрий
14 KiB
Graphify Spike — Design Spec
Дата: 27.05.2026 Тип: Spike (evidence-first), не полная интеграция Статус: Draft → User review Происхождение: заказчик увидел упоминание Graphify, спросил «снижает ли расход токенов» → разведка показала 35-70x потенциал на больших репо → spike-first решение вместо немедленной формализации Цепочка: brainstorming (this) → writing-plans → executing-plans (spike) → решение GREEN/YELLOW/RED → опционально Approach B (полная интеграция как 19-я off-phase подкатегория) отдельной задачей
1. Контекст и проблема
CLAUDE.md грузится в каждое сообщение целиком (~800 строк). Pravila — ещё ~1500 строк. Specs / plans / observer episodes — сотни файлов. Текущий поток работы Claude по репо Лидерры — grep по 5-20 файлам подряд, частые Read 100+ KB файлов целиком. Это сжигает input-токены.
Graphify (open-source skill, MIT, 54.4k ⭐, v0.8.20 от 26.05.2026) обещает решение через граф знаний: один раз парсит репо (Tree-sitter для AST + LLM для семантики прозы), потом ассистент бьёт точечные запросы по графу вместо чтения файлов целиком.
Бенчмарки на чужих репо: 35-70% экономия input-токенов, до 70x на 500+ файлов. Но цифры — для других кодовых баз, не для русско-язычного markdown-стены Лидерры.
Главный неизвестный: работает ли семантика Ollama на русском markdown с проектной терминологией Лидерры.
2. Цель спайка
Получить данные для решения «формализовать ли Graphify как 19-ю off-phase подкатегорию knowledge-graph-tooling (#89)» — на основе замеров экономии на нашем конкретном репо, не на бенчмарках чужих.
Не цель: реальная интеграция, нормативный долг, lefthook, observer-хуки, ADR, IS9-вет. Всё это — следующая задача при GREEN.
3. Зафиксированные решения (из brainstorming)
| # | Решение | Выбор |
|---|---|---|
| 1 | Backend для семантики | Ollama локально |
| 2 | Multimodal scope | Всё как из коробки (включая yt-dlp/whisper зависимости) |
| 3 | Инструмент | Graphify (не codegraph) |
| 4 | Timing | Сейчас параллельно A10 BI-tooling |
| 5 | Scope индексации | app/ + docs/ + .claude/ (без db/schema.sql) |
| 6 | Модель Ollama | qwen2.5:7b |
| 7 | Хранение графа | .graphify/ в .gitignore, не коммитим |
4. Архитектура спайка
4.1. Окружение
- Worktree:
worktree-graphify-spikeотorigin/main(или текущего HEAD на момент исполнения) - Ветка:
spike/graphify-2026-05-27 - Машина: dev Windows Server 2022 (не на боевом
liderra.ru) - Python: 3.10+ (есть, поставлен для D3 #40 Security Guidance)
- Ollama: новая установка, Windows installer с ollama.com, сервис на
localhost:11434 - Модель:
qwen2.5:7b(4.7 ГБ диск, ~6 ГБ RAM в idle) - Graphify:
uv tool install graphifyy+graphify install
4.2. Scope индексации
Включаем:
app/— Laravel + Vue (PHP, .vue, .ts, миграции, конфиги). Tree-sitter, без Ollama-расхода.docs/— markdown-стена (Pravila, CLAUDE.md, ТЗ, specs, plans, ADR). Главный consumer Ollama-семантики..claude/— skills/agents/settings markdown.
Исключаем (явно через Graphify ignore-конфиг):
node_modules/,vendor/,bin/,liderra_v8_handoff/docs/observer/episodes-*.jsonl(PII-риск, телеметрия)docs/superpowers/audits/,docs/discovery/(одноразовые snapshot'ы)web/(HTML-прототипы фазы 0)db/schema.sql(один файл, мини-польза).env,.env.*,db/00_create_roles.sql(секреты)
4.3. Хранение артефактов
- Граф:
.graphify/в корне worktree, в.gitignore(добавляем строкой.graphify/) - Ollama-модель:
%USERPROFILE%\.ollama\models\ - Отчёт спайка:
docs/discovery/2026-05-27-graphify-spike.md(commit'нуть в ветку спайка)
5. Метрики
5.1. Базовые (автоматом)
| Метрика | Цель замера |
|---|---|
| Время первой сборки графа (Tree-sitter + Ollama) | Понять, сколько ждать в новом worktree |
Размер .graphify/ (МБ) |
Сверить с прогнозом 50-200 МБ |
| Кол-во узлов / рёбер графа | Сверить с прогнозом 3-4k nodes |
| RAM Ollama в idle | Сверить с порогом <8 ГБ |
| RAM Ollama при запросе | Сверить с порогом <12 ГБ peak |
| Покрытие docs/ (успешно обработано / всего MD) | Понять качество русско-язычной семантики |
5.2. Экономия на 5 baseline-задачах
Для каждой задачи — A/B замер:
- A (baseline): Claude отвечает классическим путём (Read/Grep/Glob), считаем input-токены и tool-calls.
- B (с графом): Claude использует
/graphify query "...", получает компактный подграф, отвечает. Считаем токены Graphify-ответа + последующий ответ.
5 baseline-задач:
- «Где обрабатывается tenant_id в SetTenantContext» — поиск по коду.
- «Что говорит Pravila про параллельные сессии» — поиск по markdown.
- «Покажи все Job-классы, которые трогают LedgerService» — code-graph навигация.
- «В каком ADR решение про Universal Icons MCP границу» — кросс-доковая навигация.
- «Какие узлы реестра помечены DEFERRED в Tooling Прил.Н» — структурный запрос по нормативке.
Покрытие паттернов: код, markdown, кросс-связи.
5.3. Не меряем
- Качество финального кода / правильность ответов Claude — спайк про экономию токенов, не про accuracy.
- Влияние на Pest / CI — спайк в worktree, не трогает основной checkout.
- Экономию output-tokens — Graphify влияет в основном на input.
6. Exit criteria
GREEN — формализуем (Approach B следующим заходом)
Все четыре условия:
- Средняя экономия input-tokens ≥30% по 5 задачам.
- Минимум 3 из 5 задач показывают ≥20%.
- Время инкрементальной пере-сборки после правки файла <2 мин.
- Ollama в idle <8 ГБ RAM.
Действие: мерж спайк-ветки в main (приносит .gitignore +.graphify/ и отчёт), worktree+Ollama+Graphify остаются установленными. Approach B (полная интеграция как 19-я off-phase) — отдельная задача с собственным brainstorming → writing-plans → executing-plans.
YELLOW — частичная победа, без формализации
Хотя бы одно из:
- Экономия 15-30% средняя.
- Работает только на коде, не на markdown (Ollama споткнулась о русский).
- RAM 8-12 ГБ (граничит с другими сервисами).
Действие: мерж спайк-ветки в main (отчёт + .gitignore), Graphify+Ollama остаются установленными как личный инструмент контроллера, не в Tooling-каноне (без #89, без ADR, без §3.3 row). Memory-entry feedback_graphify_yellow.md с честной оценкой «работает частично, не формализован» + правилами когда зовём (например только на код-задачах). Пересмотр при выходе Graphify v1.0 или другой модели.
RED — откат
Хотя бы одно из:
- Экономия <15% средняя.
- Качество семантики на русском markdown — мусор.
- Время первой сборки >3ч.
- RAM >12 ГБ.
- Crash'и Graphify на Windows.
Действие: (1) cherry-pick docs/discovery/2026-05-27-graphify-spike.md в отдельный коммит на main с пометкой «negative result», (2) graphify uninstall, ollama rm qwen2.5:7b, удалить Ollama, (3) удалить worktree, удалить ветку spike/graphify-2026-05-27, (4) memory-entry project_graphify_spike_negative.md со ссылкой на cherry-pick'нутый отчёт. Порядок важен — отчёт сначала сохранить, потом удалять.
7. Timeline
- Установка Ollama + модели + Graphify: 30-60 мин.
- Первая сборка графа: 1-3ч (главный неизвестный).
- 5 baseline-задач (A/B): 1-2ч.
- Отчёт + решение: 30 мин.
- Итого активной работы: 3-7ч + ожидание сборки.
Дефолт по итогам: решение принимается в тот же день. RED-протокол — в тот же час, чтобы Ollama не съела диск впустую.
8. Out-of-scope
Не делаем в спайке (откладываем до Approach B при GREEN)
- Любая правка нормативки (Tooling Прил.Н, CLAUDE.md §3.3, PSR_v1 R10.1/R15.6, Pravila §13.2, nodes.yaml, routing-off-phase.md, automation-graph.html).
- ADR-017 (boundary rules KGT1-KGTN).
- IS9 provenance vet (
docs/security/graphify-vet.md). - Lefthook pre-commit auto-update job.
- Observer хуки (
tools/graphify-*.mjs). - Conflict map с context7 / Boost / openapi-mcp-server.
- Pravila §15.2 pre-flight sync (спайк в worktree, не трогает 8 нормативных файлов).
- Eval'ы и тесты Graphify-интеграции.
Не делаем никогда
- Права на коммит из Graphify (read-only консультант).
- Индексация
docs/observer/episodes-*.jsonl(PII-риск, sanitized phone-numbers в логах, квирки 23.05.2026). - Индексация
.env,bin/,db/00_create_roles.sql. - Запуск Ollama на боевом
liderra.ru(dev-only).
9. Что коммитим в спайк-ветку
.gitignore+строка.graphify/.docs/discovery/2026-05-27-graphify-spike.md— отчёт с таблицей метрик.- Опционально — конфиг Graphify ignore (если работает через файл).
Ничего больше. Никакой нормативки, никаких ADR, никаких узлов карты, никаких изменений lefthook/settings.json.
10. Решения отложенные до Approach B (при GREEN)
Не закрываем в спайке, но фиксируем для следующего захода:
- Где живёт узел Graphify на карте: A2 «Программирование — общее» или A6 «Архитектура»?
- Conflict map: точные границы с #60 context7 (внешние доки) и Boost (Roster intra-AST) и #47 openapi-mcp-server (OpenAPI-спека).
- Стратегия инкремента в production-режиме: git hook auto-update vs ручной
/graphify --update. - Observer integration: распознавание
graph-queryклассификации в router-classifier. - Каноническая ссылка в memory + Tooling Прил.Н 9-attribute block.
11. Связанные артефакты
- CLAUDE.md §3.3 (реестр инструментов) — спайк не правит, но при GREEN добавится #89.
- Tooling Прил.Н §0 — счётчик 83→84 (или 88→89 если A10 закрылся раньше).
- ADR серия — следующий свободный ADR-017.
docs/discovery/— home для отчёта спайка (одноразовый snapshot).- A10 BI-tooling worktree
feat/a10-bi-tooling— параллельная ветка, не блокирует.