CodeBuddy: Mądrzejsze pobieranie kontekstu dla agentów programistycznych AI

Zaniedbywany problem w kodowaniu za pomocą agentów

Energia wokół agentów do kodowania opartych na AI jest w pełni uzasadniona — Claude, Codex, Cursor i inne stały się naprawdę przydatnymi narzędziami. Jednak poświęć więcej niż tydzień na używanie takiego agenta w dużym, rzeczywistym kodowaniu, a pojawia się znajomy problem.

Sam agent nie jest czynnikiem ograniczającym. To nie możliwości modelu się psują — to kontekst przestaje być dostępny.

Dwa powtarzające się wzorce niepowodzeń pojawiają się raz za razem:

1. Głodzenie agenta kontekstem — przekazujesz mu zadanie, a on nie ma pojęcia o konwencjach stosowanych w twoim projekcie, nie pamięta o podobnym błędzie, który został naprawiony, a potem cofnięty, ani nie wie, które pliki zależą od tego, który ma teraz edytować. Rezultatem jest modyfikacja, która wydaje się rozsądna osobno, ale jest błędna dla całego systemu.

Zanurzanie agenta w kontekście — aby obejść ten pierwszy problem, podaje się mu cały repozytorium lub pozwala mu bezkrytycznie przeszukiwać wszystko. W rezultacie każde zadanie trwa dłużej, jest droższe, a prompt jest pełen szumów. Model traci swój budżet uwagi na pliki, które nie są istotne, zamiast na te nieliczne, które faktycznie mają znaczenie.

Żadne z tych rozwiązań nie dotyczy naprawdę inteligencji modelu. Obie są objawami słabej inżynierii kontekstu. To właśnie jest prawdziwy problem, który CodeBuddy ma na celu rozwiązanie.

Po powstaniu jako rozwiązanie tymczasowe, a nie zaplanowany produkt

Długo przed pojawieniem się CodeBuddy jako narzędzia, jego podstawowa idea była już stosowana ręcznie.

Zawsze, gdy w projekcie wykorzystującym Claude konieczna była rzeczywista zmiana, procedura była taka sama: znajdować odpowiednie funkcje, szukać testów obejmujących daną część kodu, przeglądać notatki wyjaśniające, dlaczego coś zostało zbudowane w taki sposób, a następnie wklejać to wszystko do rozmowy, zanim jeszcze opisano zmianę. To działało, ale było to męczące, powtarzalne i polegało wyłącznie na pamięci kodu – pamięci, która nieuchronnie słabnie w miarę rozwoju projektu.

Ostatecznie pojawiło się oczywiste pytanie: dlaczego to człowiek pełni rolę mechanizmu wyszukiwania kontekstu? To jest zadanie mechaniczne, powtarzalne. Należy ono do automatyzacji, a nie do pamięci człowieka.

Właśnie stąd wziął się CodeBuddy – nie była to decyzja o stworzeniu „narzędzia dla programistów AI”, lecz decyzja o zaprzestaniu ręcznego wykonywania tych poszukiwań.

Fałszywy skrót: unikanie Graphify

Automatyzacja tego kroku pobierania oznaczała konieczność podjęcia decyzji o tym, jak CodeBuddy ma rozumieć strukturę projektu — które pliki odwołują się do których, co wywołuje co oraz gdzie znajdują się rzeczywiste granice architektoniczne.

Odrębny projekt, Graphify, już zajmował się tym problemem, tworząc rzeczywisty graf zależności kodu, mapując prawdziwe relacje między plikami zamiast wnioskować je na podstawie wzorców nazewniczych lub bliskości. Włączenie go jako elementu zależności wydawało się niepotrzebną złożonością — kolejnym elementem, który może zawieść, kolejnym krokiem instalacji, kolejnym potencjalnym punktem awarii. Początkowy plan zakładał całkowite pominięcie tego rozwiązania i zamiast tego umożliwienie CodeBuddy stworzenia własnego, lekkiego indeksu architektonicznego przy użyciu ekstrakcji symboli, współwystępowania plików oraz kilku heurystyk — wystarczająco dużo, by skierować agenta we właściwym kierunku.

To podejście okazało się niewystarczające.

Lekki indeks mógł pokazywać, co znajduje się w pobliżu czego, ale nie potrafił wiarygodnie wyjaśnić, dlaczego dwa pliki są faktycznie powiązane, ani prześledzić łańcucha zależności na trzy lub cztery poziomy w głąb – dokładnie tego rodzaju informacje są najważniejsze przed modyfikacją kodu o dużym zasięgu oddziaływania. Wielokrotnie agent wprowadzał zmiany, które na pierwszy rzut oka wydawały się bezpieczne, ale psuły coś na drugim poziomie, po prostu dlatego, że indeks nie uchwycił tej relacji z wystarczającą precyzją.

To doprowadziło do zmiany podejścia. Zamiast traktować Graphify jako opcjonalny element o dodatkowym obciążeniu, który należy dostosować, stał się on kluczową częścią systemu: CodeBuddy nadal funkcjonuje samodzielnie, wykorzystując swój wewnętrzny indeks, dla tych, którzy wolą uniknąć dodatkowych ustawień. Jeśli jednak zainstalowany jest Graphify, CodeBuddy polega na jego grafie jako autorytatywnym źródle informacji o relacjach architektonicznych, zamiast polegać na domysłach.

To zmianę kierunku stanowi prawdziwa historia stojąca za obecnym sposobem pracy — nie nowa funkcja dodana na siłę, lecz uznanie, że prostszy projekt w rzeczywistości był gorszy, po czym nastąpiło odbudowanie wokół właśnie tej zależności, której pierwotnie unikano.

Jak wygląda CodeBuddy w praktyce dzisiaj

1. Przygotowanie

npm install -g @ayushkumar320/codebuddy
codebuddy

Zapусk codebuddy wewnątrz projektu zajmuje się mniej atrakcyjnymi, ale niezbędnymi krokami konfiguracji:

• Łączy się z lokalną bazą danych PostgreSQL
• Stosuje schemat i ustawienia potrzebne konkretnemu projektowi
• Generuje plik konfiguracyjny dostępny wyłącznie dla tego projektu
• Integruje się z Claude i Codex, dodając instrukcje pokazujące agentowi, jak korzystać z narzędzi CodeBuddy
• Prosi o decyzję dotyczącą włączenia Graphify

Wybór włączenia Graphify łączy jego serwer MCP, po czym wykonywanie polecenia /graphify . raz buduje początkową mapę architektury projektu. Odrzucenie tej opcji oznacza, że CodeBuddy korzysta ze swojego własnego lekkiego indeksu — narzędzie nadal funkcjonuje w pełni, ale uzyskany obraz architektury jest mniej precyzyjny.

2. Podstawowy cykl: context_pack

Tutaj odbywa się prawdziwa praca. Gdy przekazujesz agencie zadanie — na przykład „dodaj logowanie OAuth” — nie zaczyna on losowo przeglądać plików ani przechwytywać całego repozytorium. Zamiast tego wywołuje narzędzie CodeBuddy’ego context_pack, które tworzy ściśle określony zestaw zawierający:

• Pliki, które faktycznie są istotne dla danego zadania
• Konkretne funkcje i klasy, a nie całe pliki, o ile to możliwe

Testy, które już wykorzystują daną część kodu

Konwencje lub zasady specyficzne dla projektu, które tu obowiązują

Wcześniejsze błędy lub regresje związane z tą sekcją kodu

Wszystkie pliki, które ulegną zmianie po modyfikacji wybranych plików

Istniejące plany lub decyzje istotne dla tego zadania

Związki architektoniczne pomiędzy tymi plikami, pobierane z Graphify wtedy, gdy jest aktywny, lub z wewnętrznego indeksu w przeciwnym razie

W rezultacie powstaje mały, zintegrowany pakiet dotyczący bezpośrednio tematu, a nie rozległy i nieskondensowany. To właśnie ta różnica odróżnia rzeczywiście świadome kontekstu zachowanie od tego, co jedynie wygląda na takie.

3. Agent wdraża zmianę

Z tym pakietem Claude lub Codex mają wystarczające informacje, by analizować dalsze skutki, a nie tylko bezpośrednie różnice — na przykład które funkcje korzystają z tej funkcji, jakie testy muszą nadal przepadać oraz czy ten konkretny sposób został już wcześniej wypróbowany i odrzucony.

4. CodeBuddy pamięta

Gdy zadanie zostanie zakończone, agent może zapisać to, czego się nauczył, z powrotem do CodeBuddy: podjęte decyzje, reguły odkryte w trakcie pracy, problemy z regresją oraz metody, które okazały się skuteczne. Ta wiedza przechowuje się lokalnie, rozdzielona pomiędzy bazę danych Postgres a pamięć w formacie Markdown, i jest włączana do pakietu kontekstowego przy następnym powiązanym zadaniu. Zamiast resetować wszystko do zera przy każdej sesji, system staje się coraz dokładniejszy.

5. PR-ów sprawdza się automatycznie

Workflow w GitHubie może automatycznie raportować informacje o każdym pull request, obejmując:

• Jak ryzykowna wydaje się ta zmiana
• Gdzie brakuje pokrycia testowego
• Czego zmiana dotyczy pod względem architektury
• Czy implementacja odeszła od pierwotnego planu
• Czy weryfikacja faktycznie się udała

Dlaczego to ma większe znaczenie, niż mogłoby się wydawać

Kuszące jest zaliczenie tego do kategorii „kolejnego narzędzia deweloperskiego opartego na Claude”. Taki sposób postrzegania pomija kilka istotnych aspektów:

Rozwiązuje on prawdziwy problem ograniczający rozwój. Modele stają się coraz bardziej zaawansowane w szybkim tempie. Jakość kontekstu, który im dostarczany jest, nie nadąża na poziomie narzędzi – większość rozwiązań nadal polega na czytaniu całych plików lub przeszukiwaniu z nadzieją na najlepszy wynik. CodeBuddy opiera się na założeniu, że kolejne istotne postępy w programowaniu agentowym wynikną z poprawy tego, co dostarczane jest modelowi, a nie z samego modelu.

Z biegiem czasu rozwija się samodzielnie. Okno kontekstowe domyślnie nie ma pamięci — każda sesja zaczyna się od nowa, chyba że otaczający system celowo zachowuje stan. Ponieważ CodeBuddy śledzi decyzje, zasady oraz regresje, dziesiąte zadanie w danym kodzie powinno przebiegać płynniej niż pierwsze, bez konieczności ponownego wyjaśniania tych samych rzeczy.

Otwarcie mówi o kompromisach, zamiast je ukrywać. Uczynienie Graphify opcjonalnym jest bezpośrednią reakcją na wcześniejszą próbę całkowitego usunięcia tego kompromisu, która nie powiodła się. Możesz wybrać: brak dodatkowej konfiguracji i przyzwoity, lekki indeks, albo naprawdę dokładny graf architektury, jeśli jesteś skłonny dodać jeden dodatkowy komponent.

Wszystko pozostaje na twoim komputerze. PostgreSQL, magazyn pamięci typu Markdown, wewnętrzny indeks oraz graf tworzony przez Graphify działają lokalnie. Dane uwierzytelniające znajdują się w prywatnym pliku konfiguracyjnym. Ulepszenie kontekstu agenta nie wymaga przesyłania twojej bazy kodu gdziekolwiek indziej.

Pasuje do narzędzi, których ludzie już używają. To nie jest nowy edytor ani agent, który trzeba byłoby się nauczyć — łączy się bezpośrednio z Claude i Codex, integrując się z miejscem, w którym już pracujesz, i po prostu sprawiając, że lepiej rozumieją dostępną bazę kodu.

Kierunek dalszych rozwojów

To nadal projekt w wczesnej fazie, poddawany ciągłym modyfikacjom, a system pamięci w szczególności wymaga największych ulepszeń — obecnie funkcjonuje bardziej jak uporządkowane notatki niż coś przypominającego pamięć z rankingiem dostępności informacji. Jeśli używasz agentów programistycznych opartych na AI w rzeczywistej bazie kodu i napotykasz problem „nie rozumie mojego projektu”, Twoje opinie są naprawdę mile widziane:

npm install -g @ayushkumar320/codebuddy

Jeśli spróbujesz tego lub rozwiązałeś ten problem w inny sposób w swoim środowisku, podzielenie się tym doświadczeniem byłoby cenne.

CodeBuddy to warstwa zarządzania kontekstem dla agentów programistycznych opartych na AI, takich jak Claude i Codex. Przygotowuje ona skoncentrowany, istotny kontekst zamiast wymuszać czytanie całej bazy kodu, a opcjonalnie może być integrowana z Graphify w celu uzyskania bardziej szczegółowej mapy architektury. Dostępna jest na npm pod nazwą @ayushkumar320/codebuddy.

Literatura pokrewna

• Zrozumienie agentów AI: cele, narzędzia, pamięć i pętla agenta — Przystępne dla początkujących wyjaśnienie, w jaki sposób agenci AI różnią się od chatbotów, obejmujące podstawowe komponenty, pętlę decyzyjną, poziomy autonomii oraz praktyczne zastosowania w rzeczywistym świecie.
• Porównanie agentów AI Frontier: Astra, Flash, Fable i Mythos — Analiza wyników najnowszych wersji modeli GPT, Gemini i Claude w rzeczywistych zadaniach agencyjnych, takich jak programowanie, przeglądanie internetu i korzystanie z narzędzi, a nie tylko w testach benchmarkowych.

Jak protokół model-contextu pozwala agentom SI odkrywać i korzystać z narzędzi — Jasne wyjaśnienie MCP: jak hosty, klienci i serwery umożliwiają aplikacjom SI odkrywanie narzędzi, wywoływanie ich za pomocą ustrukturyzowanych danych wejściowych oraz określanie ich ograniczeń.