CodeBuddy: Более умное извлечение контекста для ИИ-агентов по программированию
Объясняется, как система поиска контекста на основе графа зависимостей помогает ИИ-агентам по программированию избегать как нехватки контекста, так и его чрезмерной нагрузки в крупных кодовых базах.
Занедбанный проблемный аспект в агентном программировании
Энтузиазм вокруг ИИ-агентов для программирования вполне оправдан — Claude, Codex, Cursor и другие действительно стали полезными инструментами. Но если использовать их более недели для работы с крупной реальной кодовой базой, появляется хорошо знакомая проблема.
Сам агент не является ограничивающим фактором. Проблема не в возможностях модели. Проблема — в контексте.
Постоянно возникают два типа сбоев:
- Недостаток контекста у агента — вы задаёте ему задачу, но у него нет представления о правилах проекта, нет памяти о похожей ошибке, которая была исправлена, а затем откатирована, нет понимания того, какие файлы зависят от того, с которым он собирается работать. В результате получается изменение, которое кажется разумным по отдельности, но ошибочным для всей системы.
Ни один из этих подходов на самом деле не связан с интеллектом модели. Оба являются проявлениями плохой обработки контекста. Именно это и является основной проблемой, которую пытается решить CodeBuddy.
Создано как временное решение, а не как запланированный продукт
Задолго до появления CodeBuddy в виде инструмента его основная идея уже применялась вручную.
Каждый раз, когда в проекте, использующем Claude, требовалось внести реальные изменения, процедура всегда была одинаковой: находили соответствующие функции, искали тесты, покрывающие эту часть кода, извлекали любые примечания, объясняющие, почему всё построено именно так, и вставляли всё это в диалог ещё до того, как описать изменения. Этот метод срабатывал, но был утомительным, повторяющимся и полностью зависел от запоминания структуры кода — памяти, которая неизбежно ухудшается по мере роста проекта.
В конце концов возник очевидный вопрос: почему человек выполняет функцию механизма поиска контекста? Это механическое, повторяющееся задание. Оно должно выполняться автоматически, а не в голове у человека.
Именно отсюда и возник CodeBuddy — не из решения создать «инструмент для разработчиков ИИ», а из решения прекратить выполнять такие поиски вручную.
Ложный сокращенный путь: избегание Graphify
Автоматизация этого шага получения информации требовала определения того, как CodeBuddy будет понимать структуру проекта — какие файлы зависят друг от друга, что вызывает что и где проходят реальные архитектурные границы.
Отдельный проект Graphify уже решил эту проблему, создав настоящую диаграмму зависимостей кодовой базы, отражающую реальные связи между файлами вместо того, чтобы выводить их на основе шаблонов названий или расположения. Использование его в качестве инструмента для анализа зависимостей казалось избыточной сложностью — ещё один элемент, ещё один шаг установки, ещё одна потенциальная причина сбоев. Первоначальным планом было полностью обойтись без него и заставить CodeBuddy создавать собственный легкий архитектурный индекс с помощью извлечения символов, анализа совместного присутствия файлов и нескольких эвристик — ровно столько, сколько нужно, чтобы направить агента в разумном направлении.
Этот подход оказался недостаточным.
Легкий индекс мог показать, что находится рядом с чем, но он не мог надежно объяснить, почему два файла действительно связаны, и не мог проследить цепочку зависимостей на глубину трех-четырех уровней — именно такая информация имеет наибольшее значение перед тем, как вносить изменения в код с широкими последствиями. Повторяющиеся случаи показывали, что агент вносил изменения, которые на первый взгляд казались безопасными, но нарушали что-то на следующем уровне, просто потому что индекс не смог с достаточной точностью зафиксировать эту связь.
Это привело к изменению подхода. Вместо того чтобы рассматривать Graphify как дополнительную составляющую, которую можно игнорировать при проектировании, он стал ключевой частью системы: CodeBuddy по-прежнему работает самостоятельно, используя свой внутренний индекс, для тех, кто предпочитает не добавлять дополнительную настройку. Однако при установке Graphify CodeBuddy опирается на его граф в качестве авторитетного источника информации об архитектурных связях, вместо того чтобы полагаться на догадки.
Именно это изменение направления и является настоящей причиной текущего способа работы — не какая-то новая функция, добавленная в последний момент, а признание того, что более простой дизайн на самом деле был хуже, после чего происходит перестройка с учётом именно той зависимости, которую изначально пытались избежать.
Как выглядит CodeBuddy на практике сегодня
1. Настройка
npm install -g @ayushkumar320/codebuddy
codebuddy
Запуск codebuddy внутри проекта обрабатывает не очень привлекательные, но необходимые шаги настройки:
- Подключается к локальной базе данных PostgreSQL
- Применяет схему и настройки, необходимые конкретному проекту
- Генерирует закрытый файл конфигурации, предназначенный исключительно для этого проекта
- Интегрируется с Claude и Codex, добавляя инструкции, которые указывают агенту, как использовать инструменты CodeBuddy
- Просит пользователя решить, включать ли функцию Graphify
Если вы решите включить Graphify, он подключит свой сервер MCP, после чего выполнение команды /graphify . один раз позволит создать первоначальную архитектурную карту проекта. Отказ от этой опции означает, что CodeBuddy будет использовать собственный легкий индекс — инструмент всё равно будет полностью функционировать, но получаемая архитектурная картина будет менее точной.
2. Основной цикл: context_pack
Именно здесь происходит основная работа. Когда вы задаёте агенту задачу — например, «добавить вход через OAuth» — он не начинает случайно просматривать файлы или загружать весь репозиторий. Вместо этого он вызывает инструмент CodeBuddy context_pack, который формирует тщательно отобранный пакет, содержащий:
- Файлы, которые действительно важны для выполнения задачи
- Конкретные функции и классы, необходимые для работы, а не целые файлы, если это возможно
В результате получается небольшой, компактный пакет, сосредоточенный на конкретной теме, вместо обширного и разрозненного. Именно это отличие позволяет отличить действительно учитывающее контекст поведение от того, что лишь кажется таковым.
3. Агент реализует изменения
Имея в своем распоряжении этот пакет, Claude или Codex могут анализировать не только непосредственные изменения, но и их последствия — например, какие функции зависят от данной функции, какие тесты должны продолжать проходить успешно, а также был ли ранее применен точно такой же подход и затем отклонен.
4. CodeBuddy запоминает
После завершения задачи агент может сохранить полученные знания обратно в CodeBuddy: принятые им решения, выявленные правила, возникшие проблемы, эффективные методы решения. Эти знания хранятся локально, распределенные между базой данных Postgres и памятью в формате Markdown, и включаются в контекстный пакет для следующей связанной задачи. Вместо сброса всех данных к нулю при каждой сессии система становится все более точной.
5. PR-запросы проверяются автоматически
Рабочий процесс GitHub может автоматически отчитываться о каждом pull-запросе, включая:
- Насколько рискованной кажется эта замена
- Где отсутствует покрытие тестами
- Как эта замена влияет на архитектуру
- Отклонилась ли реализация от первоначального плана
- Успешно ли прошла проверка
Почему это важнее, чем кажется
Хочется отнести это к категории «еще один инструмент для разработчиков на базе Claude». Однако такой подход упускает несколько аспектов:
Он направлен на решение настоящей проблемы. Модели постоянно становятся всё более мощными. Качество контекста, который им предоставляется, на уровне инструментов не соответствует этому росту — большинство решений по-прежнему предусматривают чтение целых файлов или использование простых методов поиска в надежде на лучшее результата. CodeBuddy основан на предположении, что следующий значимый прорыв в агентном программировании произойдет благодаря улучшению того, что поступает в модель, а не самой модели.
Со временем он совершенствуется сам по себе. По умолчанию окно контекста не имеет памяти — каждая сессия начинается заново, если только окружающая система намеренно не сохраняет состояние. Поскольку CodeBuddy отслеживает принятые решения, правила и возникающие сбои, десятая задача в определенной базе кода должна выполняться более гладко, чем первая, без необходимости повторного объяснения одних и тех же вещей.
Он откровенно рассказывает о компромиссах, вместо того чтобы их скрывать. Возможность использования Graphify по желанию — это прямой ответ на предыдущую попытку полностью устранить этот компромисс, которая не увенчалась успехом. Вы можете сами выбрать: либо без дополнительной настройки и приемлемый легкий индекс, либо действительно точную архитектурную схему, если готовы добавить еще один компонент.
Всё остаётся на вашем устройстве. PostgreSQL, хранилище данных в формате Markdown, внутренний индекс и графы от Graphify работают локально. Учётные данные хранятся в закрытом конфигурационном файле. Чтобы улучшить понимание контекста агентом, не требуется переносить ваш кодовый базис никуда ещё.
Он интегрируется в инструменты, которые люди уже используют. Это не новый редактор и не новый агент, которого нужно изучать — он подключается непосредственно к Claude и Codex, работая там, где вы уже занимаетесь своей работой, и просто делает их более эффективными в понимании кодового базиса перед ними.
Как это будет развиваться дальше
Это всё ещё проект на ранней стадии активной разработки, и особенно в системе памяти есть наиболее очевидные возможности для улучшения — в настоящее время она ведёт себя скорее как структурированные заметки, чем как система памяти с ранжированием по степени важности. Если вы используете ИИ-агентов для программирования в реальном кодовом хранилище и сталкиваетесь с проблемой «он не понимает мой проект», мы действительно приветствуем ваши отзывы:
npm install -g @ayushkumar320/codebuddy
Если вы попробуете это использовать или решали эту проблему другим способом в своей среде, будет полезно поделиться своим опытом.
CodeBuddy — это слой управления контекстом для ИИ-агентов, таких как Claude и Codex. Он готовит сфокусированный, релевантный контекст вместо того, чтобы заставлять читать весь репозиторий, и при необходимости может интегрироваться с Graphify для получения более детальной карты архитектуры. Он доступен в npm под именем @ayushkumar320/codebuddy.
Связанная литература
- Понимание ИИ-агентов: цели, инструменты, память и цикл действий агента — простое для новичков объяснение того, чем ИИ-агенты отличаются от чат-ботов, с описанием ключевых компонентов, цикла принятия решений, уровней автономии и практических применений в реальном мире.
- Сравнение современных ИИ-агентов: Astra, Flash, Fable и Mythos — анализ производительности новейших версий моделей GPT, Gemini и Claude при выполнении реальных задач агентов, таких как программирование, поиск информации и использование инструментов, а не только при выполнении тестовых заданий.