Deweloper wdrożył trójwarstwową mapę bazy kodu, która pozwala agentom AI do programowania zachować poczucie kontekstu między sesjami.

Dlaczego agenci AI potrzebują mapy

Asystenci programowania oparci na czacie budują model mentalny repozytorium tylko tak długo, jak otwarte jest okno promptu. Gdy okno kontekstowe zostaje zamknięte, model wyparowuje, zmuszając agenta do ponownego odkrywania symboli, importów i relacji między plikami od zera. To ciągłe powracanie do tych samych informacji marnuje cykle obliczeniowe i sprawia, że agent staje się mniej pomocny, gdy programista przełącza się między plikami lub wraca do projektu po przerwie.

Trzy warstwy tworzące mapę

  • Warstwa strukturalna – katalog symboli, wywołań funkcji i instrukcji importu. Odpowiada na statyczne pytanie: „co co wywołuje”.
  • Warstwa czasowa – sygnały pochodzące z Gita, takie jak wskaźniki rotacji plików (file churn rates) i historia własności. Pokazuje, które części kodu zmieniają się najczęściej i kto ma tendencję do ich modyfikowania.
  • Warstwa behawioralna – wzorce rzeczywistego użytkowania wyodrębnione z historii edycji i nawigacji samego agenta. Ujawnia, które pliki są faktycznie otwierane razem podczas sesji programowania, wskazując na „prawdziwych sąsiadów”, których nie wykryje analiza statyczna.

Warstwa behawioralna ma największe znaczenie, ponieważ odzwierciedla to, jak programiści (i agenci) naprawdę pracują, a nie tylko to, jak połączony jest kod.

Dwa sposoby przekazywania mapy agentowi

  1. Ambient Path – zwięzłe podsumowanie wstrzykiwane do każdej interakcji. Daje agentowi natychmiastowy wgląd typu „jesteś w module X, te symbole znajdują się w pobliżu”, bez konieczności wykonywania dodatkowych wywołań.
  2. Deep Path – narzędzia do zapytań na żądanie, które agent może wywołać, gdy potrzebuje bogatszych szczegółów, takich jak lista plików często zmienianych razem lub oś czasu ostatnich zmian własności.

Rozdzielenie informacji typu ambient od informacji typu deep pozwala zachować lekkość rutynowych promptów, oferując jednocześnie głębię w razie potrzeby.

Zasady projektowe zapewniające lekkość systemu

  • Pomiń ciężkie serwery językowe (language servers). Mapa opiera się na powierzchownym parsowaniu (shallow parsing), a nie na pełnej inferencji typów. Celem nie jest przewyższenie dojrzałych analizatorów statycznych, lecz uzupełnienie ich o wgląd behawioralny.
  • Ogranicz graf do pojedynczego projektu. System nie tworzy globalnego grafu zależności obejmującego wiele repozytoriów. To ograniczenie zmniejsza zużycie pamięci i przyspiesza aktualizacje.
  • Wykorzystuj istniejący magazyn pamięci. Logi zmian plików pochodzą z własnej pamięci agenta o wywołaniach narzędzi, co pozwala uniknąć duplikowania danych i zapewnia spójność źródła danych.

Budowanie mapy w praktyce

  1. Zbierz dane strukturalne poprzez szybkie przejrzenie plików źródłowych i wyodrębnienie symboli oraz linii importu.
  2. Pobierz metryki czasowe z historii Gita w repozytorium, odnotowując, które pliki mają najwięcej commitów i kto był ich autorem.
  3. Pozyskaj sygnały behawioralne, logując akcje agenta (otwieranie plików, edycję i nawigację) podczas rzeczywistych sesji programowania. Logi te stają się podstawą macierzy współwystępowania (co-occurrence matrix), która definiuje behawioralnych sąsiadów.
  4. Wypełnij Ambient Path krótką, uporządkowaną listą najbardziej istotnych symboli i plików dla bieżącego zadania.
  5. Udostępnij Deep Path jako zestaw lekkich funkcji zapytań (np. „wymień pliki edytowane razem w ostatnich sesjach”).

Szybkie hooki rejestrują każdą edycję w momencie jej wystąpienia, natomiast wolniejsze procesy działające w tle przeliczają statystyki rotacji. Razem sprawiają, że mapa jest aktualna, nie spowalniając przy tym pracy programisty.

Wyciągnięte wnioski

  • Rozdziel informacje ambient od tych na żądanie. Utrzymywanie stałego podsumowania w minimalnej formie zapobiega nadmiernemu zużyciu tokenów, podczas gdy bogatsze zapytania pozostają opcjonalne.
  • Nadawaj priorytet kontekstowi w zależności od zadania. Porządkowanie symboli w Ambient Path zgodnie z bieżącym obszarem edycji daje bardziej użyteczne sugestie.
  • Odświeżaj agresywnie, ale inteligentnie. Szybkie hooki rejestrują zmiany o wysokiej częstotliwości, natomiast okresowe skanowanie obsługuje rzadsze zmiany rotacji i własności.
  • Powierzchowne parsowanie wygrywa szybkością. Głęboka analiza typów dodaje opóźnień, nie dostarczając wglądu behawioralnego, który stanowi o przewadze mapy.

Podsumowanie: Dzięki nałożeniu struktury statycznej, historii z Gita i rzeczywistego użytkowania na kompaktowy, dwupoziomowy model dostępu, programiści mogą zapewnić agentom AI do programowania trwałą mapę bazy kodu. Utrzymywanie stałego podsumowania w minimalnej formie zapobiega nadmiernemu zużyciu tokenów.