CodeGraph Technical Whitepaper
Гибридный многоагентный RAG + Code Property Graph для интеллектуального анализа кода
1. Аннотация
Проблема: Разработчики тратят 60% рабочего времени на понимание существующего кода. Традиционные инструменты (grep, IDE, ChatGPT) не справляются с контекстным анализом больших кодовых баз.
Решение: CodeGraph объединяет гибридный RAG (векторный + графовый поиск) с Code Property Graph для мгновенного ответа на вопросы о коде с полным пониманием контекста.
Результат: Ускорение анализа кода в 10-600 раз, повышение точности поиска на 33.6% по сравнению с традиционными подходами.
2. Проблема
Корпоративная разработка сталкивается с критическими проблемами при работе с большими кодовыми базами. Эти проблемы приводят к потере продуктивности, пропущенным уязвимостям и замедлению разработки.
| Проблема | Масштаб | Источник |
|---|---|---|
| Разработчики тратят 60% времени на понимание существующего кода | 90,000 разработчиков | GitHub Survey 2023 |
| Ручной code review пропускает до 80% уязвимостей | 100+ корпоративных проектов | Отчёт NIST |
| Онбординг новых сотрудников занимает 3-6 месяцев | Отраслевой стандарт | Опросы CTO |
| Документация устаревает за 2-4 недели | 500+ команд | Опрос разработчиков |
| Аудит безопасности занимает 2-4 недели вручную | Корпоративные проекты | Отраслевой бенчмарк |
Стоимость проблемы
Для команды из 50 разработчиков со средней зарплатой 200,000 руб./мес потери составляют:
- 60 млн руб./год — время на понимание кода (60% × 50 × 200K × 12)
- Неизмеримые риски — пропущенные уязвимости, утечки данных
- Замедление TTM — отложенные релизы из-за долгой проверки кода
3. Предпосылки: почему традиционные подходы не работают
Существующие инструменты анализа кода имеют фундаментальные ограничения:
Текстовый поиск (grep, IDE search)
- Проблема: Нет понимания семантики — ищет только точные совпадения строк
- Пример: Поиск SQL-инъекций не найдёт уязвимости с параметризованными запросами
- Результат: Низкая полнота, много пропущенных угроз
Статический анализ (SonarQube, CodeQL)
- Проблема: Требует предопределённых правил, не понимает намерение пользователя
- Пример: Нельзя спросить «какие функции обрабатывают пользовательский ввод?»
- Результат: Много ложных срабатываний, нет интерактивности
ChatGPT / Copilot
- Проблема: Ограниченное контекстное окно (128K токенов ≈ 2-3 файла)
- Пример: Не видит граф вызовов на 52 000 методов
- Результат: Галлюцинации, неполные ответы без учета контекста и зависимостей крупных корпоративных проектов
Вывод: Требуется система, которая сочетает семантическое понимание LLM с полным знанием структуры кодовой базы через граф кода (CPG).
4. Методология: Гибридный многоагентный RAG + кодовый граф
CodeGraph использует научно обоснованный подход, объединяющий три ключевые технологии:
4.1 Code Property Graph (CPG)
CPG — это унифицированное представление кода, объединяющее:
- AST (Abstract Syntax Tree) — синтаксическая структура
- CFG (Control Flow Graph) — поток управления
- PDG (Program Dependence Graph) — зависимости данных
- Call Graph — связи между функциями
4.2 Гибридный поиск
Комбинация двух методов поиска с RRF-слиянием:
| Метод | Что находит | Сильные стороны |
|---|---|---|
| Векторный поиск | Семантически похожие фрагменты кода | Понимание намерения, нечёткий поиск |
| Графовый поиск | Структурные связи (вызовы, зависимости) | Точный граф вызовов, поток данных |
| RRF-слияние | Объединённый ранжированный список | Лучшее из обоих подходов |
4.3 Многоагентная архитектура
Система использует 13 специализированных агентов, разделённых на три группы:
Основной конвейер
5 агентов, образующих последовательный конвейер обработки запросов:
| Агент | Роль | Функции |
|---|---|---|
| 1. Analyzer | Классификатор намерений | Понимание запроса, извлечение ключевых слов, выбор сценария |
| 2. Retriever | Гибридный поиск | Векторный + графовый поиск, RRF-слияние результатов |
| 3. Enrichment | Обогащение контекста | Маппинг на CPG-теги, добавление доменного контекста |
| 4. Generator | Синтез запросов | Генерация SQL/PGQ запросов с грамматическими ограничениями |
| 5. Interpreter | Интерпретатор | Синтез ответа на естественном языке, группировка, рекомендации |
Специализированные агенты
5 агентов для расширенного анализа и обработки ошибок:
| Агент | Роль | Функции |
|---|---|---|
| 6. CallChain Analyzer | Анализ цепочек вызовов | Построение графа вызовов, поиск путей между функциями |
| 7. Logic Synthesizer | Синтез логики | Генерация объяснений сложной бизнес-логики |
| 8. ControlFlow Generator | Поток управления | Генерация объяснений ветвлений и циклов |
| 9. Adaptive Refiner | Адаптивное уточнение | Уточнение запросов на основе обратной связи |
| 10. Fallback Strategies | Стратегии восстановления | Обработка ошибок, автоматическое восстановление |
Доменные агенты
3 агента для анализа специфических предметных областей:
| Агент | Роль | Функции |
|---|---|---|
| 11. Security Agent | Анализ безопасности | Обнаружение 67 типов уязвимостей CWE + 21 паттерн атак CAPEC |
| 12. Performance Agent | Анализ производительности | Цикломатическая сложность, вложенность циклов, паттерны памяти |
| 13. Architecture Agent | Анализ архитектуры | Границы слоёв, зависимости модулей, паттерны проектирования |
4.4 Покрытие уязвимостей CWE/CAPEC
Security Agent обнаруживает 67 типов уязвимостей CWE и связывает их с 21+ паттернами атак CAPEC:
| Категория | CWE | Примеры |
|---|---|---|
| Инъекции | 8 | SQL (CWE-89), Command (CWE-78), LDAP (CWE-90), Code (CWE-94) |
| Память | 13 | Buffer Overflow (CWE-120), Use-After-Free (CWE-416), Double Free (CWE-415) |
| Валидация ввода | 10 | Path Traversal (CWE-22), Deserialization (CWE-502), SSRF (CWE-918) |
| Криптография | 8 | Weak Crypto (CWE-327), Insufficient Entropy (CWE-331), Bad Certificate (CWE-295) |
| Аутентификация | 6 | Hardcoded Credentials (CWE-798), Missing Auth (CWE-306) |
| Веб-приложения | 5 | XSS (CWE-79), CSRF (CWE-352), Prototype Pollution (CWE-1321) |
| Многопоточность | 6 | Race Condition (CWE-362), TOCTOU (CWE-367), XXE (CWE-611) |
| Языковые | 11+ | Python/Django, JavaScript, Java, Go, C#, Kotlin, Swift, PHP, Ruby |
Паттерны атак CAPEC
Система связывает уязвимости CWE с реальными паттернами атак CAPEC для приоритизации:
| CAPEC ID | Атака | Связанные CWE |
|---|---|---|
| CAPEC-66 | SQL Injection | CWE-89 |
| CAPEC-88 | OS Command Injection | CWE-78 |
| CAPEC-86 | XSS через HTTP Headers | CWE-79 |
| CAPEC-100 | Buffer Overflow | CWE-120 |
| CAPEC-126 | Path Traversal | CWE-22 |
| CAPEC-586 | Object Injection (Deserialization) | CWE-502 |
| CAPEC-664 | Server-Side Request Forgery | CWE-918 |
| CAPEC-201 | XML External Entity (XXE) | CWE-611 |
И ещё 13+ паттернов CAPEC для race conditions, криптографических атак, форматных строк и др.
5. Техническая архитектура
5.1 Конвейер обработки запроса
5.2 Поддерживаемые LLM-провайдеры
CodeGraph поддерживает 4 LLM-провайдера с единым интерфейсом:
| Провайдер | Модели | Контекст | Особенности |
|---|---|---|---|
| GigaChat (Сбер) | GigaChat-2, -Pro, -Max | 32K | Российский провайдер, соответствие требованиям |
| Yandex AI Studio | Qwen3-235B, gpt-oss-120b, YandexGPT | до 262K | Большой контекст, совместимый с OpenAI API |
| OpenAI | GPT-5.2 | 128K | Международный стандарт |
| Локальный | Qwen3-Coder | 32K | Автономная работа, изолированная среда |
5.3 Поддерживаемые языки программирования
CodeGraph анализирует код на 13 языках:
| Категория | Языки | Расширения |
|---|---|---|
| Системные | C/C++ | .c, .h, .cpp, .hpp, .cc, .cxx |
| Enterprise | Java, C#, Kotlin | .java, .class, .jar, .cs, .kt, .kts |
| Web | JavaScript, TypeScript, PHP, Ruby | .js, .ts, .jsx, .tsx, .php, .rb |
| Scripting | Python, Go | .py, .go |
| Mobile | Swift, Kotlin | .swift, .kt |
| Бинарный анализ | Ghidra | .exe, .dll, .so, .dylib, .elf |
| IR | LLVM | .bc, .ll |
5.4 Технологический стек
| Компонент | Технология | Описание |
|---|---|---|
| Backend | Python 3.10+ / FastAPI | Async REST API + WebSocket |
| Frontend | TUI (Rich) + CLI | Терминальный интерфейс |
| Vector DB | ChromaDB | 250K+ документов в демо-базе, embeddings |
| Graph DB | DuckDB | CPG: 52K+ методов в демо-базе, SQL/PGQ |
| CPG Parser | Joern | 13 языков |
| Workflow | LangGraph | Оркестрация агентов |
| IDE Integration | ACP (Agent Client Protocol) | Zed, JetBrains, VS Code — stdio/HTTP/WebSocket |
6. Сценарии использования
CodeGraph предоставляет 17 готовых сценариев для типичных задач разработки:
Полный список сценариев
| # | Сценарий | Описание | Пример запроса |
|---|---|---|---|
| 1 | Аудит безопасности | Комплексный поиск уязвимостей (SQL injection, XSS, buffer overflow) | "Найди все SQL инъекции и потенциальные уязвимости" |
| 2 | Анализ поверхности атаки | Анализ точек входа безопасности (taint sources, sinks) | "Какие функции принимают user input?" |
| 3 | Расследование инцидентов | Реагирование на инциденты с рекомендациями | "Проанализируй CVE-2024-XXXX" |
| 4 | Онбординг | Навигация по кодовой базе для новых разработчиков | "Объясни архитектуру проекта" |
| 5 | Документирование | Автогенерация документации API и архитектуры | "Сгенерируй API документацию" |
| 6 | Код-ревью | Автоматизированный анализ PR/MR | "Проверь этот PR на проблемы" |
| 7 | Выявление технического долга | Количественная оценка технического долга | "Оцени технический долг модуля" |
| 8 | Анализ архитектуры | Обнаружение нарушений архитектуры | "Найди циклические зависимости" |
| 9 | Разработка новой функциональности | Помощь в разработке новых функций | "Где добавить новый endpoint?" |
| 10 | Рефакторинг | Рефакторинг и обнаружение неиспользуемого кода | "Найди неиспользуемые функции" |
| 11 | Массовый рефакторинг и обновление зависимостей | Масштабный рефакторинг (миграции API) | "План миграции с v1 на v2 API" |
| 12 | Оптимизация кода | Анализ производительности и узких мест | "Найди N+1 запросы к БД" |
| 13 | Улучшение тестового покрытия | Анализ покрытия тестами | "Какие функции не покрыты тестами?" |
| 14 | Пошаговый анализ и отладка | Помощь в отладке (logging, assertions) | "Найди все места с elog(ERROR)" |
| 15 | Выявление проблем многопоточности | Анализ конкурентности (deadlocks, races) | "Найди потенциальные race conditions" |
| 16 | Проверка соответствия требованиям | Проверка соответствия ФЗ-152, GDPR, HIPAA, OWASP | "Проверь на соответствие OWASP Top 10" |
| 17 | Кросс-репозиторный анализ | Анализ между репозиториями | "Найди дублирующийся код между repo A и B" |
7. Результаты и бенчмарки
7.1 Производительность системы
| Метрика | Значение | Комментарий |
|---|---|---|
| Latency (query) | 2-3 мс | Graph query к DuckDB CPG |
| E2E response time | < 5 сек | Включая все вызовы LLM (4-5 calls) |
| Throughput | 50+ QPS | 100+ параллельных пользователей |
| Memory per instance | < 4 GB | Экономия 90% vs vector-only решения |
7.2 Качество поиска
Сравнение подхода гибридного RAG с базовыми методами на тестовом наборе из 100+ вопросов:
| Метрика | Векторный | Графовый | Гибридный (CodeGraph) | Улучшение |
|---|---|---|---|---|
| Precision@10 | 0.218 | 0.200 | 0.300 | +37.5% |
| Recall@10 | 0.433 | 0.354 | 0.553 | +27.8% |
| F1@10 | 0.286 | 0.251 | 0.383 | +33.6% |
| MRR | 1.000 | 0.636 | 1.000 | +57.1% vs graph-only |
7.3 Бизнес-эффект
Измеримые результаты внедрения CodeGraph:
| Сценарий | Без CodeGraph | С CodeGraph | Ускорение |
|---|---|---|---|
| Онбординг разработчика | 3-6 месяцев | 2-4 недели | 6x |
| Аудит безопасности | 2-4 недели | 2-4 часа | 40x |
| Код ревью (PR) | 2-4 часа | 10-15 минут | 10x |
| Поиск функции в коде | 5-30 минут | 2-3 секунды | 600x |
| Генерация документации | 1-2 дня | 5 минут | 200x |
ROI для команды из 50 разработчиков: Экономия ~60 млн руб./год на понимании кода (60% → 10% времени) + снижение рисков безопасности через автоматический аудит.
8. Команда
CodeGraph разрабатывается командой с опытом в области:
- Статический анализ кода — опыт работы с Joern, CodeQL, Semgrep
- Машинное обучение — NLP, embeddings, LLM fine-tuning
- Enterprise-разработка — масштабируемые системы, высокие нагрузки
- Информационная безопасность — SAST/DAST/fuzzing, нормативные требования и стандарты
Контакт: Для обсуждения технических деталей или партнёрства свяжитесь с нами через форму на главной странице или напишите на hello@codegraph.ru
9. Заключение
CodeGraph решает фундаментальную проблему корпоративной разработки — понимание больших кодовых баз — через инновационное сочетание:
- Гибридный RAG — комбинация векторного и графового поиска с RRF-слиянием
- Code Property Graph — полное структурное представление кода
- Многоагентная архитектура — специализированные агенты для каждого этапа и сценария
- Мульти-провайдерность — GigaChat, Yandex, OpenAI, Локальные модели
Результаты:
- +33.6% улучшение F1@10 по сравнению с baseline
- 17 готовых сценариев для типичных задач
- 13 поддерживаемых языков программирования
- <5 сек время ответа на сложные вопросы
Готовы увидеть CodeGraph в действии?
Запросите персональную демонстрацию для вашей команды и кодовой базы
Запросить демо