Prosisz Claude o refaktoryzację przepływu uwierzytelniania w monorepo na 400 tys. linii, a on z pełnym przekonaniem edytuje niewłaściwy serwis: przestarzały pakiet legacy-auth zamiast tego żywego, bo nigdy nie wczytał właściwego kontekstu. W dużej bazie kodu ograniczeniem nie jest już “czy model potrafi napisać kod”, lecz “czy ma w kontekście właściwy wycinek repozytorium - i tylko ten wycinek”.
Te 15 wskazówek pokazuje, jak nawigować, rozumieć i bezpiecznie modyfikować bazy kodu na skalę przedsiębiorstwa z Claude Code, nie topiąc go w nieistotnym kontekście i nie pozwalając, by równoległe sesje nadpisywały się nawzajem.
CLAUDE.md, który daje Claude właściwy kontekst dla każdego pakietu bez rozdymania każdego promptuClaude Code używa wyszukiwania agentowego, aby automatycznie zrozumieć strukturę twojego projektu. Zamiast wklejać pliki czy samodzielnie tłumaczyć układ, możesz zadać pytanie w stylu “Wyjaśnij, jak działa system uwierzytelniania”, a Claude wyszuka pliki związane z auth, zidentyfikuje kluczowe komponenty, prześledzi zależności, podąży za przepływem i da ci ugruntowane wyjaśnienie.
Możliwości wyszukiwania agentowego
Typowe pytanie wdrożeniowe na platformie danych wygląda tak:
Claude przeszukuje repozytorium, podąża za łańcuchami importów i wywołań i odpowiada, podając handlery endpointów, pipeline transformacji, relacje schematu i wzorce zapytań dashboardu, zamiast tego, byś spędził dzień na ręcznym czytaniu plików.
Claude Code doskonale radzi sobie tam, gdzie inne narzędzia zawodzą z masywnymi plikami:
Załóżmy, że masz przestarzały komponent React na 18 000 linii (taki, który narasta w każdej długo żyjącej aplikacji). Sztuczka polega na tym, by dać Claude precyzyjną kotwicę, zamiast prosić go o trzymanie całego pliku w głowie:
Update the handleSubmit function in src/components/CheckoutForm.tsx(around line 8500) so it debounces duplicate submissions. Show mejust that function before and after, not the whole file.Find every deprecated `useLegacyFormState` call in CheckoutForm.tsxand list the line numbers, so I can decide which to migrate first.First, walk me through the validation logic in this component.Then, in a follow-up, update only the error-handling branch.Zamiast samodzielnie grepować, pozwól Claude prześledzić strukturę za ciebie. To prompty, które wpisujesz do REPL-a Claude Code, a nie polecenia powłoki:
localStorage.”Dwa zapytania, które najbardziej się opłacają w dużej bazie kodu, to analiza wpływu zależności (przed ryzykowną zmianą) oraz przekrojowy audyt wydajności:
Strukturyzuj duże projekty refaktoryzacji efektywnie:
Początkowa analiza
"Analyze the current authentication system and identify areas for improvement"Stwórz plan
"Create a step-by-step plan to migrate from session-based to JWT authentication"Implementuj inkrementalnie
"Step 1: Create new JWT utility functions""Step 2: Update user model to support refresh tokens""Step 3: Modify login endpoint"Weryfikuj każdy krok
"Write tests for the JWT utilities""Verify backward compatibility"Strategia rozbijania zadań
Optymalizuj wydajność Claude’a z ukierunkowanym kontekstem:
# Mniej efektywne: Niejasna prośba"Optimize our application"
# Bardziej efektywne: Skupiona prośba"Optimize the database queries in the UserRepository class"
# Jeszcze lepiej: Konkretny kontekst"The getUsersWithOrders method in UserRepository has N+1 query issues. Optimize it using eager loading."Prawdziwym ograniczeniem jest budżet kontekstu, a nie liczba linii. Aktualne modele (Claude Fable 5, Opus 4.8 i Sonnet 4.6) mają okno 1 mln tokenów, ale każdy wciągnięty plik o nie konkuruje, a jakość spada, gdy wypełniasz je nieistotnym kodem. Z grubsza, jako zasada kciuka:
--add-dir, oprzyj się na hierarchicznych plikach CLAUDE.md i pracuj moduł po module.Uruchom równoległe instancje Claude Code, każdą zawężoną do jednego obszaru repozytorium. Uruchom każdą w osobnym terminalu z odpowiednim katalogiem roboczym:
# Terminal 1: Frontendclaude --add-dir ./frontend
# Terminal 2: API backenduclaude --add-dir ./backend
# Terminal 3: Migracje bazy danychclaude --add-dir ./database
# Terminal 4: Testyclaude --add-dir ./testsNastępnie steruj każdą sesją skupionym promptem, na przykład “Implement the new user dashboard” w instancji frontendowej i “Create REST endpoints for the dashboard data” w backendowej.
Korzyści z równoległych instancji:
Używaj systemu plików jako punktu przekazania między instancjami. Jedna generuje artefakty; pozostałe je konsumują:
shared/types/api.types.ts.”shared/types/api.types.ts.”shared/types/ with usage examples.”Wzorce współdzielonego workspace
project/├── .claude/│ ├── generated/ # Kod wygenerowany przez AI│ ├── templates/ # Implementacje referencyjne│ └── workspace/ # Współdzielone pliki robocze├── docs/│ └── ai-sessions/ # Dokumentacja sesjiBadaj wzorce zewnętrzne bez kopiowania ich źródeł do swojego repozytorium (co ciągnie za sobą bagaż licencyjny). Pozwól Claude streścić podejście, a potem zaprojektuj własne:
Strukturyzuj dokumentację dla dużych monorepo:
monorepo/├── CLAUDE.md # Globalne reguły i wzorce├── packages/│ ├── frontend/│ │ ├── CLAUDE.md # Specyficzne dla frontendu│ │ └── src/│ │ └── components/│ │ └── CLAUDE.md # Wytyczne komponentów│ ├── backend/│ │ ├── CLAUDE.md # Wzorce backendowe│ │ └── src/│ │ ├── services/│ │ │ └── CLAUDE.md # Wzorce serwisów│ │ └── models/│ │ └── CLAUDE.md # Reguły modeli danych│ └── shared/│ └── CLAUDE.md # Reguły współdzielonego koduPrzykład hierarchicznej dokumentacji:
# Monorepo Overview
## Architecture Principles- Microservices with shared libraries- Event-driven communication- TypeScript throughout
## Global Standards- Conventional commits- 100% test coverage for shared code- No circular dependencies# User Service
## Responsibilities- User authentication- Profile management- Permission handling
## Dependencies- Shared auth library- Database service- Event bus
## Patterns- Repository pattern for data access- JWT for authentication- Event sourcing for auditPomóż Claude zrozumieć projekt twojego systemu:
# Architecture Documentation
## System Overview```mermaidgraph TD A[API Gateway] --> B[User Service] A --> C[Product Service] A --> D[Order Service] B --> E[PostgreSQL] C --> F[MongoDB] D --> E D --> G[Redis Cache] B --> H[Event Bus] C --> H D --> H```
## Design Patterns1. **Repository Pattern**: All database access through repositories2. **CQRS**: Separate read/write models for complex domains3. **Event Sourcing**: Audit trail for critical operations4. **Circuit Breaker**: For external service calls5. **Saga Pattern**: For distributed transactions
## Communication Patterns- **Sync**: REST APIs with OpenAPI specs- **Async**: RabbitMQ for events- **Real-time**: WebSockets for live updates
## Data Flow1. Client → API Gateway (authentication)2. Gateway → Microservice (authorized request)3. Service → Database (data operation)4. Service → Event Bus (state change)5. Other Services → Event Bus (react to changes)Zadawaj zaawansowane pytania o relacje w kodzie:
# Dependency analysis"Show me all services that depend on the User model""What would break if I change the authenticate method signature?""Find circular dependencies in our import structure"
# Performance analysis"Identify all database queries in hot code paths""Find synchronous operations that could be async""Show me all uncached expensive computations"
# Security audit"Find all user input that isn't validated""Show me everywhere we construct dynamic SQL""Identify exposed sensitive data in API responses"
# Architecture validation"Verify all services follow our repository pattern""Find direct database access outside of repositories""Check if any frontend code imports backend modules"Zarządzaj użyciem tokenów w dużych projektach:
# 1. Często czyść/clear
# 2. Skupiaj rozmowy"Work only on the authentication module"
# 3. Używaj konkretnych referencji plików@auth/login.service.ts# Zamiast: "the login service file"
# 4. Kompresuj kontekst/compact
# 5. Usuń niepotrzebne pliki"Ignore test files for this task"Typical token usage by task:
- Simple bug fix: 2K-5K tokens- Feature implementation: 10K-20K tokens- Large refactoring: 50K-100K tokens- Architecture analysis: 20K-50K tokens
Cost optimization:- Use Claude Sonnet 4.6 for routine tasks- Reserve Claude Opus 4.8 for complex refactors and architecture analysis- Use Claude Fable 5 (/model fable) when velocity and quality matter most- Clear between unrelated tasks- Focus on specific modulesDokumentuj każdy główny moduł kompleksowo:
# Payment Module Documentation
## OverviewHandles all payment processing including credit cards,PayPal, and cryptocurrency payments.
## Key Files- `payment.service.ts` - Main service orchestrator- `processors/` - Payment processor implementations- `models/transaction.model.ts` - Transaction data model- `webhooks/` - Payment provider webhooks
## Critical Business Logic1. **Retry Logic**: 3 attempts with exponential backoff2. **Idempotency**: Use transaction_id to prevent duplicates3. **Audit Trail**: Every operation logged to audit_log table4. **Refunds**: Max 90 days, requires manager approval
## Integration Points- User Service: For customer data- Order Service: For order fulfillment- Notification Service: For payment receipts- Audit Service: For compliance logging
## Testing Requirements- Unit tests: Mock all external providers- Integration tests: Use sandbox environments- Load tests: 1000 TPS minimum- Security tests: PCI compliance required
## Common Issues1. Webhook timeouts - implement async processing2. Currency conversion - cache rates for 1 hour3. Failed payments - clear user communication4. Partial refunds - complex state managementPodchodź do dużej refaktoryzacji systematycznie:
Przeanalizuj aktualny stan
"Analyze the authentication system and create a refactoring plan"Stwórz sieć bezpieczeństwa
"Write comprehensive tests for current authentication behavior"Refaktoryzuj małymi krokami
"Step 1: Extract authentication logic into separate service""Step 2: Create interfaces for authentication providers""Step 3: Implement JWT provider""Step 4: Add OAuth providers"Utrzymuj kompatybilność wsteczną
"Create adapter layer for old authentication API"Strategia migracji
"Create migration plan for existing sessions"Reguły refaktoryzacji inkrementalnej
Używaj Claude do znajdowania wzorców i niespójności:
# Find inconsistent patterns"Find all different error handling patterns in our codebase""Show me all the different ways we're validating email addresses""Identify inconsistent naming conventions"
# Locate duplicate code"Find similar code patterns that could be refactored""Show me duplicate business logic across services"
# Architecture violations"Find all places where the presentation layer directly accesses the database""Show me services calling other services synchronously"
# Performance patterns"Find all N+1 query patterns""Locate all synchronous I/O in request handlers""Show me all uncached database queries"Przegląd bezpieczeństwa to jedno z najbardziej dźwigniowych zastosowań rozpoznawania wzorców w dużej bazie kodu. Jeden prompt potrafi wydobyć naraz każdą ryzykowną konstrukcję zapytania:
Taki przegląd zazwyczaj wydobywa garstkę odrębnych stylów budowania zapytań i kieruje cię prosto do tych, które wstrzykują niezaufane dane, zamiast tego, byś ręcznie audytował tysiące miejsc wywołań.
Opracuj systematyczne podejścia do zrozumienia dużych baz kodu:
# 1. High-level understanding"What does this project do? Explain the main purpose and architecture"
# 2. Identify entry points"Show me the main entry points for this application"
# 3. Trace critical paths"Trace the flow of a user login request"
# 4. Understand data model"Explain the core data models and their relationships"
# 5. Identify key patterns"What design patterns are used in this codebase?"# 1. Locate feature code"Where is the payment processing implemented?"
# 2. Understand dependencies"What does the payment system depend on?"
# 3. Find related tests"Show me all tests for payment processing"
# 4. Check documentation"Is there documentation for the payment system?"
# 5. Identify edge cases"What edge cases does the payment system handle?"# 1. Reproduce understanding"Explain how the user authentication flow works"
# 2. Locate problem area"Where might a login failure occur?"
# 3. Check recent changes"What changed recently in authentication?"
# 4. Find similar issues"Are there similar patterns that might have the same bug?"
# 5. Propose fixes"Suggest fixes for the authentication timeout issue"Lista kontrolna dużych baz kodu
/costKluczowe zasady sukcesu:
Duże bazy kodu zawodzą w konkretny, rozpoznawalny sposób. Oto, na co uważać i jak się z tego wycofać.
Przepełnienie okna kontekstu na gigantycznym pliku. Prosisz Claude o edycję pliku na 20 tys. linii, a on gubi wątek, edytuje niewłaściwy blok lub ucina go. Wyjście: przestań ładować cały plik. Zakotwicz zmianę do nazwy funkcji i zakresu linii albo najpierw poproś o docelowy obszar (“show me just handleSubmit”), a potem w kolejnym kroku edytuj ten wycinek.
Wyszukiwanie agentowe pomija kod referencjonowany dynamicznie. Wyszukiwanie znajduje statyczne importy, ale nie handlery podłączone przez klucze tekstowe, refleksję czy rejestr budowany w czasie wykonania, więc przegląd typu “znajdź każde miejsce wywołania” wraca niekompletny. Wyjście: nazwij pośrednictwo wprost (“we register routes by string in router.config.ts; trace those too”) i zweryfikuj krzyżowo dosłownym grepem, zanim zaufasz liście przy ryzykownej refaktoryzacji.
Równoległe instancje nadpisują współdzielony plik. Dwie sesje edytują shared/types/api.types.ts, a druga po cichu nadpisuje pierwszą. Wyjście: nadaj każdej instancji nienakładający się zakres katalogów, commituj (lub rób stash) między przekazaniami, aby system plików był jedynym źródłem prawdy, i nigdy nie pozwól dwóm instancjom posiadać tego samego pliku jednocześnie.
Dryf nieaktualnego CLAUDE.md. Plik CLAUDE.md wciąż opisuje stare uwierzytelnianie oparte na sesji po tym, jak przeszedłeś na JWT, więc Claude podąża za instrukcjami, które nie pasują już do rzeczywistości. Wyjście: traktuj CLAUDE.md jak kod, przeglądaj go w PR-ach i okresowo proś Claude o jego pogodzenie (“compare the auth section of this CLAUDE.md against the actual auth/ package and flag anything out of date”).
Repozytorium jest zbyt duże, by w ogóle je ogarnąć. Nawet zawężone prompty błądzą, bo sam pakiet jest plątaniną. Wyjście: nie proś o zmianę, najpierw poproś o mapę (“produce a dependency diagram of this package and identify the three highest-coupling modules”), a potem refaktoryzuj względem tej mapy moduł po module.
Mając w ręku strategie dla dużych baz kodu, kolejną dźwignią jest twoja codzienna pętla pracy. Przejdź do Optymalizacji przepływu pracy, aby przekuć te jednorazowe techniki w powtarzalne nawyki, a następnie zobacz Zarządzanie wydajnością i kosztami, aby utrzymać wydatki na tokeny pod kontrolą przy skali.