Strategie dla dużych baz kodu: Wskazówki 76-90

Twój projekt osiągnął 200 000 linii kodu. Indeksowanie Cursor trwa 20 minut, odpowiedzi agenta odwołują się do plików sprzed dwóch lat, a sugestie Tab pobierają wzorce z przestarzałych modułów. Narzędzie, które przyspieszyło cię w małych projektach, teraz zwalnia cię w projekcie, który się liczy. Te 15 wskazówek rozwiązuje problem skalowania.

Co wynieiesz z tej sekcji

• Strategię indeksowania, która utrzymuje Cursor szybkim na bazach kodu powyżej 500k linii
• Zarządzanie budżetem kontekstu, które zapobiega topieniu się agenta w nieistotnych plikach
• Konfiguracje wielokorzeniowych obszarów roboczych dla monorepo i konfiguracji multi-repo
• Techniki ograniczonego wyszukiwania i nawigacji, które znajdują właściwy kod w sekundy, nie minuty
• Prompty analizy architektonicznej, które pomagają zrozumieć nieznane obszary dużej bazy kodu

Strategia indeksowania

Wskazówka 76: Skonfiguruj wykluczenia przed otwarciem dużego projektu

Przy pierwszym otwarciu dużego projektu Cursor indeksuje wszystko. Jeśli twój node_modules ma 100 000 plików, to 100 000 plików zużywających pamięć i CPU, zanim napiszesz choćby jedną linię kodu. Najpierw skonfiguruj wykluczenia:

Utwórz lub zaktualizuj .cursorignore w katalogu głównym projektu (działa jak .gitignore):

# Artefakty buildów
dist/
build/
.next/
out/
coverage/

# Zależności
node_modules/
vendor/
.pnp/

# Wygenerowany kod
*.generated.ts
*.generated.js
prisma/generated/
graphql/generated/

# Duże pliki binarne
*.wasm
*.map
*.min.js
*.min.css
*.bundle.js

# Pliki lock (ogromne, rzadko użyteczne dla AI)
package-lock.json
pnpm-lock.yaml
yarn.lock

Nie wykluczaj swojego kodu źródłowego

Powszechnym błędem jest zbyt agresywne wykluczanie. Nigdy nie wykluczaj rzeczywistych katalogów źródłowych (src/, lib/, app/), plików testowych ani plików konfiguracyjnych. AI potrzebuje ich, aby zrozumieć twój projekt.

Wskazówka 77: Otwieraj konkretne pakiety zamiast katalogu głównego monorepo

W monorepo z 20 pakietami otwarcie katalogu głównego zmusza Cursor do indeksowania wszystkiego. Zamiast tego otwórz tylko pakiety, nad którymi aktywnie pracujesz:

# Zamiast:
cursor ~/projects/big-monorepo

# Otwórz konkretne pakiety jako wielokorzeniowy obszar roboczy:
cursor ~/projects/big-monorepo/packages/web \
       ~/projects/big-monorepo/packages/api \
       ~/projects/big-monorepo/packages/shared

Lub utwórz plik obszaru roboczego dla częstych kombinacji:

// web-api.code-workspace
{
  "folders": [
    { "path": "packages/web", "name": "Web App" },
    { "path": "packages/api", "name": "API Server" },
    { "path": "packages/shared", "name": "Shared Types" },
    { "path": "packages/config", "name": "Config" }
  ]
}

Wskazówka 78: Monitoruj i zarządzaj zdrowiem indeksowania

Regularnie sprawdzaj status indeksowania w Ustawienia > Indexing and Docs. Zdrowe wskaźniki:

Rozmiar bazy kodu	Oczekiwany czas indeksowania	Rozmiar indeksu
Poniżej 10k plików	1-3 minuty	Poniżej 500 MB
10k-50k plików	3-10 minut	500 MB - 2 GB
50k-200k plików	10-30 minut	2-5 GB
Powyżej 200k plików	Używaj wykluczeń agresywnie	Celuj poniżej 5 GB

Jeśli indeksowanie przekracza te czasy, twoje wykluczenia wymagają pracy. Najczęstsi winowajcy: niewykluczony node_modules, duże wygenerowane pliki lub binarne zasoby w drzewie źródłowym.

Zarządzanie budżetem kontekstu

Wskazówka 79: Myśl w kategoriach budżetów kontekstu

Każda konwersacja z agentem ma skończone okno kontekstowe. W dużej bazie kodu szybko osiągniesz ten limit, jeśli odniesiesz się do zbyt wielu plików. Myśl o kontekście jak o budżecie:

• Budżet: ~200k tokenów na konwersację (różni się w zależności od modelu i trybu)
• Koszt na plik: Typowy 200-liniowy plik TypeScript kosztuje ~1000-2000 tokenów
• Koszt na katalog: Odniesienie się do @src/ w projekcie z 500 plikami kosztuje cały twój budżet

Dyscyplina: odnoszenie się do minimalnej liczby plików potrzebnych do zadania. Zacznij wąsko i rozszerzaj tylko wtedy, gdy agent powie, że potrzebuje więcej kontekstu.

Wskazówka 80: Używaj plików podsumowujących dla dużych modułów

Dla modułów zbyt dużych, aby odwoływać się do nich bezpośrednio, utwórz plik podsumowujący, do którego agent może się zamiast tego odwołać:

src/payments/ARCHITECTURE.md

# Architektura modułu płatności

## Kluczowe pliki
- `service.ts` - Główne przetwarzanie płatności (integracja Stripe)
- `webhook.ts` - Handlery webhooków dla zdarzeń płatności
- `types.ts` - Interfejsy TypeScript dla encji płatności
- `repository.ts` - Operacje bazodanowe (PostgreSQL przez Drizzle)

## Przepływ danych
1. Klient wywołuje POST /api/payments/checkout
2. service.ts tworzy sesję Stripe
3. Stripe wysyła webhook do webhook.ts
4. webhook.ts aktualizuje status płatności przez repository.ts
5. WebSocket powiadamia klienta o zmianie statusu

## Kluczowe ograniczenia
- Wszystkie kwoty w centach (integer, nigdy float)
- Klucze idempotentności wymagane dla wszystkich wywołań Stripe
- Weryfikacja webhooka musi nastąpić przed przetworzeniem

Teraz zamiast @src/payments/ (co może zużyć 50k tokenów), odwołaj się do @src/payments/ARCHITECTURE.md (2k tokenów) i pobieraj konkretne pliki tylko w razie potrzeby.

Wskazówka 81: Używaj ograniczonych konwersacji z agentem

Dla dużych baz kodu ograniczaj każdą konwersację z agentem do konkretnego obszaru:

Szablon promptu ograniczonego agenta (skopiuj i wklej)

Kontekst: Pracuję w module płatności. Odnoszę się tylko do plików w @src/payments/ i @src/shared/types/.

Zadanie: Dodaj endpoint refund, który wywołuje API refund Stripe, aktualizuje status płatności w naszej bazie danych i wysyła email z powiadomieniem.

Ograniczenia: Postępuj zgodnie ze wzorcami w @src/payments/service.ts dla wywołań Stripe i @src/payments/repository.ts dla operacji bazodanowych. Nie modyfikuj żadnych plików poza @src/payments/.

Wyraźny zakres zapobiega wędrówkom agenta do niepowiązanych modułów i zużywaniu twojego budżetu kontekstu na nieistotny kod.

Nawigacja na dużą skalę

Wskazówka 82: Łącz wyszukiwanie semantyczne z Grep dla precyzji

W dużej bazie kodu ani wyszukiwanie semantyczne, ani wyszukiwanie tekstowe samo w sobie nie jest wystarczające:

• Wyszukiwanie semantyczne znajduje kod konceptualnie powiązany, ale może zwrócić wyniki z przestarzałych modułów
• Wyszukiwanie tekstowe (grep) znajduje dokładne dopasowania, ale pomija kod, który robi to samo różnymi nazwami

Połączony przepływ pracy:

Znajdź cały kod, który obsługuje odnowienie subskrypcji. Użyj wyszukiwania
semantycznego do identyfikacji odpowiednich modułów, następnie grep dla
konkretnych wywołań funkcji 'renewSubscription', 'processRenewal' i
'handleRenewalWebhook'. Pokaż mi wyniki tylko z aktywnej bazy kodu --
ignoruj wszystko w src/legacy/ lub src/deprecated/.

Wskazówka 83: Użyj wyszukiwania @codebase dla zrozumienia międzymodułowego

Gdy potrzebujesz zrozumieć, jak koncepcja rozciąga się na wiele modułów:

Prompt analizy międzymodułowej (skopiuj i wklej)

@codebase Jak przepływ uwierzytelniania użytkownika przebiega przez tę aplikację? Prześledź ścieżkę od endpointu API logowania przez middleware, serwisy i zapytania bazodanowe. Pokaż mi kluczowe pliki zaangażowane i transformacje danych na każdym kroku.

Ten prompt uruchamia semantyczne zrozumienie całej zaindeksowanej bazy kodu przez Cursor. Jest wolniejszy niż wyszukiwania ograniczone, ale daje pełny obraz, gdy potrzebujesz zrozumieć przekrojowe kwestie.

Wskazówka 84: Buduj mapy mentalne nieznanego kodu

Przy onboardingu do dużej bazy kodu użyj agenta do zbudowania uporządkowanego zrozumienia:

1. “Jakie są katalogi najwyższego poziomu i za co każdy z nich odpowiada?”
2. “Pokaż mi główne punkty wejścia — gdzie przychodzą żądania HTTP i gdzie zaczynają się zaplanowane zadania?”
3. “Jakie są główne modele domenowe i jak się do siebie odnoszą?”
4. “Od jakich zewnętrznych serwisów zależy ta aplikacja? (bazy danych, API, kolejki wiadomości)”
5. “Gdzie są najbardziej złożone części bazy kodu? Które pliki mają najwięcej zależności?”

Każde pytanie buduje na poprzednich odpowiedziach, dając ci uporządkowaną mapę mentalną w ciągu 30 minut.

Techniki specyficzne dla monorepo

Wskazówka 85: Używaj zasad specyficznych dla obszaru roboczego w monorepo

W monorepo różne pakiety często mają różne konwencje. Utwórz zasady specyficzne dla pakietów:

packages/web/.cursor/rules/web.md       # Konwencje React
packages/api/.cursor/rules/api.md       # Konwencje Express
packages/shared/.cursor/rules/shared.md # Czyste zasady TypeScript
packages/mobile/.cursor/rules/mobile.md # Konwencje React Native

Gdy agent edytuje pliki w packages/web/, pobiera zasady specyficzne dla React. Gdy edytuje packages/api/, otrzymuje zasady specyficzne dla Express. Zapobiega to stosowaniu przez agenta wzorców React do twojego kodu API lub vice versa.

Wskazówka 86: Obsługuj zależności międzypakietowe wyraźnie

Gdy zmiana w jednym pakiecie wymaga aktualizacji w innym, bądź wyraźny co do łańcucha zależności:

Prompt zmiany międzypakietowej (skopiuj i wklej)

Muszę dodać pole “organizationId” do typu User.

Krok 1: Zaktualizuj definicję typu w @packages/shared/src/types/user.ts Krok 2: Zaktualizuj schemat bazy danych w @packages/api/src/db/schema.ts i utwórz migrację Krok 3: Zaktualizuj endpointy API w @packages/api/src/routes/users.ts, aby akceptować i walidować organizationId Krok 4: Zaktualizuj formularz frontendowy w @packages/web/src/components/UserForm.tsx, aby uwzględnić nowe pole

Wykonaj każdy krok po kolei. Zweryfikuj, że TypeScript kompiluje się po każdym kroku przed przejściem do następnego.

Wskazówka 87: Używaj ukierunkowanej refaktoryzacji w pakietach

Przy refaktoryzacji wspólnego typu lub interfejsu promień rażenia może obejmować całe monorepo. Kontroluj to:

Zmień nazwę typu "UserRole" na "AccountRole" w @packages/shared/src/types.ts.
Następnie znajdź i zaktualizuj każdy import i użycie we wszystkich pakietach.
Uruchom pnpm run typecheck w katalogu głównym monorepo po zmianie nazwy,
aby zweryfikować, że nie ma złamanych odniesień.

Z włączonym trybem YOLO agent dokonuje zmiany nazwy, uruchamia TypeScript, widzi ewentualne pozostałe złamane odniesienia i naprawia je iteracyjnie.

Optymalizacja wydajności

Wskazówka 88: Zamykaj pliki, których aktywnie nie edytujesz

Cursor używa otwartych plików jako kontekstu wysokiego priorytetu. W dużej bazie kodu możesz łatwo zgromadzić ponad 30 otwartych zakładek, z których większość jest nieistotna dla twojego bieżącego zadania. Degraduje to:

• Jakość przewidywania Tab (zbyt wiele zaszumionego kontekstu)
• Czas odpowiedzi agenta (więcej plików do rozważenia)
• Użycie pamięci (Cursor przechowuje otwarte pliki w pamięci)

Zamykaj zakładki agresywnie. Używaj Cmd+P do przeskakiwania do plików, gdy ich potrzebujesz, zamiast trzymać je permanentnie otwarte.

Wskazówka 89: Używaj trybu Max selektywnie dla analizy dużych plików

Tryb Max daje rozszerzone okna kontekstowe przy wyższym koszcie. W dużej bazie kodu kuszące jest, aby zawsze go włączać. Nie rób tego. Włączaj tryb Max tylko dla:

• Analizowania pojedynczych plików powyżej 3000 linii
• Zrozumienia złożonych łańcuchów zależności obejmujących 10+ plików
• Planowania zmian architektonicznych wymagających utrzymania całej struktury modułu w kontekście

Dla wszystkiego innego — implementowania funkcji, naprawiania błędów, pisania testów — tryb standardowy jest wystarczający i znacznie tańszy.

Wskazówka 90: Utwórz ściągę “Szybkiego kontekstu” dla swojego projektu

Dla baz kodu, nad którymi pracujesz codziennie, utwórz plik referencyjny, który daje agentowi natychmiastowy kontekst:

Szablon kontekstu projektu (skopiuj i wklej)

.cursor/project-context.md

# Szybki kontekst projektu

## Architektura
- Monorepo z 4 pakietami: web (Next.js), api (Express), shared (typy), mobile (React Native)
- PostgreSQL + Redis, wdrożone na AWS ECS
- Uwierzytelnianie: JWT z tokenami odświeżania, zarządzane przez packages/api/src/auth/

## Kluczowe wzorce
- Wszystkie trasy API używają wzorca w packages/api/src/routes/users.ts
- Zapytania bazodanowe przechodzą przez Drizzle ORM, schemat w packages/api/src/db/schema.ts
- Zarządzanie stanem frontendu przez sklepy Zustand w packages/web/src/stores/
- Wspólne typy eksportowane z packages/shared/src/index.ts

## Częste polecenia
- pnpm run dev: Uruchom wszystkie pakiety w trybie deweloperskim
- pnpm run test: Uruchom vitest we wszystkich pakietach
- pnpm run typecheck: Sprawdzenie TypeScript we wszystkich pakietach
- pnpm run db:migrate: Uruchom oczekujące migracje bazy danych

Odwołaj się do tego pliku na początku złożonych konwersacji z agentem, aby dać natychmiastowy, efektywny tokenowo kontekst.

Kiedy to nie działa

Indeksowanie utknęło na procencie i nie postępuje: Zazwyczaj pojedynczy duży plik blokuje indekser. Sprawdź wygenerowane pliki (GraphQL codegen, klient Prisma, skompilowane zasoby), które prześlizgnęły się przez twoje wykluczenia. Dodaj je do .cursorignore i zrestartuj indeks.

Agent daje odpowiedzi o niewłaściwej części bazy kodu: W monorepo agent czasami myli podobnie nazwane pliki w pakietach. Bądź wyraźny co do tego, który pakiet: “@packages/api/src/users.ts — nie ten w packages/web.”

Sugestie Tab są wolne w dużych projektach: Zmniejsz liczbę otwartych zakładek, zamknij nieistotne pliki i zweryfikuj, że twoje wykluczenia działają. Szybkość Tab jest bezpośrednio proporcjonalna do ilości kontekstu, który musi przetworzyć.

Jakość odpowiedzi agenta spada w środku konwersacji: Nasycenie kontekstu. Rozpocznij nową konwersację. W dużych bazach kodu konwersacje z agentem powinny być krótsze i bardziej skoncentrowane niż w małych projektach. Dąż do maksymalnie 5-10 wymian przed rozpoczęciem od nowa.

Co dalej

Teraz możesz obsługiwać bazy kodu w każdej skali. Przejdź do Zaawansowanych technik (Wskazówki 91-105), aby poznać integrację serwera MCP, agentów w tle, niestandardowe automatyzacje i funkcje poziomu eksperta, które pchają Cursor do jego granic.