Дмитрий
205 lines
14 KiB
Markdown
205 lines
14 KiB
Markdown
# 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) (не выбрана)
|