Strategie wyszukiwania i indeksowania

Pytasz AI “gdzie obsługujemy webhooki płatności?” AI spędza 30 sekund na czytaniu całego katalogu src/, znajduje sześć plików wspominających o “płatności,” czyta je wszystkie i w końcu daje odpowiedź — ale zużyło 15 000 tokenów kontekstu. Tymczasem dobrze zaindeksowany projekt zwróciłby odpowiedni plik w mniej niż sekundę z minimalnymi kosztami kontekstu.

To, jak twoje narzędzie AI znajduje kod, ma równie duże znaczenie jak to, co znajduje. Różnica między narzędziem, które grepuje na ślepo, a takim, które używa rozumienia semantycznego, decyduje o tym, czy twoje okno kontekstu przetrwa wystarczająco długo, aby faktycznie wdrożyć poprawkę.

Czego się nauczysz

Jasne zrozumienie, jak każde narzędzie indeksuje i przeszukuje bazę kodu
Strategie optymalizacji wyników wyszukiwania w każdym narzędziu
Prompty kierujące efektywnym odkrywaniem kodu bez marnowania kontekstu
Wzorce konfiguracji dla plików ignorowania, ustawień indeksowania i zawężania wyszukiwania

Jak każde narzędzie przeszukuje

Trzy narzędzia stosują zasadniczo różne podejścia do odkrywania kodu, a zrozumienie tych różnic pomaga efektywniej z nimi pracować.

Cursor używa wyszukiwania semantycznego opartego na embeddingach generowanych przez AI. To najbardziej zaawansowane podejście:

Gdy otwierasz workspace, Cursor skanuje pliki i dzieli je na znaczące fragmenty (funkcje, klasy, bloki logiczne)
Każdy fragment jest konwertowany na embedding wektorowy, który chwyta jego znaczenie semantyczne
Embeddingi są przechowywane w bazie wektorowej zoptymalizowanej pod szybkie wyszukiwanie podobieństwa
Gdy ty lub agent przeszukujecie, zapytanie jest również konwertowane na wektor i porównywane z przechowywanymi embeddingami

Co to oznacza w praktyce: Możesz wyszukiwać według znaczenia, a nie tylko tekstu. Pytanie “gdzie jest obsługiwana autentykacja” znajdzie auth.ts, session-manager.ts i login-handler.ts, mimo że żaden z nich nie zawiera słowa “autentykacja” w nazwie pliku.

Cursor używa również tradycyjnego grepa obok wyszukiwania semantycznego. Agent decyduje, które podejście zastosować na podstawie zapytania — dokładne dopasowania wzorców używają grepa, zapytania koncepcyjne używają wyszukiwania semantycznego.

Kluczowa konfiguracja:

Sprawdź status indeksowania w Cursor Settings > Indexing & Docs
Wyszukiwanie semantyczne staje się dostępne przy 80% ukończenia indeksowania
Indeks automatycznie aktualizuje się co 5 minut, przetwarzając tylko zmienione pliki
Użyj .cursorignore do wyłączenia plików z indeksowania

Claude Code używa narzędzi plikowych do odkrywania kodu: Read, Grep, Glob i Bash. Nie ma wstępnie zbudowanego indeksu semantycznego — Claude nawiguje po bazie kodu w czasie rzeczywistym za pomocą tych narzędzi.

Grep: Wyszukiwanie tekstu oparte na wzorcach w plikach. Szybkie dla dokładnych dopasowań
Glob: Znajdowanie plików według wzorca nazwy (np. **/*.test.ts)
Read: Czytanie konkretnych plików lub ich fragmentów
Bash: Uruchamianie komend takich jak find, ag lub rg dla bardziej złożonych wyszukiwań

Co to oznacza w praktyce: Wyszukiwanie Claude jest precyzyjne i deterministyczne, ale polega na wiedzy, gdzie szukać. Opisowe nazwy plików i przejrzysta struktura projektu dramatycznie poprawiają zdolność Claude do szybkiego znajdowania odpowiedniego kodu.

Claude Code obsługuje również subagentów do badania. Gdy potrzebujesz szerokiej eksploracji bazy kodu, subagent może przeszukiwać we własnym oknie kontekstu i raportować podsumowanie, utrzymując twoją główną sesję czystą:

Use a subagent to investigate where payment webhooks are handled.
Report back the key files and the flow.

Optymalizacja pod wyszukiwanie

Nazywaj rzeczy tak, aby były łatwe do znalezienia

Najważniejsza rzecz, jaką możesz zrobić dla jakości wyszukiwania we wszystkich narzędziach: używaj opisowych, spójnych nazw.

# Źle: AI musi przeczytać każdy plik, żeby wiedzieć, co jest w środku
src/
  utils.ts
  helpers.ts
  service.ts
  handler.ts

# Dobrze: AI może znaleźć to, czego potrzebuje, po samych nazwach plików
src/
  payment-webhook-handler.ts
  email-notification-service.ts
  password-validation.ts
  date-formatting.ts

Konfiguruj pliki ignorowania

Każde narzędzie respektuje .gitignore, ale powinieneś również skonfigurować ignorowanie specyficzne dla narzędzia dla plików śledzonych w git, ale nieistotnych dla pracy z AI.

Stwórz plik .cursorignore w katalogu głównym projektu:

# Duże pliki danych
data/fixtures/*.json
scripts/migration-data/

# Wygenerowany kod (czytaj źródło zamiast tego)
src/generated/
src/__generated__/

# Zbudowana dokumentacja
docs/build/

# Pliki lock (za duże, za zaszumione)
pnpm-lock.yaml

Ignorowanie dużych plików poprawia zarówno prędkość indeksowania, jak i dokładność odpowiedzi, ponieważ AI skupia się na kodzie źródłowym, a nie na szumie.

Claude Code natywnie respektuje .gitignore. Dla dodatkowych wyłączeń dodaj wskazówki do CLAUDE.md:

# Files to ignore
- Do not read files in src/generated/ -- these are auto-generated
- Do not read *.lock files
- Focus on src/ for application code
- Focus on tests/ for test files

Możesz również użyć .claude/settings.json do konfiguracji granic uprawnień, które uniemożliwiają Claude czytanie określonych ścieżek.

Codex respektuje .gitignore. Dodaj dodatkowe wskazówki w AGENTS.md:

## Code Navigation
- Application source is in src/
- Tests are in tests/ (co-located with source)
- Ignore src/generated/ -- auto-generated, do not read or modify
- Ignore data/ -- large fixtures, not relevant for code tasks

I need to find where [SPECIFIC BEHAVIOR] is implemented.

Search strategy:
1. Search for relevant function/class names (not just the concept)
2. Check import statements to trace the dependency chain
3. Read only the relevant functions, not entire files
4. Report: file path, function name, and a 2-3 sentence summary

Do not read more than 4 files. If you cannot find it in 4 files,
tell me what you searched for and I will narrow it down.

Zaawansowane wzorce wyszukiwania

Śledzenie funkcji od początku do końca

Gdy musisz zrozumieć, jak funkcja działa w wielu warstwach (route -> controller -> service -> baza danych), pokieruj AI, aby efektywnie prześledziło ścieżkę.

Trace the [FEATURE] flow from entry point to database:

1. Find the route/endpoint that handles [USER ACTION]
2. Follow the handler to the service layer
3. Follow the service to the data access layer
4. Identify the database tables/queries involved

At each step, note the file, function, and any middleware/interceptors.
Read only the relevant functions at each layer -- not entire files.
Produce a summary diagram of the flow.

Znajdowanie wszystkich użyć wzorca

Wyszukiwanie semantyczne Cursor może znaleźć koncepcyjnie podobny kod:

Find all places in the codebase where we handle errors from
external API calls. I want to see if we have a consistent pattern
or if each service handles errors differently.

Claude może połączyć Grep i Read do precyzyjnego odkrywania wzorców:

Search the codebase for all instances of try/catch blocks that
handle HTTP errors from external APIs. Use grep to find them,
then read the surrounding context for each. Group them by
pattern -- are they consistent or inconsistent?

Find all error handling patterns for external API calls in this
codebase. List each file and the pattern used. Identify if there
is a standard pattern or if they vary.

Gdy coś nie działa

Wyszukiwanie semantyczne zwraca nieistotne wyniki. Zwykle oznacza to, że indeks zawiera za dużo szumu (artefakty budowania, vendored code, duże pliki danych). Zaktualizuj pliki ignorowania i pozwól indeksowi się przebudować.

AI czyta za dużo plików podczas wyszukiwania. Ustaw jawne limity w promptach: “Nie czytaj więcej niż 5 plików.” W Claude Code użyj subagentów do szerokich wyszukiwań, aby utrzymać główny kontekst czysty.

Wyszukiwanie znajduje złą wersję funkcji. W bazach kodu z wieloma implementacjami tego samego konceptu (np. v1 i v2 API), powiedz AI, na której wersji ma się skupić. Wskaż konkretny katalog lub plik.

Indeksowanie trwa za długo lub się nie udaje. Duże bazy kodu (100K+ plików) mogą się wolno indeksować. W Cursor upewnij się, że .cursorignore wyłącza duże katalogi. Indeks buduje się przyrostowo, więc możesz zacząć pracować, gdy osiągnie 80% ukończenia.

Co dalej

Wzorce pamięci Zachowaj wnioski z wyszukiwań na stałe między sesjami dzięki auto-pamięci i regułom projektu.

Organizacja plików Zorganizuj bazę kodu tak, aby wyniki wyszukiwania były trafne i minimalne.

Koszt kontekstu Zrozum koszt sesji intensywnie korzystających z wyszukiwania i jak go zoptymalizować.