Wyszukiwanie i indeksowanie kodu dla agentów AI: tekst, semantyka i symbole

Agenci AI do programowania znajdują kod na trzy sposoby: wyszukiwaniem tekstowym w stylu ripgrepa, wyszukiwaniem semantycznym po indeksie embeddingów i wyszukiwaniem symboli przez serwer językowy. Claude Code i Codex opierają się na tekście, dopóki nie doda się serwera językowego lub MCP; agent Cursora ma też wyszukiwanie semantyczne. Dobór wyszukiwania do pytania i odcięcie szumu decydują, ile kosztuje odkrywanie kontekstu.

Pytasz agenta, gdzie obsługiwane jest anulowanie subskrypcji. Agent grepuje „cancel”, otwiera kilkanaście plików, w tym wygenerowanego klienta i przestarzały handler v1, po czym pewnym tonem opisuje martwą ścieżkę kodu. Połowa okna kontekstu znika, zanim powstanie choć jedna linia. Ta strona jest dla programistów, którzy codziennie pracują z agentami, i dla tech leadów, którzy konfigurują repozytorium tak, żeby każdy agent w zespole dobrze je przeszukiwał.

Co zyskasz, konfigurując wyszukiwanie kodu

• Mapę tego, jak Claude Code, Codex i Cursor przeszukują repozytorium, i które warstwy możesz dołożyć.
• Tabelę decyzyjną, która dla danego pytania wybiera wyszukiwanie tekstowe, semantyczne albo po symbolach.
• Ustawienia plików ignorowania i uprawnień, które trzymają wygenerowany kod, fixtures i sekrety z dala od wyników.
• Cztery prompty do skopiowania: zawężone szukanie, śledzenie funkcji, audyt użyć i delegowana eksploracja.
• Kontrolę z dwóch poleceń, która dowodzi, że znaleziska agenta są prawdziwe i kompletne, bez czytania każdego pliku.

Jak Claude Code, Codex i Cursor znajdują kod?

Wszyscy trzej agenci zaczynają od wyszukiwania tekstowego. Różnią się tym, co jeszcze jest wbudowane, a co musisz dodać sam.

Warstwa wyszukiwania	Claude Code	Codex	Cursor
Wyszukiwanie tekstowe (grep, globbing plików)	Wbudowane	Wbudowane, przez powłokę	Wbudowane
Wyszukiwanie semantyczne po indeksie embeddingów	Dodaj serwer MCP	Dodaj serwer MCP	Wbudowane
Wyszukiwanie symboli (definicje, referencje, hierarchia wywołań)	Narzędzie LSP po instalacji wtyczki code intelligence	Dodaj serwer MCP	Niepotwierdzone; dodaj serwer MCP
Delegowana eksploracja w osobnym kontekście	Wbudowany subagent Explore	Subagenci	Subagenci

Claude Code

Wyszukiwanie tekstowe. Na macOS, Linuksie i WSL Claude Code nie włącza narzędzi Grep i Glob do domyślnego zestawu. Claude szuka poleceniami find i grep przez narzędzie Bash, a pod spodem działają wbudowane wersje bfs i ugrep. Na Windowsie Grep i Glob są w zestawie domyślnym. Na pozostałych systemach podanie któregokolwiek z nich w --allowedTools przy starcie sesji przywraca oba; --tools daje dokładnie te, które wymienisz (sprawdzone w dokumentacji narzędzi i na Claude Code 2.1.283, kanał latest, 2026-09-26).

Gdy są włączone, dwa zachowania tych narzędzi mają znaczenie dla szumu. Grep jest zbudowany na ripgrepie i pomija pliki z .gitignore. Glob domyślnie nie respektuje .gitignore i zwraca najwyżej 100 plików; ustaw CLAUDE_CODE_GLOB_NO_IGNORE=false przed uruchomieniem, żeby pomijał pliki ignorowane.

Wyszukiwanie symboli. Narzędzie LSP skacze do definicji, znajduje referencje, listuje symbole, znajduje implementacje i śledzi hierarchię wywołań. Pozostaje nieaktywne, dopóki nie zainstalujesz wtyczki code intelligence dla swojego języka i nie umieścisz binarki serwera językowego w PATH. Po każdej edycji zgłasza też błędy typów. W sesjach w chmurze serwery językowe z wtyczek się nie uruchamiają, więc narzędzie jest tam nieaktywne.

Delegowana eksploracja. Claude deleguje pracę do wbudowanego subagenta Explore, gdy musi zrozumieć kod bez zmieniania go, więc wyniki wyszukiwania nie trafiają do głównej rozmowy. Explore pomija twoje pliki CLAUDE.md, czyli mapa nawigacji trzymana wyłącznie w CLAUDE.md do niego nie dociera.

Codex

Wyszukiwanie tekstowe. Codex uruchamia polecenia powłoki w swoim sandboksie. Dołączone do niego instrukcje każą modelowi preferować rg do tekstu i rg --files do nazw plików, a gdy rg brakuje, sięgać po inne narzędzia (codex-rs/core/gpt_5_codex_prompt.md w tagu rust-v0.157.1). ripgrep pomija pliki pasujące do .gitignore, .ignore i .rgignore.

Brak wbudowanego indeksu. Codex 0.157.1 nie wymienia w codex features list żadnej funkcji indeksu semantycznego ani serwera językowego (sprawdzone na 0.157.1). Wyszukiwanie po symbolach i semantyczne dają serwery MCP dodane przez codex mcp add.

Zawężanie. Uruchamiaj Codeksa we właściwym katalogu przez -C DIR, a drugie repozytorium dołączaj przez --add-dir DIR, zamiast wklejać kod do promptu. W interfejsie terminalowym /mention dołącza plik bezpośrednio, a /status pokazuje zużycie tokenów w sesji.

Cursor

Trzy narzędzia wyszukiwania. Środowisko uruchomieniowe agenta, które Cursor dostarcza w pakiecie @cursor/sdk 1.0.32, zawiera narzędzie semantycznego przeszukiwania kodu, narzędzie grep oparte na ripgrepie i wyszukiwanie plików po wzorcu glob. Agent wybiera między nimi przy każdym zapytaniu. To samo środowisko definiuje też typy narzędzi przejścia do definicji i wyszukiwania symboli; nie dało się tu sprawdzić, czy agent z nich korzysta.

Wykluczenia. To samo środowisko odmawia agentowi odczytu ścieżek z .cursorignore i przekazuje tę listę do przeglądania plików przez ripgrepa. Plik używa składni .gitignore.

Czego tu nie podajemy. Podczas weryfikacji strona cursor.com była niedostępna, więc czasy indeksowania, układ ekranu ustawień ani to, czy ścieżka z .cursorignore wypada też z indeksu semantycznego, nie są tu podane jako fakty. Potwierdź je w dokumentacji Cursora, zanim na nich oprzesz konfigurację. Wykluczenia dla całego zespołu opisuje strona jak zabezpieczyć Cursora w zespole.

Które wyszukiwanie pasuje do pytania?

Najwięcej kontekstu marnuje się, gdy wyszukiwaniu tekstowemu zadajesz pytanie pojęciowe, a semantycznemu strukturalne. Wybieraj według pytania, nie według narzędzia.

Pytanie, które zadajesz	Najlepsze wyszukiwanie	Dlaczego	Wskazówka w prompcie
„Gdzie jest zdefiniowane applyDiscount?”	Tekstowe	Znasz dokładny identyfikator, więc wystarczy jedno rg -w	Podaj identyfikator
„Gdzie ponawiamy nieudane płatności?”	Semantyczne albo tekstowe po prawdopodobnych identyfikatorach	Pojęcie nie ma stałej nazwy	Poproś najpierw o kandydatów na identyfikatory
„Kto wywołuje applyDiscount i przez które trasy?”	Po symbolach	Tekst gubi importy z aliasem i łapie komentarze	„Użyj serwera językowego”
„Jak działa checkout od początku do końca?”	Delegowana eksploracja	Szeroki odczyt, który nie powinien trafić do głównego kontekstu	„Użyj subagenta” lub Explore
„Zmień nazwę applyDiscount wszędzie”	Po symbolach, potem type checker	Referencje muszą być kompletne, a kompilator to udowadnia	„Znajdź referencje, potem uruchom typecheck”

W małym repozytorium wyszukiwanie tekstowe wystarcza, a dodanie indeksu kosztuje więcej konfiguracji, niż oszczędza. Wyszukiwanie po symbolach lub semantyczne opłaca się tym bardziej, im większy kod, im bardziej dynamiczne nazewnictwo i im więcej niemal identycznych implementacji.

Przygotuj repozytorium, żeby każdy agent dobrze je przeszukiwał

1. Wyklucz szum ze wszystkich narzędzi. Wygenerowany kod, zależności w repozytorium, fixtures, artefakty buildu i lockfile’e dominują w wynikach wyszukiwania tekstowego. Wyklucz je raz, w plikach, które czyta każde narzędzie:

   Claude Code

   Na macOS, Linuksie i WSL Claude domyślnie szuka poleceniami grep i find przez Bash. Czy ten wbudowany grep respektuje .gitignore, dokumentacja nie mówi (sprawdzone na 2.1.283), więc nie licz na to. Albo uruchom sesję przez claude --allowedTools Grep, co przywraca oparte na ripgrepie narzędzia Grep i Glob, albo oprzyj się na sekcji „Searching this repository” w CLAUDE.md, która każe Claude’owi używać rg, jeśli jest zainstalowany (Claude Code go nie gwarantuje), a w przeciwnym razie przekazywać do grep flagi wykluczeń, takie jak --exclude-dir:

   ## Searching this repository
   - src/generated/ and src/__generated__/ are generated. Search src/api/ for the source schema instead.
   - fixtures/ holds large test data. Do not read it unless a test names a fixture file.
   - Search with `rg` if it is installed (it skips gitignored files); otherwise pass --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=src/generated to grep.

   CLAUDE_CODE_GLOB_NO_IGNORE=false ma znaczenie dopiero wtedy, gdy Glob jest włączony: na Windowsie albo po --tools lub --allowedTools. Wtedy ustaw tę zmienną w profilu powłoki, bo Glob domyślnie ignoruje .gitignore, a Grep go respektuje.

   Codex

   Zacommituj plik .ignore w katalogu głównym repozytorium. ripgrep go czyta, więc śledzony szum znika z wyszukiwań rg Codeksa bez zmiany tego, co śledzi Git:

   # .ignore: skipped by ripgrep, still tracked by Git
   src/generated/
   src/__generated__/
   fixtures/
   *.snap

   Tę samą sekcję „Searching this repository” dodaj do AGENTS.md, żeby model wiedział, gdzie leży prawdziwy kod źródłowy.

   Cursor

   Zacommituj .cursorignore z tymi samymi wpisami. Odczyty agenta i przeglądanie plików przez jego grep pomijają pasujące ścieżki:

   # .cursorignore (gitignore syntax)
   src/generated/
   src/__generated__/
   fixtures/

2. Napisz krótką mapę nawigacji. Pięć do dziesięciu linii w CLAUDE.md lub AGENTS.md, które mówią, gdzie leży każda warstwa (trasy, serwisy, dostęp do danych, testy), oszczędza agentowi przeczesywania katalogów przy każdym zadaniu. Ogranicz się do ścieżek, bez prozy. Co jeszcze tam należy, opisuje strona dokumentacja jako kontekst, a jak nazywać pliki, żeby wyszukiwanie je znajdowało, strona organizacja plików pod agentów.

3. Dodaj wyszukiwanie po symbolach, gdy kod jest duży lub typowany. W Claude Code zainstaluj wtyczkę code intelligence dla swojego języka i serwer językowy, którego oczekuje:

   # terminal
   npm install -g typescript-language-server typescript
   claude plugin install typescript-lsp@claude-plugins-official

   Dla Codeksa albo gdy chcesz jednego serwera dla kilku narzędzi, Serena udostępnia przez MCP wyszukiwanie na poziomie symboli oparte na serwerach językowych. Instaluj ją z repozytorium autorów, nie z marketplace’u, bo jej README ostrzega, że polecenia z marketplace’ów są przestarzałe:

   # terminal
   uv tool install -p 3.13 serena-agent
   claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
   serena setup codex

   Przewodnik po serwerach MCP do analizy kodu porównuje Serenę, codebase-memory-mcp, Claude Context (wyszukiwanie semantyczne wymagające bazy wektorowej i dostawcy embeddingów) oraz Repomix.

4. Zmierz kontekst przed zmianą i po niej. Uruchom ten sam prompt w świeżej sesji i porównaj /context w Claude Code albo /status w Codeksie. Jeśli liczby prawie się nie ruszyły, zmiana nie była warta utrzymania.

Prompty, dzięki którym szukanie kodu jest tanie i sprawdzalne

Każdy prompt prosi o odwołania w formie path:line:symbol. To one sprawiają, że odpowiedź da się sprawdzić w następnej sekcji.

Prompt do skopiowania: zawężone szukanie kodu

Find where subscription cancellation is handled in this repository.

Rules:
- Start by listing 3-5 identifiers you will search for (function, route and
  event names), then search for those, not for the English word "cancel".
- Skip generated code, fixtures and anything under a v1/ or legacy/ path
  unless nothing else matches.
- Read only the functions that match, not whole files. Stop after 6 files.

Report:
1. Each relevant location as path:line:symbol (for example
   src/billing/cancel.ts:42:cancelSubscription), one per line with nothing
   else on it.
2. A three-sentence summary of the flow.
3. What you searched for that returned nothing, so I can narrow it.

Prompt do skopiowania: prześledź funkcję od trasy do bazy danych

Trace what happens when a user submits POST /api/checkout, from the route
handler to the database write.

For each hop (route, middleware, service, data access, query), give one
line in the exact form path:line:symbol (for example
src/api/checkout.ts:18:handleCheckout) with nothing else on it, and put
one sentence on what it does on the next line.
Use the language server for definitions and references where it is
available; otherwise use rg with -w on exact identifiers.
Read only the functions on the path. Finish with the list of tables written.

Prompt do skopiowania: audyt wszystkich użyć wzorca

List every place that calls an external HTTP API and handles its errors.

1. Search with rg for the HTTP client calls used here (fetch, axios,
   got, httpx: check package manifests first to see which apply).
2. For each call site, output one line:
   path:line:symbol | client | how errors are handled (throw, retry, swallow, log)
3. Group the lines by handling style and flag every "swallow".
Output the raw list first, then the grouping. Do not edit any file.

Prompt do skopiowania: deleguj szeroką eksplorację

Use a subagent to map how authentication works in this repository:
entry points, session storage, token refresh, and where permissions
are checked. The subagent should return only a summary of at most
20 lines with path:line:symbol citations, not file contents.
Then tell me which three files I should read myself before changing
the session lifetime.

W Claude Code ostatni prompt zwykle trafia do Explore. Ponieważ Explore pomija CLAUDE.md, ścieżki, których ma unikać, wpisz bezpośrednio do promptu. W Codeksie i Cursorze to samo sformułowanie uruchamia subagenta.

Jak sprawdzić znaleziska agenta bez czytania każdego pliku?

Pewna siebie odpowiedź z wyszukiwania może wskazywać linię, która nie istnieje, albo pomijać połowę wywołań. Dwie deterministyczne kontrole łapią oba przypadki i żadna nie wymaga czytania kodu.

Sprawdź, czy każde odwołanie jest prawdziwe. Zapisz linie agenta w formacie path:line:symbol do citations.txt. Prompty powyżej proszą właśnie o ten format; z wyniku promptu audytowego zostaw tylko pierwszą kolumnę (cut -d'|' -f1 audit.txt | sed 's/ *$//' > citations.txt). Potem uruchom:

# terminal: every cited line must exist and contain the cited symbol
while IFS=: read -r path line sym; do
  if sed -n "${line}p" "$path" 2>/dev/null | grep -qF -- "$sym"; then
    echo "ok   $path:$line"
  else
    echo "FAIL $path:$line ($sym)"
  fi
done < citations.txt

W językach z :: w nazwach symboli (C++, Rust, PHP) użyj innego separatora, na przykład |, w prompcie i w IFS.

Każde FAIL oznacza, że agent sparafrazował, zgadł numer linii albo wskazał plik, który się przesunął. Wklej błędy z powrotem i poproś o ponowne wyszukanie tych pozycji.

Sprawdź, czy lista jest kompletna. Porównaj pliki wskazane przez agenta z niezależnym wyszukiwaniem tekstowym tego samego identyfikatora. Użyj identyfikatora z własnego wyszukiwania (tu z przykładu zmiany nazwy, applyDiscount):

# terminal: files that mention the symbol but are missing from the agent's list
rg -l -w applyDiscount src | sort > expected.txt
cut -d: -f1 citations.txt | sed "s|^\./||" | sort -u > found.txt
comm -13 found.txt expected.txt

Każdy wypisany plik to kandydat, którego agent pominął. Część to komentarze lub testy, reszta to realne braki. Przy zmianie nazwy lub sygnatury ostatecznym dowodem są type checker i testy: zielone tsc --noEmit (albo odpowiednik w twoim języku) plus przechodzące testy pokazują, że każda referencja została zaktualizowana, i robią to pewniej niż jakakolwiek lektura. Kontrolę odwołań zatwierdza programista, który zlecił wyszukiwanie; sama zmiana przechodzi przez zwykłe bramki przeglądu PR-ów agenta.

Do czego wyszukiwanie może sięgnąć, a nie powinno?

Wyszukiwanie to także ścieżka odczytu sekretów. Zanim oprzesz bezpieczeństwo na plikach ignorowania, poznaj trzy luki:

• Reguły blokujące odczyt w Claude Code mają granice. Reguła deny w rodzaju Read(./.env) obejmuje wbudowane narzędzia plikowe i polecenia plikowe, które Claude Code rozpoznaje w Bash, takie jak cat. Nie obejmuje polecenia, które czyta pliki bez ich nazywania, na przykład grep -r pattern . uruchomionego z katalogu zawierającego plik. Egzekwowanie na poziomie systemu operacyjnego daje dopiero sandbox; zobacz uprawnienia, sandboksy i tryby zatwierdzania.
• .cursorignore egzekwuje środowisko uruchomieniowe agenta Cursora, nie system operacyjny. Polecenia terminala uruchamiane przez agenta kontrolują osobno tryby uruchamiania i sandbox Cursora.
• Hostowane indeksy semantyczne wysyłają kod poza maszynę. Serwer MCP taki jak Claude Context wysyła fragmenty kodu do dostawcy embeddingów, chyba że bazę wektorową i embeddingi uruchamiasz lokalnie. Uzgodnij to z właścicielem polityki danych, zanim zaindeksujesz prywatne repozytorium.

Kiedy wyszukiwanie kodu zawodzi

Agent cytuje kod wygenerowany lub zewnętrzny. Szum nie jest wykluczony dla tego narzędzia. Dopisz ścieżkę do pliku ignorowania z kroku 1, zacznij świeżą sesję i uruchom prompt ponownie. W Claude Code na macOS, Linuksie lub WSL sprawdź, czy plik zwróciło wywołanie grep lub find przez Bash; przywróć narzędzie Grep przez --allowedTools Grep albo dopisz ścieżkę do reguł wyszukiwania w CLAUDE.md. W sesjach z włączonym Glob sprawdź, czy plik zwrócił Glob; ignoruje on .gitignore, dopóki nie ustawisz CLAUDE_CODE_GLOB_NO_IGNORE=false.

Odpowiedź opisuje niewłaściwą implementację. Repozytoria z handlerami v1 i v2 albo z kopią w skrypcie migracji mylą zarówno wyszukiwanie tekstowe, jak i semantyczne. Wskaż w prompcie katalog z działającym kodem i dopisz do mapy nawigacji linię mówiącą, która wersja jest aktualna.

Szukanie zjada okno kontekstu. Agent czyta całe pliki, żeby odpowiedzieć na pytanie o lokalizację. Dopisz do promptu „czytaj tylko pasujące funkcje” i limit plików albo deleguj szukanie do subagenta, żeby wracało tylko jego podsumowanie. Strona okna kontekstu i limity tokenów opisuje kompaktowanie, gdy jest już za późno.

Narzędzie LSP zwraca błędy albo nigdy nie jest używane. Binarki serwera językowego nie ma w PATH, wtyczka dla tego języka nie jest zainstalowana albo sesja działa w chmurze, gdzie serwery językowe z wtyczek się nie uruchamiają. Uruchom binarkę serwera ręcznie, żeby potwierdzić, że startuje, a potem zrestartuj sesję.

Wyszukiwanie semantyczne zwraca trafienia, które wyglądają wiarygodnie, ale są błędne. Wyszukiwanie po embeddingach szereguje według podobieństwa, nie poprawności. Poproś najpierw o kandydatów na identyfikatory, potwierdź każdego dokładnym wyszukiwaniem tekstowym lub po symbolach i uruchom kontrolę kompletności opisaną wyżej.

Codex przechodzi na wolne wyszukiwanie. W środowisku nie ma rg, więc model sięga po inne narzędzia, na co pozwalają mu instrukcje. Zainstaluj ripgrepa w obrazie lub dev containerze, w którym działa Codex.

Dokąd dalej po wyszukiwaniu i indeksowaniu

Serwery MCP do analizy kodu Zainstaluj Serenę, codebase-memory-mcp, Claude Context lub Repomix i przeprowadź refaktoryzację na poziomie symboli.

Organizacja plików pod agentów Nazywaj i rozmieszczaj pliki tak, żeby wyszukiwanie tekstowe od razu trafiało we właściwy.

Własni subagenci w Claude Code Zdefiniuj własnego subagenta do eksploracji, także takiego, który wczytuje twoje reguły nawigacji.

Koszt kontekstu Wyceń sesje intensywnie przeszukujące kod i zdecyduj, gdzie indeks się opłaca.