CodeGraph помогает команде связать продуктовую задачу с требованиями, кодом, проверками и решением о выпуске. Этот раздел отвечает на вопросы о назначении платформы, первой полезной задаче и работе с ИИ, а затем помогает разобраться с подключением и анализом.
Назначение и выбор первого сценария
Зачем CodeGraph, если уже есть Git, трекер и CI?
В этих системах находятся код, задачи и результаты запусков. Чтобы принять изменение, команде нужно сопоставить их: какое требование реализовано, на какой ревизии выполнен тест, кто рассмотрел риск и что осталось проверить. CodeGraph хранит связи и результаты ролевой работы, чтобы это сопоставление оставалось доступным при передаче задачи.
Git, трекер и CI продолжают хранить свои основные записи. Набор доступных интеграций зависит от установки. Начните с одного репозитория и сценария из карты задач. Общая модель описана в архитектуре платформы.
Как CodeGraph связан с агентом, который пишет код?
Совместимый агент выполняет действия. CodeGraph добавляет контекст задачи, распределение ответственности, разрешённую область работы и связь результата с проверками. Цифровые сотрудники представляют роли продукта, разработки, архитектуры, безопасности и QA. Человек задаёт цель, доступ и условия приёмки.
Можно отдельно видеть подготовленное изменение и недостающую проверку. Принятая передача задачи подтверждает ответственность следующей роли. Фактический запуск автоматического исполнителя и полученные результаты проверяются отдельно.
Зачем использовать граф кода при работе с ИИ?
Граф свойств кода (CPG) связывает символы, вызовы и зависимости программы. Для изменения метода CodeGraph может исследовать методы, которые вызывают его напрямую или через другие методы, в том числе в других файлах. Эти связи помогают собрать контекст задачи и выбрать участки для проверки.
Например, команда меняет расчёт лимита в сервисе. Анализ влияния показывает потребителей изменяемого метода. Разработчик использует этот результат, чтобы проверить связанные вызовы и выбрать регрессионные тесты. Поиск структурных шаблонов помогает найти похожие конструкции, которые тоже стоит рассмотреть при изменении. Эти задачи описаны в карте возможностей анализа и руководстве по поиску шаблонов.
Для вопросов о передаче данных откройте руководство по потокам данных. Для проверки гипотезы об уязвимости используйте систему гипотез: она связывает гипотезу с результатом проверки и доказательствами в коде. Так у команды есть конкретные связи и позиции в исходниках для обсуждения изменения, а у агента — контекст для следующего действия.
Какую пользу можно проверить на небольшом пилоте?
Выберите задачу с понятным результатом: разобрать влияние изменения, проверить риск безопасности или связать требование с кодом и приёмкой. Зафиксируйте исходные затраты времени и правила оценки, выполните сценарий и сравните результат. Один конкретный сценарий позволит увидеть, где команда экономит время и получает более понятный результат.
Карта анализа помогает выбрать проверку. Для риска в коде прочитайте руководство по гипотезам; для рабочего изменения — руководство по ревью. Эффект пилота нужно измерить в вашей команде: сравните время разбора задачи, подготовки изменения и проверки результата.
Для сравнения 5–10 задач используйте пилотный бенчмарк. Руководство показывает, как задать исходные показатели и критерии успеха, собрать измерения и получить отчёт с рекомендацией по дальнейшему использованию CodeGraph.
Начало работы
С чего начать?
Если экземпляр CodeGraph уже развёрнут, пройдите быстрый старт: вход, доступ к проекту, импорт репозитория, проверка графа и первая задача. Для установки нового экземпляра используйте руководство по установке.
Как обновлять CPG и проверять PR/MR автоматически?
Подключите вебхук своего Git-сервиса: GitHub, GitLab, GitVerse или SourceCraft. В инструкциях показано, как связать репозиторий с проектом, настроить события push и PR/MR и проверить обновление графа и результат ревью. Для команды это два связанных действия: поддерживать контекст анализа в актуальном состоянии и получать проверку при обсуждении изменения.
Как настроить регулярный аудит и контроль архитектуры?
В расписании аудита задайте периодичность, часовой пояс, сервисный аккаунт и обработку пропущенных запусков. Проверьте первый запуск по истории заданий и сохранённому отчёту.
В руководстве по архитектурному контролю опишите компоненты и разрешённые зависимости, выберите правила и подключите проверку к обновлению CPG. Так договорённости о границах компонентов становятся проверяемыми правилами для изменений кода.
Нужны ли все сервисы для локального знакомства?
Нет. Запускайте только интерфейсы, которые нужны вашей задаче. У анализа через CLI и проверки веб-интерфейса после входа разные зависимости. При ошибке запуска используйте актуальное руководство по диагностике: определите нужные сервисы и проверьте их состояние.
Проекты и свежесть графа
Зачем обязательно выбирать проект?
Выбранный проект определяет контекст репозитория, расположение CPG, авторизацию, память и привязку доказательств. Идентификатор указывает проект, а разрешение сервер получает из аутентифицированного запроса с допустимым проектным контекстом.
Почему результат пуст или не совпадает с исходным кодом?
Проверьте, что проиндексирована ожидаемая ревизия, язык поддерживается, исключения заданы верно, а синхронизация проекта завершена. Пустой результат может означать «не найдено», но также бывает следствием устаревшего контекста, неполного покрытия графа или неверно выбранного проекта.
Анализ и доказательства
Какую команду анализа выбрать?
Откройте карту возможностей анализа: review — находки по изменениям, impact —
зона влияния, patterns — структурный поиск, hypothesis — гипотезы безопасности по CPG,
threat-model — границы доверия, sbom — анализ состава ПО и зависимостей (SCA). Подготовьте CLI по руководству. Перед автоматизацией вызовите python -m src.cli --help и --help выбранной подкоманды.
Как использовать результаты анализа при выпуске?
Сохраните результат анализа вместе с точной ревизией кода и областью проверки. В управляемой задаче CodeGraph связывает его с результатами приёмки, ревью, проверки безопасности, тестирования, документации, требованиями, проверкой работающего экземпляра и финансовым контролем. Так команда видит, какие проверки выполнены для выпуска и какие ещё предстоит выполнить.
Можно ли автоматически применять исправления CodeGraph?
Некоторые процессы предлагают или подготавливают изменения. Работайте с ними как с обычным патчем: проверьте различия в исходниках, выполните тесты затронутых функций и регрессионные тесты, оцените безопасность и сохраните план отката. Применение патча и публикация проходят через предусмотренные процессом ревью и одобрение.
MCP и цифровые сотрудники
Почему MCP-инструмент отсутствует?
Видимость зависит от работающего сервера, активного профиля, политики владельца и подключения клиента. Следуйте руководству оператора MCP. Список инструментов клиента показывает доступные имена и схемы. Успешный вызов подтверждает работу конкретного инструмента в текущем профиле и контексте проекта.
Как передавать структурированные аргументы MCP?
Передавайте нативные массивы и объекты, а не JSON внутри строк. Передавайте идентификаторы и поля области действия из схемы конкретного инструмента. Проект, пространство имён (namespace), пользовательская история и задача нужны только там, где этого требует схема и контракт операции. Лёгкая служебная задача может не иметь пользовательской истории. Не передавайте пути к БД через MCP-инструменты для агента: сервер определяет хранилище по разрешённому контексту.
Какие полномочия дают цифровые сотрудники?
Каждая роль выполняет свою часть работы в пределах доступа к проекту и согласованной задачи. Роли, капсулы задач, передачи и закрытие описаны в статье об управляемых цифровых сотрудниках. Человеческое одобрение действует только для точно указанных в подписанном разрешении перехода и области действия.
Безопасность и работа с данными
Можно ли отправлять код внешней LLM?
Только если это допускают политика развёртывания, настройка провайдера и классификация данных. Перед включением провайдера прочитайте руководство по безопасности LLM. Не помещайте секреты в промпты, логи, аргументы команд, тестовые данные и публичную документацию.
Поддерживается ли прямая интеграция через DuckDB?
Для интеграции используйте CLI, REST, MCP, ACP с выбранным проектом или интерфейсы GoCPG. Выберите интерфейс по задаче: REST для приложения, MCP или ACP для агента, CLI для сценария автоматизации, GoCPG для работы с графом. Укажите проект или его CPG согласно инструкции выбранного интерфейса. Примеры запросов приведены в справочнике REST API, подключение агента — в руководстве оператора MCP.
Куда сообщить о предполагаемой уязвимости?
Не публикуйте детали эксплуатации и секреты в открытом обращении. Отправьте сообщение на hello@codegraph.ru. Укажите затронутую ревизию, описание, оценку влияния и минимальное безопасное воспроизведение. Сохраняйте нужные логи без учётных данных.
Ошибки и восстановление
Что приложить к обращению в поддержку?
Укажите установленную ревизию, ОС, интерфейс, точную форму команды или запроса, выбранный проект, ожидаемое поведение, ошибку и фрагмент лога без секретов. Напишите, воспроизводится ли проблема и актуален ли проектный контекст.
Стоит ли повторять управляемое действие с другим ID задачи?
Сначала проверьте статус существующей задачи и причину отказа. Если результат уже сохранён, продолжите работу с ним. Если запуск прерван, следуйте инструкции по восстановлению для этой операции. Сохранение ID связывает повторный запуск с исходной задачей и её предыдущими результатами.
Где искать дальше?
Известные операционные симптомы собраны в руководстве по диагностике, маршрутизация задач — в карте сценариев. Контракт установленной версии проверяйте через справку CLI или список инструментов MCP. Текущий код и наблюдаемое поведение важнее архивных примеров.