Почему каждому ИИ-агенту для программирования нужен граф знаний кода

В 2026 году Claude Code в терминале и Cursor в IDE меняют десятки файлов за проход, гоняют тесты и читают логи. Что тормозит продуктовые команды в крупных репозиториях — не «модель плохо пишет код», а неполная зона влияния: переименовали Swift-протокол — забыли conformance в extension-target; поменяли публичный API — моки в тестах остались старыми; сдвинули Pod-модуль — и только ночной пайплайн на облачном Mac падает.

Больший контекст, сильнее модель, больше @-файлов — всё это снимает симптомы. Граф знаний кода (CKG) переводит понимание репозитория из вероятностной похожести в запрашиваемую структуру. Ниже — что такое CKG, почему RAG системно промахивается, как сюда ложатся LSP и SCIP и какие узлы Xcode нужны iOS-командам.

Что такое граф знаний кода?

Не маркетинговый штамп, а явная модель сущностей и связей в коде:

• Узлы — файлы, каталоги, модули (npm-workspace, Gradle-subproject, Swift Package), символы (типы, функции, extensions), тесты, CI-джобы, Xcode Target и Scheme.
• Рёбра — imports, calls, inherits, implements, references, tests, owns, builds.

Векторные хранилища отвечают: «какие фрагменты похожи на мой вопрос?» Граф отвечает: «от символа A по цепочке вызовов и границам модулей обязательно проходят какие узлы?» При рефакторинге, security-fix и breaking API важен второй тип вопроса.

В командах с формальным ревью и комплаенсом CKG даёт объяснимость: почему агент открыл файл Z — не только «модель сочло релевантным».

Почему RAG и гигантское окно всё равно пропускают файлы

Типичная индексация агента: нарезка, эмбеддинг, top-k в prompt, правки. Работает для изолированных фич. Системно ломается здесь:

Зрелая схема: граф сужает кандидатов, эмбеддинги снимают неоднозначность имён («LoginHandler» vs «AuthService»). Оптимизировать только одно — бить мимо узкого места.

Где граф сидит в цикле агента

Прод-цикл: plan → retrieve → edit → verify. CKG усиливает планирование, retrieval и проверку scope в verify:

Plan. Задача: «перевести PaymentService на async/await». Сначала запрос к графу: ссылки, модуль, тесты — потом подзадачи. Не заливать весь src/ вслепую.

Retrieve. Обязательные файлы = обход графа плюс CLAUDE.md / .cursorrules — меньше галлюцинированных путей.

Verify. После патча: остались рёбра на старые символы? В CI: diff графа рядом с git diff.

Как строить граф: LSP, SCIP, компилятор

Распространённые пути:

• LSP — точность символов как в IDE; сильные экосистемы Swift, TypeScript, Go.
• SCIP / LSIF — monorepo, артефакты CI, привязка к commit.
• tree-sitter — лёгкий для sandbox; динамические вызовы требуют эвристик.
• Граф сборки Xcode — реальные зависимости target и линковки Apple.

Золотое правило: commit графа = commit, который правит агент. Оборванный индекс на ноутбуке → план по устаревшим рёбрам. Поэтому индексируют на фиксированном runner — например OpenClaw и CI на облачном Mac, где Xcode, Pods, подпись и тесты делят ту же macOS-правду, что и индекс.

iOS и macOS: дополнительные узлы

«Файл → функция» для Swift часто мало. На практике у клиентов ZavCloud:

• Target / Scheme — extension vs host app как явная зависимость.
• SPM / CocoaPods — source pod vs binary: рёбра «читаемый код» vs «только линк».
• @objc / динамический dispatch — рёбра «возможна runtime-привязка»; агент предлагает UI-тесты.
• Generated code — SwiftGen, Protobuf помечены generated, без ручного патча.

Если разработка на Windows/Linux, а сборка только в облаке — граф должен совпадать везде. См. Mac mini vs облачный Mac для iOS-команд и Xcode на Windows в 2026: узкое место часто граф сборки ≠ граф кода, а не GHz на столе.

Оркестрация, OpenClaw и обрывистые сессии

Агент будят из Slack или Telegram (шлюз OpenClaw и аналоги) — контекст чата тонкий. CKG становится долгой памятью вне окна: какие модули тронул последний PR, где тесты тонкие — через query, а не экспорт 200k токенов переписки.

Оркестратор решает когда индексировать и тестировать; граф — где менять. Квитанции (репо, команда, exit code, краткий лог) плюс diff графа упрощают разбор: «агент подтянул все ссылки?»

LSP, SCIP и tree-sitter: что выбрать и когда

Команды часто спрашивают: «достаточно индекса IDE или нужен CI-индекс?» На практике это часто два экспорта одной модели графа. LSP даёт быстрые, точные по символам рёбра для интерактивного агента: rename, go-to-definition, find references. SCIP/LSIF даёт артефакт, привязанный к commit, который можно переиспользовать на runner — удобно, когда несколько разработчиков ведут feature-ветки параллельно и агент в Actions должен видеть те же рёбра, что и локально.

tree-sitter уместен, если агент работает в sandbox без полного compiler graph (например, только поддерево monorepo). Ограничение: динамические языки и Objective-C bridges требуют дополнительных правил. Для Swift/iOS зрелые команды сочетают LSP для исходников с метаданными сборки Xcode для target — иначе граф кода верный, а агент запускает тесты в неверном scheme. Зафиксируйте в CLAUDE.md, какой путь индекса для какой задачи: так вы не смешаете устаревший LSP-dump со свежим SCIP-артефактом на одном PR.

Для распределённых команд полезен единый «графовый контракт»: формат экспорта, версия парсера и commit SHA в метаданных каждого запроса агента. Без этого два разработчика на одной ветке получают разные списки файлов на одну и ту же инструкцию — и ревью превращается в угадайку.

Анализ влияния как продукт, не интуиция

Многие команды требуют список влияния до merge. RAG не гарантирует полноту. С CKG анализ влияния — это:

• замыкание ссылок — все рёбра от изменённого символа;
• границы модулей — кто экспортирует API;
• карта тестов — какие spec должны стать зелёными;
• scope CI — какие target по builds пересобрать.

Это можно вшить в комментарии PR или план агента — ревьюер и модель видят один список. Меньше «увидели только на staging».

Стоимость, доверие, безопасность

Полный индекс крупного monorepo — CPU и десятки минут. Стратегия: инкремент (изменённые файлы + соседи) и кэш по SHA commit. На облачном Mac — снимок на длинную ветку; агент монтирует ту же версию при старте.

Доверие: каждое ребро с версией парсера и commit; без выдуманных зависимостей. В чувствительных репо — не экспортировать пути с секретами, каталоги клиентских данных и конфиги с токенами: граф описывает структуру, не сырой dump.

Минимальный старт на этой неделе

1. Выбрать Swift Package или сервисный модуль; экспорт символов и ссылок через LSP или SCIP.
2. В CLAUDE.md: перед публичным API — список ссылок скриптом из графа.
3. GitHub Actions self-hosted на облачном Mac: PR → инкрементальный индекс + тесты; в логах — непокрытые рёбра references.

# Символ → рёбра references (не семантический поиск)
refs = graph.out_edges(symbol="PaymentService.charge", type="references")
files = unique([r.source_file for r in refs])
# files в план агента, затем claude / cursor agent

Итог: памяти агента нужна топология

Модели сильнеют — топология ПО не становится сплошным текстом. Пока есть модули, вызовы и графы сборки, ИИ-агентам программирования нужен граф знаний кода для «одно изменение — много мест». Векторы — ассоциация; граф — анатомия. Строить оба на воспроизводимой macOS CI (облачный Mac) и отдавать Claude Code, Cursor или OpenClaw — незаметный, но обязательный шаг от демо к продакшену в 2026.

• Инструменты — Claude Code vs Cursor
• CI — OpenClaw и облачный Mac
• iOS — Mac mini vs облачный Mac · Xcode на Windows
• Агенты — OpenHuman vs OpenClaw
• Хостинг — Аренда Mac mini в облаке