SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor · Zaktualizowano 2026-10-23

Graft: jak stworzyć mapę bazy kodu dla agenta AI

Dowiedz się, jak Graft wykorzystuje tree-sitter do tworzenia trwałego indeksu repozytorium. Zredukuj liczbę zapytań agenta dzięki udostępnieniu struktury plików przez MCP.

Czym jest mapa bazy kodu dla agentów programistycznych

Mapa bazy kodu dla agentów programistycznych to trwały indeks repozytorium, z którego agent korzysta w celu wyszukiwania informacji, zamiast każdorazowego przeszukiwania plików za pomocą polecenia grep w każdej nowej sesji. Graft stanowi jedną z implementacji tej koncepcji. Narzędzie to analizuje kod za pomocą tree-sitter, tworzy folder powiązanych węzłów w formacie markdown wraz z grafem połączeń dla każdego symbolu i udostępnia narzędzia wyszukiwania poprzez MCP (model context protocol, standardowy interfejs używany przez agentów programistycznych do wywoływania zewnętrznych narzędzi).

Graft nie jest proxy ani bramą. Pomiędzy agentem a API modelu nie znajduje się żaden pośrednik. Mapa jest folderem na dysku, który agent odczytuje. To rozróżnienie determinuje charakter rozwiązywanego problemu: samodzielnie hostowana bramka tokenów mierzy i kieruje wysyłanymi już żądaniami, podczas gdy mapa zmienia liczbę żądań, które w ogóle muszą zostać wysłane.

Technika ta jest starsza niż samo narzędzie i przetrwa je. Należy najpierw poznać technikę, a dopiero potem jej mechanikę.

Dlaczego agenci programujący tracą tokeny kontekstu na ponowne odkrywanie struktury

Obserwacja agenta rozpoczynającego pracę nad repozytorium, które widział już pięćdziesiąt razy, pokazuje powtarzalny schemat. Agent listuje katalogi. Używa grep do wyszukania symbolu. Otwiera trzy pliki, aby ustalić, w którym zdefiniowano funkcję, a następnie czwarty, aby sprawdzić, kto ją wywołuje. Żadna z tych czynności nie jest właściwym zadaniem. To orientacja, za którą płaci się w tokenach wejściowych przy każdej sesji.

Przyczyna jest prosta. Model nie posiada pamięci między sesjami. Wszystko, czego agent dowiedział się o strukturze projektu, znajdowało się w oknie kontekstowym, które zostało odrzucone po zakończeniu sesji. Dlatego to samo odkrywanie struktury uruchamia się od zera, a użytkownik płaci za nie ponownie. Prompt caching oferuje zniżki tylko dla identycznego prefiksu promptu widzianego w ciągu ostatnich pięciu minut lub godziny za dodatkową opłatą, więc nie pozwala przenieść wczorajszej eksploracji do dzisiejszej sesji. W dużym repozytorium faza orientacji kosztuje więcej niż sama edycja: dziesięć wywołań narzędzi w celu zlokalizowania kodu i jedno w celu jego zmiany. Orientacja stanowi połowę rachunku, a edycja drugą, dlatego umiejętność ograniczania agenta do najmniejszej działającej zmiany warto łączyć z mapą, zamiast wybierać między nimi.

Mapa przerywa tę pętlę, przenosząc proces odkrywania z modelu na dysk. Parser przeszukuje repozytorium raz, rejestruje, gdzie zdefiniowano dany symbol i co go wywołuje, a następnie aktualizuje ten zapis wraz ze zmianami w kodzie. Agent zadaje jedno pytanie i otrzymuje odpowiedź wraz z nazwą pliku i numerem linii. Powtarzalna eksploracja staje się tanim wyszukiwaniem.

Użytkownicy korzystają już ze słabszej wersji tego rozwiązania. Plik AGENTS.md określający konwencje zapobiega ponownemu wyprowadzaniu konwencji przez agenta za każdym razem. Wygenerowana mapa zapobiega ponownemu wyprowadzaniu struktury. Różnica polega na tym, kto ją tworzy. Plik z instrukcjami pisze się ręcznie, więc pozostaje on niewielki. Mapę generuje parser, dzięki czemu może ona obejmować dziesięć tysięcy plików. Jeśli chodzi o to, na co faktycznie zużywany jest budżet wewnątrz sesji, sposób, w jaki Claude Code wykorzystuje okno kontekstowe wyjaśnia szczegóły rozliczeń.

Co faktycznie buduje Graft

Dwa artefakty, oba w folderze graft/ w katalogu głównym repozytorium.

Pierwszym jest graf węzłów zapisany w formie powiązanych plików markdown, jeden plik na węzeł. Każdy węzeł zawiera podsumowanie w języku naturalnym, „sedno” ważnych linii logiki wyodrębnionych ze źródła, dokładne pliki źródłowe z hashem zawartości, typowane linki typu wiki do innych węzłów (depends_on, part_of, uses, implements) oraz sekcję notatek, która przetrwa regenerację, co pozwala na zapisanie kontekstu, którego parser nie jest w stanie wywnioskować.

Drugim jest graft/.graph/wiring.json, graf strukturalny dla każdego symbolu, wyodrębniany przez tree-sitter: definicje, referencje oraz krawędzie wywołań między nimi.

Ten podział jest istotny, ponieważ tylko jedna połowa wymaga modelu. graft build to czysty tree-sitter, który nigdy nie wywołuje LLM (large language model), dzięki czemu jest deterministyczny i bezpłatny. graft build --deep dodaje pisemne podsumowania oraz sedno dla każdego symbolu, a są to wywołania modelu, za które ponosi się koszty.

Wsparcie dla języków jest podzielone na poziomy, a poziom określa, w jakim stopniu można ufać grafowi wywołań. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift oraz R posiadają obsługę rozdzielania międzyplikowego z uwzględnieniem zakresów (scope-aware). Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix oraz Lua otrzymują symbole wraz z ogólnymi krawędziami wywołań, co oznacza, że krawędź może być dopasowaniem nazwy, a nie rozwiązaną referencją. Krawędzie o jakości kompilatora są opcjonalne przy użyciu --lsp oraz serwera językowego, takiego jak rust-analyzer lub gopls.

Instalacja Graft i przypięcie wersji

Graft wymaga środowiska Node.js w wersji 20 lub nowszej i jest udostępniany na licencji MIT. Według stanu na 17 października 2026 r. aktualne wydanie to 0.23.0, opublikowane 15 października 2026 r., a pierwsza wersja, 0.1.0, pochodzi z lipca 2026 r. Należy traktować to oprogramowanie jako wczesne. Wydanie 0.22.0, opublikowane 14 października 2026 r., zmieniło nazwę projektu na Trail-code: ten sam kod jest teraz dystrybuowany również jako @trailhq/trail-code z poleceniem trail, podczas gdy @nanonets/graft zachowuje polecenie graft.

Niniejszy przewodnik przypina wersję 0.21.1, opublikowaną 29 września 2026 r. i będącą ostatnim wydaniem przed zmianą nazwy, ponieważ wersje 0.22 i 0.23 wprowadziły zmiany w poleceniach, na których opiera się ten przewodnik. Od wersji 0.22 polecenie graft check porównuje różnice w gałęzi z informacjami zespołu w repozytorium i kończy działanie z kodem 1 w przypadku konfliktu, wykrywanie dryfu przeniesiono do graft build --check, a narzędzia MCP noszą nazwę trail_* (serwer nadal odpowiada na stare nazwy graft_*). Dziennik zmian 0.23.0 podaje również, że w repozytorium skonfigurowanym z trail mapa przenosi się do .trail/cache/, a Claude Code nie otrzymuje już serwera MCP, podczas gdy plik README nadal opisuje graft/ i .mcp.json. Przed zmianą przypiętej wersji należy zapoznać się z dziennikiem zmian i uruchomić --dry-run.

npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graft

Polecenie npm ls -g powinno wyświetlić @nanonets/graft@0.21.1. Należy celowo przypiąć tę wersję. Użycie samego npm install -g @nanonets/graft powoduje rozwiązanie tagu latest w momencie uruchomienia, a w przypadku projektu wydającego kilka mniejszych wersji miesięcznie, prowadzi to do sytuacji, w której we wtorek użytkownik korzysta z innego narzędzia niż to, które współpracownik zainstalował w poniedziałek. Przypięta wersja zapewnia, że flagi CLI i format grafu pozostają niezmienne dla wszystkich, co pozwala na aktualizację w wybranym przez siebie momencie.

Następnie należy zintegrować narzędzie z posiadanym repozytorium:

cd /path/to/your/repo
graft init --dry-run
graft init

Polecenie graft init pyta, które z używanych agentów programistycznych mają zostać skonfigurowane, a następnie buduje graf. Należy najpierw uruchomić --dry-run i zapoznać się z listą plików, które zostaną zmodyfikowane, ponieważ niektóre z nich znajdują się poza repozytorium. Polecenie graft init jest idempotentne i nie nadpisuje istniejących konfiguracji, więc jego ponowne uruchomienie jest bezpieczne. Aby wycofać zmiany, graft uninstall usuwa wszystkie pliki i wpisy konfiguracyjne utworzone przez Graft; operacja ta działa w trybie testowym (dry run), dopóki nie zostanie użyta flaga -y.

Ten sam monit zawiera pole wyboru telemetrii. Od wersji 0.12.0 Graft domyślnie wysyła anonimowy sygnał o użyciu: zagregowane liczby i stałe etykiety, nigdy kod, ścieżki plików ani nazwa repozytorium. Zdarzenia są wysyłane maksymalnie raz dziennie, z jednym wyjątkiem: zdarzenie instalacji, które skrypt postinstall pakietu npm przekazuje natychmiast do procesu wysyłającego w tle. Należy odznaczyć to pole podczas graft init, uruchomić graft telemetry disable lub ustawić DO_NOT_TRACK=1, aby wyłączyć tę funkcję (wyłącza się ona również automatycznie w środowiskach CI), a graft telemetry debug wyświetla partię danych, która zostałaby wysłana, bez faktycznego wysyłania.

W wersji 0.21.1 integracja obejmuje Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent oraz Google Antigravity. Hermes Agent jest pełnoprawnym hostem graft init od wersji 0.13.0, a w przypiętej wersji graft init --agents hermes i graft init --agents antigravity wybierają te dwa elementy tak samo jak każdego innego hosta. Grok został dodany w wersji 0.13.0 i jest wybierany za pomocą graft init --agents grok. Claude Code otrzymuje najgłębszą integrację: wpis serwera MCP, pasek stanu pokazujący rozmiar i nieaktualność grafu, haki po edycji przebudowujące graf oraz plik umiejętności w .claude/. Pozostałe agenty otrzymują plik instrukcji lub reguł, który informuje agenta o istnieniu narzędzi (Hermes Agent i Antigravity odczytują sekcję AGENTS.md), a Grok otrzymuje również blok MCP we własnej konfiguracji. "Wsparcie" oznacza zatem, że Graft zapisuje konfigurację, więc agent, który ignoruje własny plik reguł, zignoruje również mapę. Jest to typowa przyczyna sytuacji, w której agenty ignorują zapisane dla nich instrukcje, co ma tutaj takie samo zastosowanie jak w każdym innym przypadku.

Co trafia do repozytorium, a co pozostaje poza git

Po graft init, spodziewaj się następujących elementów:

  • graft/: graf węzłów markdown oraz graft/.graph/wiring.json. Dodane automatycznie do .gitignore.
  • .mcp.json: rejestruje serwer MCP typu graft, aby Claude Code mógł go uruchomić.
  • .claude/settings.json: scalone w miejscu, dodające pasek stanu oraz hooki post-edit.
  • AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md, .grok/skills/graft/SKILL.md oraz .adal/skills/graft/SKILL.md: sekcje wewnątrz znaczników dołączone do plików odpowiadających wybranym agentom.
  • .grok/config.toml: blok [mcp_servers.graft] na poziomie repozytorium, zapisywany tylko w przypadku wyboru Grok.
  • ~/.codex/config.toml, ~/.codex/hooks.json oraz ~/.codex/hooks/graft/graft-hooks.cjs: ustawienia globalne dla maszyny, zapisywane tylko przy wyborze Codex, jeśli ~/.codex/ już istnieje. graft init --no-global pomija te pliki, a graft init --no-hooks pomija sam shim hooka.

Graf jest pamięcią podręczną, podobnie jak node_modules. Nie należy go commitować. Generuje się ponownie z kodu w kilka sekund, zmienia się przy niemal każdej edycji, a jego commitowanie zamienia poprawkę w jednej linii w diff obejmujący setki plików, którego nikt nie będzie w stanie przejrzeć. Zamiast tego commituj konfigurację połączeń, w tym AGENTS.md oraz .mcp.json. Współpracownik klonuje repozytorium, uruchamia graft build i otrzymuje własny, lokalny graf.

Sprawdź, czy reguła ignorowania została dodana przed pierwszym commitem:

grep -n graft .gitignore
git status --short

grep powinno wyświetlić linię zawierającą graft/, a git status --short nie powinno wyświetlić nic w sekcji graft/. Jeśli pliki z graft/ pojawiają się w tym wyniku, oznacza to, że wpis ignorowania jest nieobecny lub nadpisany w innym miejscu. Napraw to przed commitem, ponieważ git śledzi plik, gdy tylko zostanie dodany, a późniejsza edycja .gitignore nie spowoduje usunięcia go z indeksu.

Jeśli wolisz zarejestrować serwer MCP ręcznie lub przypiąć go do konkretnej wersji, którą zainstalowano, wpis jest krótki:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
    }
  }
}

Narzędzia wyszukiwania wywoływane przez agenta zamiast grep

Graft udostępnia sześć narzędzi przez MCP. graft_find_code zwraca ranking węzłów dla opisu zadania, wraz z plikiem i linią. graft_file_api zwraca wszystkie sygnatury w pliku bez treści funkcji. graft_trace_calls przeszukuje wywołujących lub wywoływanych na kilku poziomach głębokości. graft_find_all zwraca trafienia wyrażeń regularnych pogrupowane według symboli. graft_repo_map umożliwia wstępne zapoznanie się z nieznanym repozytorium. graft_check_freshness raportuje, czy graf jest nadal zgodny z kodem.

Każde z nich posiada odpowiednik CLI, co pozwala sprawdzić, co faktycznie otrzymuje agent:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask powinno wyświetlać ranking węzłów z odniesieniami file:line zamiast zawartości plików. To cały mechanizm: agent otrzymuje wskaźnik i otwiera jeden plik, zamiast czytać dziesięć w celu znalezienia właściwego. graft viz otwiera interaktywną przeglądarkę na localhost, jeśli użytkownik chce samodzielnie przejrzeć graf. Jeśli graft ask nie zwraca nic użytecznego dla pytania, na które można odpowiedzieć w trzydzieści sekund, nie należy zmieniać jego treści i pytać ponownie. Wyszukiwanie rankingowe może zawieść, a plik umiejętności projektu wskazuje, że słabe trafienia oznaczają konieczność przejścia na graft grep, graft skeleton lub graft callers. Jeśli te również nie przyniosą rezultatów, należy sprawdzić występowanie dryfu (graft check . dla przypiętej wersji 0.21.1, graft build --check od wersji 0.22) i potwierdzić, w której warstwie znajduje się dany język, ponieważ nieaktualny graf lub zbyt szerokie krawędzie warstw spowodują błąd działania agenta.

Jeden koszt jest łatwy do przeoczenia. Sześć definicji narzędzi jest wstrzykiwanych do promptu systemowego każdego żądania przez całą sesję. Koszt ten jest ponoszony niezależnie od tego, czy agent korzysta z mapy, czy nie. W przypadku repozytorium wystarczająco małego, by zmieścić się w kontekście, stała opłata może być wyższa niż oszczędność wynikająca z eksploracji.

Co dzieje się z grafem po zmianie kodu

Odświeżenie strukturalne jest tanie i automatyczne. Graft odczytuje drzewo robocze, a nie git, więc edycja niezatwierdzona oraz edycja w poczekalni (staged) są dla niego równie widoczne. Każde zapytanie najpierw sprawdza stan drzewa roboczego i ponownie analizuje tylko te pliki, które uległy zmianie. Dokumentacja wersji 0.21.1 określa czas tej weryfikacji na około 3 ms, gdy nic się nie zmieniło; aktualny README podaje wartość kilkudziesięciu milisekund, około 50 ms w przypadku własnego repozytorium projektu. Odbudowa na koniec cyklu pracy dotyczy tylko plików, w których przesunięto kod. Ustaw GRAFT_NO_REFRESH=1 lub przekaż --no-refresh, aby uzyskać odpowiedź z grafu na dysku bez ponownej analizy. Przekaż --no-reuse, aby wymusić pełną ponowną analizę od zera, co jest zalecane po aktualizacji samego Graft.

Część wygenerowana przez model zachowuje się inaczej i to ona może po cichu przestać działać poprawnie. Podsumowania i kluczowe punkty (cruxes) są buforowane. Każdy węzeł rejestruje skrót zawartości swoich źródeł, więc gdy plik źródłowy ulega zmianie, węzeł jest oznaczany jako nieaktualny, zamiast być prezentowanym jako bieżący. Ta flaga pomaga tylko wtedy, gdy coś na nią zareaguje. Odśwież za pomocą graft build --deep, co ponownie zużywa tokeny modelu.

Uczyń nieaktualność widoczną:

graft check .
echo $?

W przypiętej wersji 0.21.1 kod wyjścia 0 oznacza, że graf zgadza się z kodem, a kod wyjścia 1 oznacza rozbieżność. Od wersji 0.22, graft check zwraca 1 w przypadku konfliktu z procesem uczenia zespołowego, a bramką rozbieżności jest graft build --check, więc zmień polecenie po zmianie przypiętej wersji. Uruchamiaj je z poziomu hooka pre-push, aby mapa sprzed sześciu miesięcy nie udzielała pewnych odpowiedzi na temat kodu, który został przepisany w marcu. README wersji 0.21.1 opisuje graft check jako lokalny sygnał świeżości, a aktualny README wymienia build --check dla CI. W obu przypadkach graft/ jest ignorowane przez git, więc świeży checkout w CI startuje bez grafu, chyba że zadanie go zbuduje.

Dokładna analiza opublikowanych wyników testów wydajnościowych

Plik README w wersji 0.21.1 zawierał nagłówek: „do 4x taniej i 3x szybciej, przy zachowaniu lub poprawie poprawności”. Obecny plik README pomija to stwierdzenie i przedstawia bardziej konserwatywne dane: „W 162 uruchomieniach tego samego agenta na tych samych zadaniach: o 32% niższy koszt, o 42% mniej niebuforowanych tokenów wejściowych, o 60% krótszy czas oraz ten sam odsetek poprawnych odpowiedzi”. Dane te pochodzą z własnych testów projektu, opublikowanych w pliku README. Poniżej przedstawiono pełne wyniki dwóch raportowanych serii testów.

WykresGraft's own published benchmark results, versus a no-map baseline, as of October 2026
Dane, na których opiera się ten wykres
[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

Kontrolowany test obejmuje 162 uruchomień w dwóch repozytoriach, z których jednym jest sam Graft, przy trzech próbach na zadanie. Raport wskazuje na 42% mniejszą liczbę niebuforowanych tokenów wejściowych oraz o 46% mniej wywołań narzędzi. Test SWE-bench Verified obejmuje 50 instancji z tym samym modelem dla obu wariantów i wykazuje mniejsze oszczędności: 23% tokenów oraz 25% wywołań narzędzi. Trzecia seria testów, obejmująca 15 zadań dla PocketBase (dziesięć pytań programistycznych oraz pięć odtworzonych scalonych pull requestów), kosztowała łącznie 11.02 USD w porównaniu do 13.91 USD dla linii bazowej.

Wszystkie te dane należy traktować jako testy dostawcy. Dwa czynniki ograniczają ich wartość informacyjną. Kontrolowany test obejmuje repozytorium samego Graft, czyli bazę kodu, pod którą autorzy optymalizowali narzędzie. SWE-bench Verified to publiczny zbiór danych zawierający zgłoszenia ze znanych projektów open-source w języku Python, a publiczne zbiory danych są naturalnym celem optymalizacji narzędzi, niezależnie od intencji twórców. Żaden z tych wyników nie odnosi się bezpośrednio do prywatnego monorepo, które posiada własną specyfikę nazewnictwa oraz martwy kod.

Kwestia poprawności wymaga ponownej analizy. W kontrolowanym teście wynik nie uległ zmianie: 93% z mapą w porównaniu do 93% bez niej. Wzrost z 54% do 66% występuje wyłącznie w teście SWE-bench Verified. Narzędzie, które redukuje koszty tokenów przy zachowaniu jakości, jest korzystnym rozwiązaniem. Należy jednak unikać łączenia wyniku poprawności z SWE-bench z wynikiem oszczędności tokenów z kontrolowanego testu w ramach jednego twierdzenia.

Zmierz własną deltę tokenów, zanim w nią uwierzysz

Jedyną istotną liczbą jest ta pochodząca z Twojego repozytorium. Ta metoda zajmuje jedno popołudnie.

Wybierz zadanie, które możesz powtórzyć dokładnie w ten sam sposób. Pytanie jest lepsze niż edycja, ponieważ edycja zmienia repozytorium, a drugie uruchomienie nie jest już tym samym eksperymentem. „Który moduł wymusza limit szybkości (rate limit) na ścieżce logowania” to właściwy format.

Włącz telemetrię i skieruj ją na własny terminal:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

Eksporter konsolowy drukuje rekordy metryk w miarę ich zbierania. Interesującym Cię rekordem jest claude_code.token.usage, który posiada atrybut type o wartości input, output, cacheRead lub cacheCreation. Orientacja pojawia się w input oraz cacheRead, ponieważ to tam trafia zawartość plików. Zsumuj te dwie wartości.

Uruchom zadanie trzy razy, za każdym razem w nowej sesji, z podpiętą mapą. Następnie usuń wpis graft z .mcp.json i uruchom zadanie kolejne trzy razy. Porównaj mediany zamiast pojedynczych przebiegów, ponieważ czas pracy agenta wykazuje duże wahania, a jeden niefortunny przebieg może wskazać wynik odwrotny do prawdy. Zapisz również liczbę wywołań narzędzi (tool-call count): wywołania narzędzi są mechanizmem, a tokeny efektem, więc oszczędność tokenów bez spadku liczby wywołań narzędzi oznacza, że zmieniło się coś innego.

Następnie odejmij koszty, których benchmark nie wykazuje. graft build --deep zużywa tokeny modelu przy każdym pełnym odświeżeniu. Sześć schematów narzędzi jest przesyłanych w każdym żądaniu. Jeśli Twoje agenty działają na wynajmowanym serwerze, ustawienie twardego limitu wydatków na agenta zmienia to z niespodzianki w budżet, a co faktycznie raportuje telemetria agenta kodującego opisuje, co opuszcza maszynę po włączeniu eksportera.

Kiedy mapa bazy kodu przestaje być przydatna?

  • Repozytorium mieści się już w kontekście. Pojedyncza mała usługa nie wymaga mapy, a za każdym razem płacisz za użycie sześciu schematów narzędzi. Jeśli agent znajduje dowolny plik w jednym lub dwóch wywołaniach narzędzi, zrezygnuj z niej.
  • Język znajduje się w szerokiej kategorii wsparcia. Ogólne krawędzie wywołań oznaczają, że graft callers może pominąć wywołującego lub wygenerować go na podstawie kolizji nazw. Potwierdź wynik za pomocą graft grep, zanim zaufasz zasięgowi zmian.
  • Graf stał się nieaktualny i nikt tego nie zauważył. W wersji 0.21.1 graft check kończy działanie kodem 1 w przypadku rozbieżności (od wersji 0.22 robi to graft build --check), co jest użyteczne tylko wtedy, gdy ktoś to uruchamia. To kwestia pre-push hooka, a nie nawyku.
  • Monorepo wymaga zakresowania. Pojedyncze repozytorium git nie jest podzielone, ale graft build wykrywa podprojekty na podstawie pnpm-workspace.yaml, obszarów roboczych package.json lub plików go.mod, pyproject.toml bądź Cargo.toml dla każdego pakietu i używa ich jako zakresów rankingu, a graft ask "..." --in services/billing/ zawęża zapytanie do jednego podprojektu. Ten sam instynkt, który prowadzi do zagnieżdżonych plików AGENTS.md dla każdego pakietu, ma zastosowanie do mapy.
  • Agent ignoruje powiązania. Obserwuj wywołania narzędzi w rzeczywistej sesji, zanim stwierdzisz, że mapa jest używana. Agent, który nadal uruchamia grep, sygnalizuje, że nigdy nie odczytał pliku reguł.

FAQ

Czy należy dodawać folder graft/ do repozytorium git?

Nie. graft build automatycznie dodaje graft/ do pliku .gitignore, ponieważ graf jest pamięcią podręczną, którą można wygenerować ponownie, podobnie jak node_modules. Zmienia się on przy niemal każdej edycji, więc dodanie go do repozytorium ukryłoby rzeczywiste zmiany (diffy) pod setkami wygenerowanych plików. Należy dodać jedynie konfigurację, która informuje agentów o istnieniu mapy, w tym AGENTS.md oraz .mcp.json, a każdemu członkowi zespołu pozwolić na lokalne uruchomienie graft build. Przed pierwszym commitem należy zweryfikować pliki za pomocą grep -n graft .gitignore i git status --short, ponieważ git śledzi plik po jego dodaniu, a późniejsza edycja .gitignore nie powoduje usunięcia go z indeksu.

Czy korzystanie z Graft wiąże się z kosztami?

Strukturalna część narzędzia jest bezpłatna. graft build, graft ask, graft check oraz sześć narzędzi pobierania MCP to operacje tree-sitter, które nie wywołują modelu. graft build --deep stanowi płatną część: tworzy podsumowania w języku naturalnym oraz kluczowe informacje dla poszczególnych symboli za pomocą LLM, skonfigurowanego przy użyciu GRAFT_PROVIDER, GRAFT_API_KEY i GRAFT_MODEL, oraz GRAFT_BASE_URL dla dowolnego punktu końcowego zgodnego z OpenAI. Można używać Graft wyłącznie w trybie strukturalnym, nie zużywając ani jednego tokena na sam graf.

Ile tokenów zaoszczędzi mapa bazy kodu w moim repozytorium?

Nikt nie jest w stanie tego określić bez pomiarów. Projekt wykazuje 42% mniej niebuforowanych tokenów wejściowych w ramach własnego testu 162 oraz 23% mniej tokenów w teście SWE-bench Verified, w obu przypadkach w porównaniu do bazy bez mapy. Są to benchmarki dostawców, z których jeden przeprowadzono częściowo na własnym repozytorium Graft, i żaden z nich nie opisuje prywatnego kodu. Należy uruchomić jedno powtarzalne zapytanie trzy razy z mapą i trzy razy bez niej, przy ustawionych flagach CLAUDE_CODE_ENABLE_TELEMETRY=1 i OTEL_METRICS_EXPORTER=console, a następnie porównać medianę claude_code.token.usage dla typów input oraz cacheRead.

Co dzieje się z grafem podczas refaktoryzacji?

Struktura analizuje się ponownie. Graft sprawdza stan drzewa roboczego i parsuje tylko te pliki, które uległy zmianie, więc zmiana nazwy jest wykrywana przy następnym zapytaniu. Gdy nic się nie zmieniło, sprawdzenie to zajmuje około 3 ms w wersji 0.21.1 i kilkadziesiąt milisekund w bieżącym wydaniu; narzędzie widzi niezatwierdzone zmiany, ponieważ odczytuje pliki, a nie historię git. Podsumowania napisane przez model stają się nieaktualne: każdy węzeł przechowuje skrót zawartości swoich źródeł, a zmiana źródła oznacza węzeł jako nieaktualny zamiast go nadpisywać. Należy sprawdzić rozbieżności (graft check . w wersji 0.21.1, graft build --check od wersji 0.22), a następnie uruchomić graft build --deep, aby odświeżyć część tekstową.

Które agenty programistyczne mogą obecnie korzystać z Graft?

W przypiętej wersji 0.21.1, graft init obsługuje Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent oraz Google Antigravity, łącznie jedenaście hostów. Dziennik zmian wymienia Hermes Agent jako hosta pierwszej klasy od wersji 0.13.0, a hermes oraz antigravity są standardowymi identyfikatorami --agents w przypiętym wydaniu. Claude Code otrzymuje najwięcej: wpis serwera MCP w .mcp.json, pasek stanu, hooki post-edit oraz plik umiejętności w .claude/. Codex otrzymuje sekcję AGENTS.md oraz wpisy systemowe w ~/.codex/, które graft init --no-global pomija. Grok otrzymuje plik umiejętności oraz blok MCP w .grok/config.toml. Hermes Agent i Antigravity odczytują sekcję AGENTS.md, a pozostałe otrzymują plik reguł lub sterowania. Każdy inny klient MCP może korzystać z serwera bezpośrednio, rejestrując polecenie npx -y @nanonets/graft@0.21.1 mcp.

Czy ten artykuł był przydatny?