CodeBuddy: Розумніше отримання контексту для AI-агентів з програмування

Проігнорована проблема в агентському програмуванні

Ентузіазм щодо AI-агентів для програмування цілком обґрунтований — Claude, Codex, Cursor та інші стали справді корисними інструментами. Але якщо використовувати їх протягом більше тижня для роботи з великою кодовою базою у реальному світі, поступово виникає знайома проблема.

Сам агент не є обмежуючим фактором. Проблема не в можливостях моделі. Проблема — у контексті.

Постійно з’являються два типи помилок:

1. Брак контексту у агента — ви даєте йому завдання, а він не знає, яких правил дотримується ваш проект, не пам’ятає про подібну помилку, яка вже була виправлена, а потім скасована, та не розуміє, які файли залежать від того, який саме файл він збирається змінити. Результатом є зміна, яка здається розумною окремо, але є неправильною для всієї системи.

Занурення агента у контекст — щоб уникнути цієї першої проблеми, ви надаєте йому весь репозиторій або дозволяєте йому без вибору шукати серед усього. Тепер кожне завдання виконується довше, коштує більше, а запит наповнюється шумом. Модель витрачає свій бюджет уваги на файли, які не мають значення, замість того, щоб зосередитися на кількох важливих.

Жоден з цих підходів насправді не стосується інтелекту моделі. Це обидва симптоми поганої роботи з контекстом. Саме цю проблему намагається вирішити 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, який створює чітко визначений пакет, що містить:

• Файли, які дійсно мають значення для завдання
• Конкретні функції та класи, які беруть участь, а не цілі файли, коли це можливо уникнути

Тести, які вже тестують цю частину коду

Специфічні для проекту конвенції чи правила, які тут застосовуються

Колишні баги чи регресії, пов’язані з цим фрагментом коду

Усі файли, які можуть постраждати після змін цільових файлів

Існуючі плани чи рішення, що стосуються цього завдання

Архітектурні зв’язки цих файлів, отримані з Graphify у разі його активності чи з внутрішнього індексу у разі її відсутності

Результатом є компактний, насичений та цілеспрямований пакет замість розгорнутого та неповноцінного. Саме ця різниця відрізняє справді контекстно обізнану поведінку від тієї, що лише імітує контекстну обізнаність.

3. Агент впроваджує зміни

Маючи цей пакет, Claude чи Codex мають достатньо інформації, щоб аналізувати наслідки у довгостроковій перспективі, а не лише негайні зміни — наприклад, які функції використовують цю функцію, які тести мають продовжувати проймати, та чи вже намагалися застосувати саме цей підхід раніше та чи було його скасовано.

4. CodeBuddy пам’ятає

Після завершення завдання агент може записати отримані знання назад у CodeBuddy: прийняті рішення, правила, виявлені протягом роботи, проблеми з регресією та підходи, які виявилися ефективними. Ці знання зберігаються локально, розподілені між базою даних Postgres та пам’яттю у форматі Markdown, і включаються до контекстного пакету для наступного схожого завдання. Замість того, щоб скидатися до нуля з кожною сесією, система стає все точнішою.

5. PR-запити перевіряються автоматично

Робочий процес GitHub може автоматично надавати звіти щодо кожного pull request, враховуючи:

• Наскільки ризикованою здається ця зміна
• Де відсутнє тестування
• Як ця зміна впливає на архітектуру
• Чи відхилилася реалізація від початкового плану
• Чи справді вдалося перевірити результат

Чому це має більше значення, ніж може здатися

Хочеться віднести це до категорії „ще один інструмент для розробки, створений на основі Claude“. Однак такий підхід не враховує кількох аспектів:

Він стосується справжнього бутлекорку. Моделі постійно стають все потужнішими з великою швидкістю. Однак якість контексту, який надається їм, на рівні інструментів не встигає за цим розвитком — більшість налаштувань все ще передбачають читання цілих файлів або пошук потрібної інформації з надією на краще. CodeBuddy базується на припущенні, що наступні значущі досягнення в сфері агентського програмування прийдуть від покращення того, що надається моделі, а не від самої моделі.

З часом він розвивається сам по собі. Вікно контексту за замовчуванням не має пам’яті — кожна сесія починається з нуля, якщо тільки оточуюча система не зберігає стан навмисно. Оскільки CodeBuddy відстежує рішення, правила та проблеми, десяте завдання у певній базі коду має виконуватися легше, ніж перше, без необхідності знову пояснювати те саме.

Він відкрито говорить про компроміси, замість того щоб їх приховувати. Роблення Graphify необов’язковим — це пряма відповідь на попередню спробу повністю усунути цей компроміс, яка не вдалася. Ви можете обрати: без додаткової налаштування та придатного легкого індексу, або справді точну архітектурну діаграму, якщо готові додати ще один компонент.

Усе залишається на вашому пристрої. PostgreSQL, система зберігання даних у форматі Markdown, внутрішній індекс та графи Graphify працюють локально. Креденції зберігаються у приватному файлі конфігурації. Щоб покращити роботу агента, не потрібно пересилати ваш кодовий базис кудись ще.

Він інтегрується з інструментами, які люди вже використовують. Це не новий редактор чи агент, якого потрібно вивчати — він безпосередньо підключається до Claude та Codex, працюючи там, де ви вже працюєте, і просто робить їх ефективнішими у розумінні кодового базису, який перед ними.

Яким буде подальший розвиток

Це все ще проєкт на ранній стадії, який активно удосконалюється, і саме система пам’яті має найбільш очевидний простір для покращень — наразі вона поводиться скоріше як структуровані нотатки, ніж як щось схоже на пам’ять із рангуванням даних. Якщо ви використовуєте штучні інтелектуальні агенти для кодування у реальному кодовому базі та стикаєтесь із проблемою „він не розуміє мого проєкту“, ваші відгуки справді будуть корисними:

npm install -g @ayushkumar320/codebuddy

Якщо ви спробуєте це, або якщо ви вирішили цю проблему іншим способом у своїй системі, буде корисно поділитися своїм досвідом.

CodeBuddy — це шар керування контекстом для штучних інтелектуальних агентів для кодування, таких як Claude та Codex. Він готує зосереджений, релевантний контекст замість того, щоб змушувати до читання всього репозиторію, і за бажанням може інтегруватися з Graphify для отримання більш детальної карти архітектури. Він доступний у npm як @ayushkumar320/codebuddy.

Пов’язана література

• Розуміння AI-агентів: цілі, інструменти, пам’ять та цикл дій агента — просте пояснення для початківців про те, чим AI-агенти відрізняються від чат-ботів, з описом основних компонентів, циклу прийняття рішень, рівнів автономії та прикладів їх використання у реальному світі.
• Порівняння AI-агентів Frontier: Astra, Flash, Fable та Mythos — аналіз продуктивності найновіших версій моделей GPT, Gemini та Claude у реальних завданнях, пов’язаних із агентними функціями, таких як програмування, перегляд інформації та використання інструментів, а не лише у тестах на базові здібності.

Як протокол Model Context Protocol дозволяє штучним інтелектуальним агентам знаходити та викликати інструменти — чітке пояснення MCP: як хости, клієнти та сервери дозволяють програмам на основі штучного інтелекту знаходити інструменти, викликати їх за допомогою структурованих вхідних даних, та які є їхні обмеження.