Graphify: превращаем кодовую базу в граф знаний
Как Graphify строит детерминированный граф знаний из кода, документации и схем БД без векторных хранилищ. Интеграция с Claude Code, Cursor и Gemini CLI.
Как Graphify строит граф без векторного поиска
Как Graphify строит граф без векторного поиска
Парсинг AST вместо эмбеддингов
Во-первых, Graphify не использует векторы для построения графу знаний. Вместо этого он парсит AST‑дерево исходного кода, извлекая структуру классов, функций, переменных и их отношения. Это позволяет получать детерминированный граф, где каждая вершина — сущность, а ребра — ссылки, определённые правилами.
Пример: файл example.py содержит класс Service с методом run. После парсинга AST‑дерево выглядит так (упрощённо):
json{
"nodes": [
{"id": "example.Service", "type": "class"},
{"id": "example.run", "type": "method"}
],
"edges": [
{"from": "example.Service", "to": "example.run", "label": "has_method"}
]
}
Команда для получения такого JSON‑вывода:
bashgraphify parse --input example.py --output - | jq .
Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу
Определение связей между сущностями
Связи между сущностями определяются из нескольких источников: импортов, комментариев, схем баз данных и конфигурационных файлов. Graphify читает эти данные, сопоставляя их с элементами AST, и формирует ребра, которые описывают реальные зависимости.
Пример конфигурации, описывающей связь между модулем и базой данных:
yamlconnections:
- type: uses
source: module
target: database
match: "postgres"
Команда, использующая данный файл:
bashgraphify build --config connections.yaml --output knowledge_graph.dot
Результат — файл knowledge_graph.dot, который можно визуализировать в любом GraphViz‑совместимом инструменте. Всё построено детерминированно, без применения векторных хранилищ, что гарантирует воспроизводимость и предсказуемость связей.
Таким образом, Graphify строит граф знаний, опираясь на статический анализ кода и явные ссылки, а не на распределённые эмбеддинги, что упрощает отладку и обеспечивает предсказуемость работы в CI/CD‑конвейерах.
Интеграция с AI-ассистентами для кода
Настройка /graphify в Claude Code и Cursor
Во‑первых, Graphify представляет собой набор расширений, которые добавляют возможность генерировать граф знаний прямо в среде редактирования кода. Для работы требуется установленная последняя версия Claude Code (пакет claude‑code‑client ≥ 2.4) и Cursor 2024‑го выпуска.
-
Инициализация конфигурации
В корневой директории проекта создаётся файл.graphify.yml. Пример минимального набора:yamlgraphify: sources: - type: code paths: - src/ - type: docs paths: - docs/ output: format: dot file: graph.dotКоманда
graphify initсоздаёт такой файл со всеми комментариями‑подсказками. -
Подключение в Claude Code
После установки расширения в VS Code открываем контекстный меню «Graphify → Generate Knowledge Graph».
В открывшемся диалогe указываем путь к конфигу и выбираем тип вывода (DOT или SVG).bash# Пример запуска из терминала внутри Claude Code graphify run --config .graphify.yml --output svgПосле завершения в папке
./outputпоявляется файлknowledge.svg, который можно сразу просмотреть в браузере или импортировать в Claude Chat для дальнейшего анализа. -
Настройка в Cursor
В Cursor переходим в раздел Extensions, находим Graphify (пакетgraphify‑cursor) и нажимаем Install.
В настройках проекта указываем переменную окруженияGRAPHIFY_API_KEY, получаемую в кабинете Graphify‑Labs.bashexport GRAPHIFY_API_KEY=ghp_XXXXXXXXXXXXXXXXXXXX graphify run --watch --output dotПараметр
--watchотслеживает изменения в файлахsrc/иdocs/и автоматически обновляет граф каждый раз, когда сохраняется изменённый файл.
Для более детального описания параметров см. Graphify‑Labs/graphify.
Практические рекомендации по использованию Graphify в реальных проектах – в Навыки реальных инженеров: практические практики из .agents.
Работа с Gemini CLI и Codex
Во‑вторых, Graphify может быть интегрирован в сторонние AI‑инструменты, такие как Gemini CLI и Codex, чтобы получать готовый граф в виде входных данных для генерации кода или документирования.
-
Подготовка данных
Graphify сохраняет граф в формате DOT. Gemini CLI умеет читать этот формат и преобразовывать в JSON‑схему, которую понимает его собственный движок.bash# Пример конвертации DOT → JSON для Gemini CLI dot -Tjson graph.dot -o graph.json gemini-cli --model gemini-1.5-pro --input graph.json --output prompt.txtПолученный
prompt.txtсодержит описание узлов и релейных связей, которое можно передать в любой LLM‑ассистент (Claude Code, GPT, Gemini Chat) для получения рекомендаций по рефакторингу, генерации тестов или создания документации. -
Интеграция с Codex
Codex (инструмент, предоставляющий автодополнение и генерацию кода на основе запросов) поддерживает импорт пользовательских схем через параметр--schema.bash# Пример использования схемы, полученной от Graphify codex generate --language python --schema graph.json --output module.pyВ результате Codex генерирует файл
module.py, где функции и классы уже привязаны к соответствующим узлам графа, что упрощает построение микросервисных решений. -
Автоматизация в пайплайне CI
Для полной автоматизации удобно добавить шаг в GitHub Actions или GitLab CI, который после каждого коммита генерирует граф, сохраняет его в артефакте и передаёт в Gemini CLI. Пример workflow‑файла:yamlname: Generate Knowledge Graph on: push: branches: [ main ] jobs: graphify: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Graphify run: pip install graphify-cli - name: Generate DOT graph run: graphify run --config .graphify.yml --output dot - name: Convert to JSON run: dot -Tjson graph.dot -o graph.json - name: Feed to Gemini CLI env: GRAPHIFY_API_KEY: ${{ secrets.GRAPHIFY_API_KEY }} run: gemini-cli --model gemini-1.5-pro --input graph.json --output prompt.txtПосле выполнения артефакт
prompt.txtможно использовать в downstream‑задачах: создание Pull Request, генерация тестов, обновление документации.
Подробные примеры использования Gemini CLI в сочетании с Graphify – в Навыки реальных инженеров: практические практики из .agents.
Симуляция прошивок для AI‑агентов, что часто требуется при работе с графовыми схемами, описана в Simantic: симуляция прошивок для AI‑агентов.
Если требуется автономная разработка на Rust с использованием аналогичных подходов, см. Автономная разработка на Rust с помощью Claw‑Code.
Таким образом, Graphify легко встраивается в существующие рабочие процессы Claude Code, Cursor, Gemini CLI и Codex, обеспечивая детерминированное построение графов знаний без привлечения векторных хранилищ. Всё, что остаётся – описать задачи, запустить генерацию и использовать полученный граф в дальнейшем анализе кода.
Поддерживаемые форматы и источники данных
Код
Graphify умеет напрямую анализировать файлы исходного кода любых поддерживаемых языков.
Для быстрого старта достаточно указать каталог с проектом и получить JSON‑описание граф‑структуры.
bash# Пример: парсим весь проект на Python и сохраняем граф в файл
graphify parse --input ./src --language python --output ./graph.json
В результате в graph.json появляются узлы — классы, функции, интерфейсы — и связи — наследование, вызовы, импорт.
Если нужно уточнить только определённый модуль, можно задать путь к файлу:
bashgraphify parse --input ./src/utils/helpers.py --output ./helpers.graph.json
Примечание. При работе с большими репозиториями удобно предварительно собрать список файлов в manifest.txt и передать его через параметр --files. Это уменьшает нагрузку на процессор и гарантирует детерминированность результата.
Подробнее о парсинге кода в Graphify‑Labs
SQL‑схемы и конфигурационные файлы
Помимо кода, Graphify принимает DDL‑описания баз данных и файлы конфигураций.
SQL‑скрипты, содержащие CREATE TABLE, ALTER, VIEW и т.п., преобразуются в сущности‑узлы, а их зависимости (внешние ключи, ссылки) фиксируются как ребра графа.
sql-- Пример DDL‑скрипта, который будет обработан
CREATE TABLE users (
id BIGSERIAL PRIMARY KEY,
username VARCHAR(50) NOT NULL,
email VARCHAR(100) UNIQUE,
created_at TIMESTAMP DEFAULT now()
);
CREATE TABLE orders (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT REFERENCES users(id),
total NUMERIC(12,2) NOT NULL,
status VARCHAR(20) DEFAULT 'pending',
placed_at TIMESTAMP DEFAULT now()
);
Конфигурационные файлы поддерживаются в форматах YAML, TOML и JSON.
Каждая секция превращается в объект‑узел, а ссылки между секциями (например, references в YAML) автоматически становятся ребрами.
yaml# Пример конфигурации, читаемой Graphify
services:
api:
image: myorg/api:1.2
ports:
- "8080:8080"
environment:
DB_HOST: postgres
DB_PORT: 5432
worker:
image: myorg/worker:0.9
depends_on:
- api
Во‑первых, Graphify сохраняет оригинальный синтаксис в метаданных, так что потом легко отследить, откуда взялась конкретная сущность.
С практической точки зрения удобно хранить схемы и конфиги в отдельном каталоге schema/ и указывать его в параметре --configs.
См. как интегрировать схемы с другими источниками
Обработка PDF‑документации и Markdown
Техническая документация часто поставляется в PDF или Markdown.
Graphify умеет извлекать текст из PDF‑файлов, парсить структуру заголовков и сохранять её как набор узлов‑параграфов.
bash# Импортировать PDF‑документацию и получить граф
graphify import --pdf ./docs/architecture.pdf --output ./docs.graph.json
Во время импорта Graphify использует OCR‑библиотеку для сканирования сканных PDF и затем применяет тот же AST‑парсер, что и для кода, чтобы выделить функции, классы и ссылки.
Для Markdown‑файлов процесс проще: каждый блок кода, заголовок # и список * преобразуются в соответствующие узлы.
markdown# Сервис аутентификации
## Основные компоненты
- **AuthController** — обработка запросов
- **TokenService** — генерация JWT
- **UserRepository** — взаимодействие с БД
bash# Парсим Markdown‑файл
graphify parse --input ./docs/README.md --output ./readme.graph.json
Если требуется объединить несколько источников (код, схемы, документацию), достаточно передать несколько путей через параметр --sources:
bashgraphify build \ --sources ./src ./schema/ ./docs/architecture.pdf ./docs/README.md \ --output ./full-graph.json
Таким образом, граф знаний становится единым источником правды, откуда можно генерировать автодокументацию, проверять целостность ссылок или питать AI‑агентов (Claude Code, Cursor, Gemini CLI).
Дополнительные практики из .agents
Готово.
Практические сценарии использования
Поиск зависимостей при рефакторинге
Во-первых, Graphify позволяет построить граф зависимостей между модулями, импортированными пакетами и вызовами функций без необходимости анализа статического кода вручную.
Следующий пример показывает, как запустить сканирование проекта и получить файл GraphML, который можно открыть в yEd или импортировать в Neo4j:
bashgraphify scan --project /path/to/project --output dependencies.graphml
Для визуализации удобно превратить граф в PNG с помощью Graphviz:
bashdot -Tpng dependencies.graphml -o dependencies.png
Если интересуют только определённые типы зависимостей, можно задать фильтр через параметр --filter. Например, чтобы отобразить только внешние библиотеки:
bashgraphify scan --project . --filter external --output external_deps.graphml
Во-вторых, результат сканирования удобно использовать в pull‑request’е: сравнивайте два файла GraphML, полученных до и после изменения, и видите, какие модули стали добавляться или удаляться.
Подробнее о работе с графом зависимостей
С практической точки зрения, такой подход уменьшает риск «сломать» скрытые связи, которые часто проявляются только после деплоя.
Автоматическое документирование архитектуры
В-третьих, Graphify умеет генерировать схемы архитектуры из кода, схем баз данных и документации, что позволяет быстро получать актуальные диаграммы без ручной рисовки.
Пример команды, генерирующей диаграмму системы на основе кода и SQL‑схемы:
bashgraphify generate \
--source /path/to/source \
--db schema.sql \
--output architecture.svg
Полученный SVG можно включить в README‑файл репозитория или в Confluence‑страницу, где поддерживается живой процесс документирования.
Для интеграции с Claude Code, Cursor или Gemini CLI удобно добавить в конфигурацию проекта файл .graphify.yml, например:
yamlproject_root: /home/alexey/projects/myapp
output_format: svg
include:
- src/
- db/
- docs/
После коммита в репозиторий CI‑pipeline автоматически запускает Graphify и публикует обновлённую диаграмму в артефактах сборки.
Пример использования Graphify в CI/CD
С практической точки зрения, автоматическое генерирование схем сокращает время, затрачиваемое на поддержание актуальности документации, и повышает предсказуемость системы, поскольку каждый изменок в коде сразу отражается в диаграмме.
Если требуется более детальная настройка, см. раздел «Навыки реальных инженеров: практические практики из .agents».
Часто задаваемые вопросы
Как Graphify строит граф знаний без векторных хранилищ?
Graphify парсит AST‑дерево исходного кода, извлекая классы, функции, переменные и их отношения. На основе этой структуры формируются вершины и ребра, описывающие зависимости, без применения эмбеддингов. Это обеспечивает детерминированный граф, где каждая связь предсказуема и воспроизводима.
Что требуется для определения связей между сущностями в коде?
Graphify использует импорты, комментарии, схемы баз данных и конфигурационные файлы, сопоставляя их с элементами AST. Правила связей задаются в YAML‑конфигурации, где указывается тип (например, uses), источник и цель. После сопоставления формируются ребра, отражающие реальные зависимости.
Как интегрировать Graphify с Claude Code, Cursor и Gemini CLI?
Интеграция осуществляется через командные строки, предоставляемые этими инструментами, которые вызывают Graphify parse или build с указанием входных файлов. Например, в Cursor можно добавить скрипт, который после парсинга AST сохраняет результат в файл знани‑графа. Аналогично, Gemini CLI принимает путь к проекту и генерирует dot‑файл для визуализации.
Как визуализировать полученный граф и какие форматы поддерживает Graphify?
Сгенерированный граф хранится в формате DOT, совместимом с GraphViz, или в JSON‑структуре, которую можно импортировать в любые визуализационные инструменты. Для быстрой проверки удобно открыть DOT‑файл в VS Code с расширением GraphViz Preview или в онлайн‑редакторе. Форматы вывода настраиваются параметром --output в командах parse и build.