Strategie dla dużych baz kodu

Dołączyłeś do zespołu pracującego nad monolitem TypeScript liczącym 300 000 linii. Otwierasz Cursor, prosisz o wyjaśnienie przepływu uwierzytelniania i wraca z niejasną odpowiedzią, która pomija połowę łańcucha middleware. Próbujesz trybu Agent dla funkcji, a on tworzy nowy plik od zera zamiast integrować się z istniejącą warstwą serwisu trzy katalogi w głąb. Baza kodu jest zbyt duża, aby AI mógł ją pomieścić w kontekście za jednym razem, i bez wskazówek robi założenia, które nie pasują do Twojej architektury.

Duże bazy kodu wymagają fundamentalnie innego podejścia do rozwoju wspomaganego przez AI. Musisz prowadzić AI do właściwych części bazy kodu, dokumentować wzorce, których nie może wywnioskować, i strukturyzować prompty wokół zakresowych, przyrostowych zmian.

Co wyniesiesz

• Podejście oparte na regułach do kodowania wiedzy domenowej, której AI nie może wywnioskować tylko z kodu
• Strategie zarządzania kontekstem, które kierują agenta na właściwe pliki bez spalania budżetu tokenów
• Wzorce promptów zaprojektowane dla zakresowych, przyrostowych zmian w dużych bazach kodu
• Konfiguracja indeksowania i przestrzeni roboczej dla optymalnej wydajności

Pisz reguły dla wiedzy specyficznej dla domeny

Pomyśl o tym, co powiedziałbyś nowemu pracownikowi pierwszego dnia. Jaki kontekst by potrzebowali, aby zacząć wnosić znaczący wkład? Ten sam kontekst jest cenny dla Cursor.

Stwórz pliki .cursor/rules/, które przechwytują wiedzę nie oczywistą z czytania kodu:

---
description: Add a new API endpoint
alwaysApply: false
---

When creating new API endpoints:

1. Define the route in src/routes/[domain]/index.ts
2. Create the controller in src/controllers/[domain]/
3. Add validation schemas in src/schemas/[domain].ts using Zod
4. Register the route in src/app.ts under the appropriate middleware group
5. All endpoints must use the withAuth middleware unless explicitly public
6. Error responses use our standard format: { error: string, code: string, details?: unknown }

See @src/routes/users/index.ts for a complete example.

Wskazówka

Gotowa do skopiowania i wklejenia reguła dla konwencji plików:

Stwórz .cursor/rules/file-conventions.mdc:

---
globs: "*.ts"
alwaysApply: true
---

- Use kebab-case for file names (user-service.ts, not userService.ts)
- Use camelCase for function and variable names
- Use PascalCase for classes, interfaces, and type aliases
- Use UPPER_SNAKE_CASE for constants
- Prefer named exports over default exports
- One primary export per file

Auto-dołącz reguły ze wzorcami glob

Reguły pasujące do konkretnych wzorców plików są automatycznie dołączane, gdy agent pracuje z pasującymi plikami. Twoje konwencje backendowe ładują się tylko dla plików backendowych, konwencje frontendowe tylko dla pracy frontendowej:

---
globs: "src/api/**/*.ts"
---

Backend API conventions:
- All handlers receive (req: Request, res: Response, next: NextFunction)
- Use the logger from @src/lib/logger, never console.log
- Database queries go through the repository layer, never raw SQL in handlers
- All mutations must be wrapped in transactions

Zawężaj każdy prompt

Najbardziej ważny nawyk dla dużych baz kodu: nigdy nie proś Agenta o zrobienie zbyt wiele na raz. Zamiast “dodaj kontrolę dostępu opartą na rolach do aplikacji”, rozbij to:

1. “Add a role column to the users table and create the migration” (1-2 pliki)
2. “Create a withRole middleware that checks user roles, following the pattern in @src/middleware/auth.ts” (1-2 pliki)
3. “Apply the withRole('admin') middleware to the admin routes in @src/routes/admin/index.ts” (1 plik)
4. “Add tests for the role middleware in @src/middleware/tests/role.test.ts” (1 plik)

Każdy krok jest wystarczająco mały, aby agent pomieścił cały istotny kontekst i wyprodukował dokładne wyjście. Każdy krok buduje na zatwierdzonej, zweryfikowanej pracy z poprzedniego kroku.

Wskazówka

Prompt gotowy do skopiowania i wklejenia dla zakresowej implementacji:

I need to add email notification support. Start with just the email service layer.

Create src/services/email-service.ts that:
- Uses Resend as the email provider (see @package.json for the dependency)
- Follows the same service pattern as @src/services/payment-service.ts
- Exports sendEmail(to, subject, htmlBody) and sendTemplateEmail(to, templateId, variables)
- Includes proper error handling and retry logic
- Logs all email sends using our logger from @src/lib/logger.ts

Do NOT create routes, controllers, or templates yet. Just the service layer.

Używaj czatu do zapoznania się

Podczas nawigacji po nieznanej części dużej bazy kodu użyj trybu Ask przed wprowadzeniem jakichkolwiek zmian:

Trace the request lifecycle for POST /api/orders/create.

Start from the route definition, through all middleware, into the controller,
through the service layer, and into the database queries. List every file
in the call chain and explain what each one does.

Include error handling paths -- what happens when validation fails,
when the database is unavailable, and when the payment provider rejects.

Ten rodzaj eksploracji w trybie Ask zajmuje 30 sekund i oszczędza 15 minut ręcznej nawigacji po plikach.

Wybierz właściwe narzędzie dla każdej edycji

Narzędzie	Najlepsze do	Zakres	Szybkość
Tab	Szybkie ręczne edycje z sugestiami AI	Pojedyncza pozycja kursora	Natychmiastowa
Edycja inline (Cmd/Ctrl+K)	Skoncentrowane zmiany zaznaczonego kodu	Pojedynczy plik	Szybka
Agent (Cmd/Ctrl+I)	Funkcje wieloplikowe i refaktoryzacja	Wiele plików	Dokładna

W dużych bazach kodu Tab i Edycja inline obsługują 60-70% Twoich zmian. Są szybsze, bardziej przewidywalne i nie wymagają, aby AI rozumiało cały projekt. Zachowaj Agenta dla zmian, które naprawdę obejmują wiele plików.

Wskazówka

Gotowe do skopiowania i wklejenia dla ukierunkowanej edycji inline:

Zaznacz funkcję, naciśnij Cmd/Ctrl+K i wklej:

Refactor this function to use async/await instead of .then() chains. Preserve all error handling. Do not change the function signature or return type.

Zarządzanie kontekstem w skali

Używaj wzmianek @ obficie

W dużych bazach kodu agent potrzebuje Twojej pomocy w znalezieniu właściwych plików:

Add a new user notification preferences endpoint.

Follow the patterns in:
- @src/routes/users/index.ts (route definition)
- @src/controllers/users/profile.ts (controller pattern)
- @src/schemas/user.ts (validation schema)
- @src/services/user-service.ts (service layer)

The new endpoint should be PATCH /api/users/notification-preferences

Używaj .cursorignore do redukcji szumu

Wyklucz katalogi, które dodają szum bez wartości:

.cursorignore

node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.map
vendor/
__generated__/

To zmniejsza czas indeksowania, utrzymuje okno kontekstu czyste i zapobiega odnoszeniu się agenta do wygenerowanego lub vendorowanego kodu.

Często rozpoczynaj nowe czaty

Długie rozmowy w dużych bazach kodu to przepis na zamieszanie. Agent gromadzi kontekst z wcześniejszych wiadomości i może odwoływać się do nieaktualnych informacji.

Rozpocznij nowy czat, gdy:

• Przechodzisz do innej części bazy kodu
• Zatwierdziłeś zestaw zmian i zaczynasz następny element
• Agent odnosi się do plików lub kodu, który już nie istnieje
• Wymieniasz się wiadomościami przez więcej niż 5-6 wymian

Kiedy to się psuje

Agent tworzy pliki od zera zamiast integrować się z istniejącymi wzorcami. Twoje reguły nie są wystarczająco szczegółowe. Dodaj regułę opisującą strukturę plików i odnoszącą się do kanonicznych przykładów ze wzmiankami @file.

Agent traci kontekst w połowie dużej zmiany. Zmiana jest zbyt duża dla jednego promptu. Rozbij ją na mniejsze, zatwierdzone kroki.

Indeksowanie trwa zbyt długo lub zużywa zbyt dużo pamięci. Upewnij się, że .cursorignore wyklucza wygenerowane pliki, artefakty budowy i duże katalogi vendorów. Zobacz Optymalizacja wydajności.

Agent stosuje się do niewłaściwych konwencji. Stwórz reguły o zakresie glob, które automatycznie dołączają się przy edycji konkretnych katalogów. Reguła backendowa, która ładuje się dla src/api/**/*.ts, zapewnia prawidłowe konwencje bez powtarzania ich w każdym promptcie.

Co dalej

• Niestandardowe reguły i szablony — Głębokie zanurzenie w budowaniu kompleksowej biblioteki reguł
• Optymalizacja wydajności — Dostrajanie indeksowania i pamięci dla dużych projektów
• Zarządzanie tokenami — Zarządzanie kosztami, gdy okna kontekstu są duże