Eksploracja i analiza bazy kodu

Wyobraź sobie dołączenie do nowego zespołu i stanięcie przed bazą kodu o 100 000 linijkach z kryptycznymi nazwami zmiennych, niejasną architekturą i minimalną dokumentacją. To, co kiedyś zajmowało tygodnie bolesnej eksploracji, teraz zajmuje godziny z Claude Code. Ta lekcja przekształca cię w archeologa bazy kodu, odkrywającego ukryte wzorce i rozumiejącego złożone systemy z prędkością terminala.

Sztuka odkrywania bazy kodu

Scenariusz: Właśnie odziedziczyłeś starszą platformę e-commerce. Oryginalny zespół odszedł, dokumentacja jest skąpa, a musisz dodać nowego dostawcę płatności do piątku. Od czego w ogóle zacząć?

Twoje pierwsze pytania

Uruchom Claude Code w głównym katalogu projektu
Okno terminala
```
cd legacy-ecommerce-platform
claude
```

Zorientuj się w terenie

> Co robi ten projekt? Daj mi przegląd wysokopoziomowy

Zrozum architekturę

> Wyjaśnij strukturę folderów i główne wzorce architektoniczne używane

Znajdź punkty wejścia

> Gdzie jest główny punkt wejścia? Jak startuje aplikacja?

Mapuj krytyczne ścieżki

> Prześledzij przepływ użytkownika dokonującego zakupu od początku do końca

W ciągu minut Claude dostarcza:

Cel projektu i główne funkcje
Identyfikację stosu technologicznego
Wzorce architektoniczne (MVC, mikrousługi, itp.)
Kluczowe katalogi i ich odpowiedzialności
Diagramy przepływu danych
Zewnętrzne zależności i integracje

Wzorce nawigacji dla dużych baz kodu

Eksploracja szerokościowa

Zacznij szeroko, potem zagłębiaj się:

Wstępna rozpoznanie
Głębokie zagłębienie

> Daj mi kompleksowy przegląd tej bazy kodu, uwzględniając:
> - Główne technologie i frameworki
> - Strukturę i organizację projektu
> - Kluczowe domeny biznesowe
> - Integracje zewnętrzne
> - Podejście do testowania

Claude analizuje cały projekt i dostarcza ustrukturyzowany raport:

## Przegląd projektu: Starszy platform e-commerce

### Stos technologiczny
- Backend: Node.js z Express 4.x
- Frontend: React 16.x z Redux
- Baza danych: PostgreSQL 12, Redis dla cache
- Płatności: Integracje Stripe, PayPal
- Infrastruktura: Docker, wdrożenie AWS

### Architektura
- Monolit z modułami zorientowanymi na usługi
- RESTful API z autentykacją JWT
- Renderowanie po stronie serwera dla SEO
- Przetwarzanie zamówień sterowane zdarzeniami

### Kluczowe domeny
1. **Zarządzanie użytkownikami** (`/src/auth`, `/src/users`)
2. **Katalog produktów** (`/src/products`, `/src/inventory`)
3. **Przetwarzanie zamówień** (`/src/orders`, `/src/payments`)
4. **Realizacja** (`/src/shipping`, `/src/warehouses`)

### Znalezione krytyczne problemy
- Przestarzałe zależności (luki bezpieczeństwa)
- Niespójna obsługa błędów
- Brakujące pokrycie testami w module płatności

Po otrzymaniu przeglądu, zagłęb się w konkretne obszary:

> Skup się na module przetwarzania płatności. Pokaż mi:
> - Wszystkie integracje dostawców płatności
> - Jak dane płatności przepływają przez system
> - Środki bezpieczeństwa w miejscu
> - Ostatnie zmiany lub commity związane z płatnościami

Claude dostarcza szczegółową analizę:

Podział plik po pliku modułu płatności
Diagramy sekwencji dla przepływu płatności
Wyniki audytu bezpieczeństwa
Punkty integracji i zależności

Wzorzec myśliwego

Podczas wyszukiwania konkretnej funkcjonalności:

> Muszę znaleźć gdzie są walidowane kody rabatowe.
> Wyszukaj logikę rabatów, kuponów, kodów promocyjnych

Claude używa swoich zdolności wyszukiwania agentowego do:

Znalezienia wszystkich plików zawierających logikę rabatów
Prześledzenia ścieżki wykonania
Identyfikacji przypadków brzegowych i reguł biznesowych
Pokazania powiązanych schematów bazy danych
Podkreślenia potencjalnych problemów

Zrozumienie zależności kodu

Mapowanie zależności

Scenariusz: Musisz uaktualnić krytyczną bibliotekę, ale nie jesteś pewien co się zepsuje.

> Przeanalizuj wszystkie zależności modułu autentykacji.
> Pokaż mi co od niego zależy i od czego on zależy

Claude generuje kompleksowy graf zależności:

Zależności bezpośrednie

bcrypt - Hashowanie haseł
jsonwebtoken - Generowanie JWT
passport - Strategie autentykacji
redis - Przechowywanie sesji

Zależni wewnętrzni

/api/routes/* - Wszystkie endpointy API
/middleware/auth.js - Middleware auth
/services/user.js - Usługa użytkownika
/workers/session-cleanup.js - Zadania w tle

Zależności bazy danych

Tabela users - Dane użytkowników
Tabela sessions - Aktywne sesje
Tabela auth_logs - Audyt bezpieczeństwa
Tabela permissions - Dostęp oparty na rolach

Integracje zewnętrzne

Dostawcy OAuth (Google, GitHub)
Usługa email dla resetowania haseł
Usługa SMS dla 2FA
Usługa logowania audytu

Analiza wpływu

Przed wprowadzeniem zmian:

> Jeśli zmienię autentykację użytkowników na używanie tylko OAuth,
> które części bazy kodu będą dotknięte?

Claude dostarcza:

Lista dotkniętych plików i funkcji
Wymagane migracje bazy danych
Zmiany kontraktów API
Komponenty frontend wymagające aktualizacji
Zestawy testów wymagające modyfikacji

Rozpoznawanie wzorców i antywzorców

Identyfikacja zapachów kodu

> Przeanalizuj tę bazę kodu pod kątem popularnych antywzorców i zapachów kodu.
> Skup się na problemach z maintainability

Analiza Claude’a może ujawnić:

Znalezione antywzorce
Sugestie refaktoryzacji

// 1. God Object - OrderController robi za dużo
class OrderController {
  // 2000+ linii obsługujących:
  // - Tworzenie zamówień
  // - Przetwarzanie płatności
  // - Zarządzanie inwentarzem
  // - Powiadomienia email
  // - Śledzenie analityczne
}

// 2. Copy-Paste Programming
// Znaleziono 15 instancji niemal identycznej obsługi błędów

// 3. Magiczne liczby
if (order.total > 1000) { // Co reprezentuje 1000?
  applyDiscount(0.1); // Dlaczego 10%?
}

// 4. Callback Hell
getUserData((user) => {
  getOrderHistory(user.id, (orders) => {
    calculateLoyaltyPoints(orders, (points) => {
      updateUserProfile(user.id, points, (result) => {
        // ... głębsze zagnieżdżenie
      });
    });
  });
});

// 1. Podziel God Object na usługi zorientowane
class OrderService { /* Logika zamówień */ }
class PaymentService { /* Logika płatności */ }
class NotificationService { /* Powiadomienia */ }

// 2. Wyodrębnij wspólną obsługę błędów
const handleError = createErrorHandler({
  log: true,
  notify: true,
  fallback: 'default'
});

// 3. Użyj nazwanych stałych
const PREMIUM_ORDER_THRESHOLD = 1000;
const PREMIUM_DISCOUNT_RATE = 0.1;

// 4. Użyj async/await
const user = await getUserData();
const orders = await getOrderHistory(user.id);
const points = await calculateLoyaltyPoints(orders);
const result = await updateUserProfile(user.id, points);

Wykrywanie wąskich gardeł wydajności

Analiza zapytań do bazy danych

> Zidentyfikuj potencjalne wąskie gardła wydajności w zapytaniach do bazy danych

Claude bada twoją bazę kodu i znajduje:

// PROBLEM 1: Problem zapytań N+1
const orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [userId]);
for (const order of orders) {
  // To uruchamia zapytanie dla KAŻDEGO zamówienia!
  order.items = await db.query('SELECT * FROM order_items WHERE order_id = ?', [order.id]);
}

// SUGESTIA CLAUDE'A: Użyj pojedynczego zapytania join
const ordersWithItems = await db.query(`
  SELECT o.*,
         json_agg(oi.*) as items
  FROM orders o
  LEFT JOIN order_items oi ON o.id = oi.order_id
  WHERE o.user_id = ?
  GROUP BY o.id
`, [userId]);

// PROBLEM 2: Brakujące indeksy
// Znaleziono zapytania filtrujące po nieindeksowanych kolumnach:
await db.query('SELECT * FROM products WHERE sku = ?'); // 'sku' nie indeksowane
await db.query('SELECT * FROM users WHERE email = ?');   // 'email' nie indeksowane

// PROBLEM 3: Ładowanie niepotrzebnych danych
const users = await db.query('SELECT * FROM users'); // Ładowanie wszystkich kolumn
// Ale używa tylko: user.id, user.name, user.email

Wykrywanie wycieków pamięci

> Sprawdź potencjalne wycieki pamięci lub nieefektywne użycie pamięci

Claude identyfikuje problematyczne wzorce:

// PROBLEM: Event listenery nie czyszczone
class OrderMonitor {
  constructor() {
    // Listenery dodane ale nigdy nie usunięte
    eventBus.on('order.created', this.handleOrder);
    eventBus.on('order.updated', this.handleOrder);
  }
  // Brakuje metody cleanup
}

// PROBLEM: Nieograniczony wzrost cache
const cache = {};
function cacheResult(key, value) {
  cache[key] = value; // Cache rośnie na zawsze!
}

// PROBLEM: Duże tablice trzymane w pamięci
let allOrdersEver = []; // Rośnie w nieskończoność

Analiza wielojęzykowa

Scenariusz: Twoja platforma używa Node.js dla API, Python do przetwarzania danych i Go dla usług czasu rzeczywistego.

Nawigacja wielojęzykowa

> Ten projekt używa wielu języków. Daj mi przegląd:
> - Który język obsługuje jaką funkcjonalność
> - Jak komunikują się usługi
> - Przepływ danych między granicami różnych języków

Claude mapuje architekturę wielojęzykową:

Przegląd architektury:

Node.js API (./api/)
├── Endpointy REST
├── Serwer GraphQL
└── Handlery WebSocket
    ↓
    Redis Queue / RabbitMQ
    ↓
Python Workers (./workers/)
├── Pipeline danych
├── Predykcje ML
└── Generowanie raportów
    ↓
    PostgreSQL / S3
    ↓
Usługi Go (./services/)
├── Powiadomienia czasu rzeczywistego
├── Sygnalizacja WebRTC
└── Handel wysokiej częstotliwości

Komunikacja:
- HTTP/REST między frontendem a Node.js
- Kolejki wiadomości między Node.js a Python
- gRPC między usługami Python i Go
- Współdzielony PostgreSQL dla trwałych danych
- Redis dla cache i pub/sub

Tworzenie żywej dokumentacji

Automatycznie generowana dokumentacja

> Utwórz kompleksową dokumentację dla modułu przetwarzania zamówień.
> Uwzględnij decyzje architektoniczne, diagramy przepływu i dokumentację API

Claude generuje:

Dokument architektury

# Moduł przetwarzania zamówień

## Przegląd
Moduł przetwarzania zamówień obsługuje kompletny cykl życia zamówień klientów,
od koszyka do dostawy.

## Decyzje architektoniczne

### Projekt sterowany zdarzeniami
**Decyzja**: Użycie architektury sterowanej zdarzeniami dla zmian stanu zamówień
**Uzasadnienie**:
- Rozdziela przetwarzanie zamówień od innych systemów
- Umożliwia powiadomienia w czasie rzeczywistym
- Wspiera spójność ostateczną
- Pozwala na łatwe dodawanie nowych zdarzeń zamówień

### Wzorzec maszyny stanów
**Decyzja**: Implementacja zamówień jako skończona maszyna stanów
**Stany**: oczekujące → potwierdzone → przetwarzane → wysłane → dostarczone
**Korzyści**:
- Jasne przejścia stanów
- Zapobiega nieprawidłowym zmianom stanu
- Łatwiejsze testowanie i debugowanie

## Diagram komponentów
```mermaid
graph TD
    A[Order API] --> B[Order Service]
    B --> C[State Machine]
    B --> D[Event Publisher]
    D --> E[Notification Service]
    D --> F[Inventory Service]
    D --> G[Payment Service]
    C --> H[(Order Database)]

Endpointy API

POST /orders - Tworzenie nowego zamówienia
GET /orders/:id - Pobieranie szczegółów zamówienia
PATCH /orders/:id/status - Aktualizacja statusu zamówienia
POST /orders/:id/cancel - Anulowanie zamówienia

</TabItem>
<TabItem label="Diagram przepływu">
```mermaid
sequenceDiagram
    participant C as Customer
    participant API as Order API
    participant OS as Order Service
    participant PS as Payment Service
    participant IS as Inventory Service
    participant NS as Notification Service

    C->>API: Create Order
    API->>OS: Process Order
    OS->>PS: Charge Payment
    PS-->>OS: Payment Result

    alt Payment Success
        OS->>IS: Reserve Inventory
        IS-->>OS: Inventory Reserved
        OS->>NS: Send Confirmation
        OS-->>API: Order Confirmed
        API-->>C: Success Response
    else Payment Failed
        OS->>NS: Send Failure Notice
        OS-->>API: Order Failed
        API-->>C: Error Response
    end

Ciągła dokumentacja

Skonfiguruj Claude’a do utrzymywania dokumentacji:

> Utwórz plik CLAUDE.md, który zawiera niezbędną wiedzę
> o tej bazie kodu dla przyszłych developerów

Claude generuje kompleksowy CLAUDE.md:

# Baza wiedzy platformy e-commerce

## Szybki start
- `npm install` - Instalacja zależności
- `docker-compose up` - Start wszystkich usług
- `npm run dev` - Start serwera developmentu
- `npm test` - Uruchomienie zestawu testów

## Przegląd architektury
Monolityczna aplikacja Node.js z:
- API Express.js
- Frontend React
- Baza danych PostgreSQL
- Cache Redis
- Wdrożenie Docker

## Kluczowa logika biznesowa

### Przetwarzanie zamówień
Zamówienia podążają za wzorcem maszyny stanów:
- Klient dodaje przedmioty do koszyka
- Checkout waliduje inwentarz
- Płatność przetwarzana przez Stripe/PayPal
- Zamówienie potwierdzone i inwentarz zarezerwowany
- Realizacja wyzwolona
- Aktualizacje wysyłki przez webhooks

### Silnik cenowy
- Ceny bazowe w tabeli produktów
- Rabaty stosowane przez silnik reguł
- Podatek obliczany na podstawie adresu wysyłki
- Konwersja walut przez usługę kursów wymiany

## Popularne zadania

### Dodawanie dostawcy płatności
1. Zaimplementuj interfejs dostawcy w `/src/payments/providers/`
2. Dodaj konfigurację do `/config/payments.js`
3. Zaktualizuj PaymentService aby uwzględnił nowego dostawcę
4. Dodaj handler webhook specyficzny dla dostawcy
5. Zaktualizuj opcje płatności w frontendzie

### Debugowanie problemów z zamówieniami
1. Sprawdź stan zamówienia w bazie danych
2. Przejrzyj tabelę order_events dla historii
3. Sprawdź dashboard dostawcy płatności
4. Przejrzyj logi: `docker logs ecommerce-api`

## Znane problemy
- Wyciek pamięci w generowaniu raportów (obejście: restart workera codziennie)
- Race condition w rezerwacji inwentarza (użyj blokad bazy danych)
- Wolne wyszukiwanie produktów (potrzebna integracja Elasticsearch)

## Testowanie
- Testy jednostkowe: `npm run test:unit`
- Testy integracyjne: `npm run test:integration`
- Testy E2E: `npm run test:e2e`
- Testy obciążeniowe: `npm run test:load`

## Wdrożenie
- Staging: Automatyczne przy merge do develop
- Produkcja: Wymagane ręczne zatwierdzenie
- Rollback: `npm run deploy:rollback`

Skanowanie luk bezpieczeństwa

Audyt bezpieczeństwa

> Przeprowadź audyt bezpieczeństwa tej bazy kodu. Szukaj:
> - Luk SQL injection
> - Możliwości XSS
> - Omijania autentykacji
> - Eksponowania wrażliwych danych
> - Przestarzałych zależności ze znanymi lukami

Analiza bezpieczeństwa Claude’a:

Dla każdego problemu Claude dostarcza:

Dokładną lokalizację w kodzie
Ocenę ważności
Proof of concept
Kroki naprawcze
Strategie zapobiegania

Najlepsze praktyki analizy bazy kodu

1. Zacznij od pytań, nie założeń

Zamiast losowego nurkowania w kod:

> Jakie są najważniejsze części tej bazy kodu do zrozumienia najpierw?

2. Używaj stopniowego odkrywania

Zacznij szeroko, potem zawęź:

Ogólna architektura
Kluczowe podsystemy
Konkretne moduły
Poszczególne funkcje

3. Weryfikuj zrozumienie

> Na podstawie mojej analizy, tak myślę że działa przepływ płatności: [opis].
> Czy to jest prawidłowe? Co mi umyka?

4. Dokumentuj podczas eksploracji

> Utwórz diagram pokazujący jak te komponenty współdziałają

5. Szukaj wzorców

> Jakich wzorców kodowania i konwencji używa ten zespół?

Analiza wielu repozytoriów

Scenariusz: System twojej firmy rozciąga się na 12 repozytoriów.

Nawigacja między repozytoriami

# Dodaj wiele katalogów do kontekstu Claude'a
claude --add-dir ../user-service ../payment-service ../notification-service

Następnie:

> Jak te trzy usługi komunikują się? Prześledzij przepływ rejestracji użytkownika
> przez wszystkie trzy repozytoria

Claude dostarcza:

Diagramy interakcji usług
Kontrakty API między usługami
Współdzielone modele danych
Przepływy kolejek wiadomości
Wspólne biblioteki i zależności

Powiązane lekcje

Przewodnik refaktoryzacji Przekształć starszy kod z pewnością używając możliwości refaktoryzacji Claude'a

Przepływy debugowania Opanuj złożone scenariusze debugowania z inteligentnym dochodzeniem

Generowanie dokumentacji Twórz i utrzymuj kompleksową dokumentację automatycznie

Następne kroki

Nauczyłeś się nawigować i rozumieć złożone bazy kodu z Claude Code. Ta umiejętność jest fundamentalna - czy dołączasz do nowego zespołu, dziedziczysz projekt, czy próbujesz optymalizować istniejące systemy.

Pamiętaj: Claude Code to nie tylko narzędzie wyszukiwania. To twój inteligentny przewodnik przez labirynt kodu, pomagający zrozumieć nie tylko co kod robi, ale dlaczego został napisany w taki sposób i jak wszystko się ze sobą łączy. Użyj tych technik, aby stać się produktywnym w nowych bazach kodu w godziny zamiast tygodni.