Strategie dla baz kodu 1M+ LOC

Poproszono cię o dodanie funkcjonalności do modułu przetwarzania płatności. Baza kodu to 1,8 miliona linii w 12 000 plikach. Otwierasz Cursor, wklejasz wymagania, a AI zmyśliło ścieżkę importu, która nie istnieje, odwołało się do przestarzałego wewnętrznego API i pominęło trzy inne serwisy, które muszą się zmienić jednocześnie. Okna kontekstu mają swoje ograniczenia — a duże bazy kodu przekraczają je o rzędy wielkości.

Co wyniesiesz z tego rozdziału

• Strategie dzielenia dużych baz kodu na fragmenty przyswajalne dla AI
• Wzorce promptów dające narzędziom AI wystarczający kontekst bez ich przeciążania
• Techniki utrzymywania spójności architektonicznej przy zmianach wieloplikowych
• Przepływy pracy dla bezpiecznych, przyrostowych modyfikacji w systemach krytycznych
• Metody budowania trwałego kontekstu, który przetrwa między sesjami

Problem główny: Okno kontekstu vs. rozmiar bazy kodu

Nawet przy modelach wspierających okna kontekstu 200K+ tokenów, baza kodu z milionem linii nie zmieści się. Rozwiązaniem nie jest większy kontekst — to mądrzejszy dobór kontekstu.

Piramida kontekstu

Myśl o kontekście jako o piramidzie z czterema warstwami:

1. Warstwa architektoniczna (zawsze obecna): Dokumentacja wysokopoziomowa, mapy zależności, granice modułów
2. Warstwa domenowa (specyficzna dla zadania): Podsystem, nad którym pracujesz, jego interfejsy i kontrakty
3. Warstwa implementacyjna (specyficzna dla pliku): Faktyczne pliki, które modyfikujesz
4. Warstwa referencyjna (na żądanie): Przykłady podobnych wzorców w innych częściach bazy kodu

Cursor

Indeksowanie bazy kodu w Cursor obsługuje warstwę architektoniczną automatycznie. Wzmocnij je za pomocą:

.cursor/rules

This is a large-scale payment processing platform.
Key modules:
- /src/payments/ - Payment processing (Stripe, PayPal, internal ledger)
- /src/accounts/ - User account management and KYC
- /src/notifications/ - Event-driven notification system
- /src/shared/ - Shared types, utilities, and base classes

When modifying any module, always check:
1. The module's public API in its index.ts barrel export
2. Integration tests in /tests/integration/{module-name}/
3. The event contracts in /src/shared/events/

Użyj oznaczeń @file i @folder, aby wciągać konkretny kontekst do konwersacji. Dla zmian przekrojowych, odwołaj się do grafu zależności: @src/shared/types/payment.ts przed modyfikacją jakiegokolwiek modułu związanego z płatnościami.

Claude Code

Dostęp Claude Code do systemu plików czyni go naturalnie przystosowanym do dużych baz kodu. Ustrukturyzuj swoją hierarchię CLAUDE.md:

# /CLAUDE.md (root - architecture layer)
Monorepo with 1.8M LOC. Key architectural decisions:
- Event-driven architecture using RabbitMQ
- Each service owns its database schema
- Shared types live in /packages/shared-types/
- All inter-service communication goes through /packages/event-bus/

# /packages/payments/CLAUDE.md (domain layer)
Payment service handles Stripe and PayPal integrations.
Never modify PaymentProcessor directly - extend via strategy pattern.
All new payment methods must implement IPaymentStrategy interface.

Claude Code czyta je automatycznie, budując warstwowy kontekst podczas nawigacji po bazie kodu.

Codex

Zadania chmurowe Codex działają w izolowanych środowiskach z pełnym dostępem do repozytorium. Dla dużych baz kodu:

# codex.md or AGENTS.md
Large monorepo navigation rules:
- Always run `find . -name "*.ts" -path "*/payments/*" | head -20` to orient before modifying payment code
- Check /docs/architecture/ for system design documents before cross-service changes
- Use git log --oneline -20 on target files to understand recent change patterns

When making changes that span multiple packages:
1. List all affected packages first
2. Check each package's README for modification guidelines
3. Run the package's test suite after each change

Worktrees Codex umożliwiają równoległą eksplorację różnych podsystemów bez konfliktów.

Strategie nawigowania po dużych bazach kodu

Strategia 1: Eksploracja od zależności

Zanim cokolwiek zmodyfikujesz, zmapuj promień rażenia twojej zmiany.

Wskazówka

Gotowy prompt do mapowania zależności:

Before making any changes, I need you to map the dependency graph for the PaymentProcessor class:
1. Find where PaymentProcessor is defined
2. List every file that imports or references it
3. Identify which of those files are in the critical payment path vs. auxiliary (logging, analytics)
4. Check for any event listeners or message queue consumers that react to payment events
5. Show me the dependency tree as a simple text diagram

Do not modify any files yet. I need to understand the blast radius first.

Strategia 2: Podsumowanie architektoniczne

Twórz żywe dokumenty architektoniczne, do których narzędzia AI mogą się odwoływać.

Cursor

Użyj trybu Agent w Cursor do generowania i utrzymywania podsumowań architektonicznych:

Scan the /src directory and create a concise architectural summary.
For each top-level module, document:
- Purpose (one sentence)
- Public API surface (exported functions/classes)
- Dependencies on other modules
- Database tables it owns
Save this to .cursor/architecture.md

Odwołuj się do tego pliku w przyszłych konwersacjach za pomocą @.cursor/architecture.md.

Claude Code

Generuj dokumenty architektoniczne, które stają się częścią hierarchii CLAUDE.md:

claude "Analyze the entire /src directory structure and generate
an architecture summary. For each package in /packages/:
- What it does (one line)
- Its public exports
- Which other packages it depends on
- Its test coverage status
Save to /docs/architecture-summary.md"

Claude Code będzie czytał ten plik automatycznie w przyszłych sesjach.

Codex

Zadania chmurowe Codex mogą przeprowadzać głęboką analizę architektoniczną:

Analyze this repository's architecture. Create /docs/architecture-map.md with:
- Module dependency graph (text-based)
- Data flow diagram for the main user journeys
- List of shared interfaces and where they're implemented
- Database schema ownership by module
This will be used as a reference for future development tasks.

Strategia 3: Przyrostowa modyfikacja z weryfikacją

Nigdy nie próbuj dużej zmiany w jednym podejściu. Rozbij ją na weryfikowalne kroki.

1. Zidentyfikuj wszystkie pliki, które muszą się zmienić

   Poproś AI o wylistowanie każdego dotkniętego pliku przed napisaniem jednej linii kodu. Zweryfikuj tę listę z własnym zrozumieniem.

2. Modyfikuj najpierw współdzielone interfejsy

   Zacznij od definicji typów, interfejsów i kontraktów. Te zmiany propagują błędy, które ujawniają ukryte zależności.

3. Aktualizuj implementacje moduł po module

   Modyfikuj każdy konsumujący moduł niezależnie. Uruchom testy tego modułu przed przejściem do następnego.

4. Uruchamiaj testy integracyjne po każdym module

   Nie czekaj, aż wszystkie moduły zostaną zaktualizowane. Wyłapuj problemy integracyjne wcześnie.

5. Finalna weryfikacja przekrojowa

   Uruchom pełny zestaw testów, sprawdź błędy typów w całej bazie kodu i przejrzyj kompletnego diffa przed zatwierdzeniem.

Wskazówka

Gotowy prompt do bezpiecznych przyrostowych zmian:

I need to add a `currency` field to the PaymentRequest type. This is a large codebase change.

Phase 1 - Analysis (do not modify files):
- Find the PaymentRequest type definition
- List every file that uses PaymentRequest
- Categorize files by: must change immediately vs. can use default value

Phase 2 - Interface change:
- Add currency: string to PaymentRequest with a default of "USD"
- Update the validation schema

Phase 3 - Critical path updates:
- Update PaymentProcessor to use the currency field
- Update the Stripe and PayPal adapters

After each phase, stop and let me verify before continuing.

Praca z kodem legacy

Duże bazy kodu nieuchronnie zawierają kod legacy. Narzędzia AI mogą pomóc w nawigacji, ale potrzebujesz konkretnych strategii.

Wzorzec: Podejście Kamienia z Rosetty

Znajdź najnowszy, dobrze napisany moduł, który stosuje aktualne konwencje. Użyj go jako wzorca referencyjnego, którego AI ma się trzymać przy modyfikowaniu kodu legacy.

Wskazówka

Gotowy prompt do modernizacji kodu legacy:

I need to add retry logic to the legacy OrderService (/src/legacy/OrderService.java).
Use /src/services/modern/PaymentService.java as the reference for our current patterns:
- Same error handling approach
- Same logging conventions
- Same retry strategy (exponential backoff with jitter)
- Same test structure

Do not rewrite OrderService entirely. Add the retry logic following modern conventions
while keeping the existing functionality intact. Minimize the diff.

Kiedy coś się psuje

“AI ciągle zmyśla ścieżki plików i nazwy importów.” Twoja warstwa kontekstu jest zbyt cienka. Dodaj jawne listy plików do swojego pliku reguł lub poproś AI o wyszukanie poprawnych ścieżek przed generowaniem kodu: “First, find where UserService is actually defined in this codebase, then write the import.”

“Zmiany działają w izolacji, ale łamią integrację.” Pominąłeś krok mapowania zależności. Zawsze mapuj promień rażenia przed rozpoczęciem. Użyj strategii przyrostowej modyfikacji z weryfikacją między każdą fazą.

“AI sugeruje wzorce, które są sprzeczne z naszą architekturą.” Dokumentacja twojej warstwy architektonicznej jest brakująca lub nieaktualna. Zainwestuj czas w utrzymywanie plików CLAUDE.md lub .cursor/rules kodujących decyzje i ograniczenia architektoniczne.

“Okno kontekstu wypełnia się, zanim skończę zadanie.” Rozbij zadanie na podzadania. Każde podzadanie powinno być możliwe do ukończenia w jednej konwersacji. Użyj podsumowań architektonicznych do szybkiego odbudowywania kontekstu w nowych sesjach.

Co dalej

Zarządzanie monorepo Przepływy pracy AI specyficzne dla architektur monorepo z zależnościami między pakietami.

Mikroserwisy z AI Koordynuj zmiany wspomagane AI przez granice rozproszonych serwisów.

Zarządzanie kontekstem Głębokie zanurzenie w optymalizację okien kontekstu i wzorce pamięci.