# 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-задач:**

1. «Где обрабатывается tenant_id в SetTenantContext» — поиск по коду.
2. «Что говорит Pravila про параллельные сессии» — поиск по markdown.
3. «Покажи все Job-классы, которые трогают LedgerService» — code-graph навигация.
4. «В каком ADR решение про Universal Icons MCP границу» — кросс-доковая навигация.
5. «Какие узлы реестра помечены 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` — параллельная ветка, не блокирует.

## 12. Ссылки

- [GitHub: safishamsi/graphify](https://github.com/safishamsi/graphify)
- [Graphify website](https://graphify.net/)
- [MindStudio benchmark: 70x cost reduction](https://www.mindstudio.ai/blog/graphify-claude-code-knowledge-graph-large-codebase-70x)
- [Альтернатива: colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) (не выбрана)
