Archeologia Codebase'u

Problem

Wrzucono cię do nieznanego codebase'u. Czytanie każdego pliku jest niemożliwe. Musisz zrozumieć architekturę, kluczowe wzorce i gdzie wprowadzać zmiany — szybko.

Metoda: Śledź dane

Nie czytaj kodu od góry do dołu. Śledź, jak dane przepływają przez system:

Warstwa 1: Punkty wejścia (5 min)

Gdzie świat zewnętrzny dotyka tego systemu?

# Znajdź główne punkty wejścia
- package.json scripts (start, dev, build)
- Dockerfile / docker-compose.yml
- Definicje route'ów (app router, express routes, handlery API)
- Listenery eventów / konsumenty kolejek
- Cron joby / zadania zaplanowane

Zapytaj: Co wyzwala ten system do działania?

Warstwa 2: Routing i middleware (5 min)

Jak żądania trafiają do logiki biznesowej?

- Middleware auth (kto ma dostęp do czego)
- Warstwa walidacji (jakie dane wejściowe są akceptowane)
- Mapowanie Route → Controller/Handler
- Granice obsługi błędów

Zapytaj: Co się dzieje między „żądanie przychodzi" a „logika biznesowa się uruchamia"?

Warstwa 3: Logika biznesowa (10 min)

Gdzie podejmowane są ważne decyzje?

- Warstwa serwisów / use case'y / logika domenowa
- Kluczowe modele domenowe i ich relacje
- Maszyny stanów / definicje workflow'ów
- Reguły biznesowe i walidacje

Zapytaj: Jakie są 3-5 najważniejszych konceptów w tej domenie?

Warstwa 4: Warstwa danych (5 min)

Jak stan jest persystowany?

- Schema bazy danych / migracje
- Modele ORM / repozytoria
- Warstwy cache
- Przechowywanie plików

Zapytaj: Co jest źródłem prawdy? Gdzie żyją ważne dane?

Warstwa 5: Integracje zewnętrzne (5 min)

Z jakimi innymi systemami to się komunikuje?

- Klienty API / SDK
- Kolejki wiadomości / event busy
- Serwisy trzecie (płatności, email, auth)
- Zewnętrzne połączenia bazodanowe

Zapytaj: Co się zepsuje, jeśli zewnętrzny system X padnie?

Komendy archeologiczne

Uruchom te, żeby szybko zbudować mentalną mapę:

# Przegląd struktury projektu
find . -type f -name "*.ts" | head -50
ls -la src/

# Zależności — jakie biblioteki mają znaczenie
cat package.json | jq '.dependencies'

# Schema bazy — jakie dane istnieją
find . -name "*.migration.*" -o -name "schema.*"

# Route'y — jak wygląda powierzchnia API
grep -r "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts"

# Środowisko — jakiej konfiguracji to potrzebuje
cat .env.example

# Testy — co jest faktycznie testowane (ujawnia co jest ważne)
find . -name "*.test.*" -o -name "*.spec.*"

# Git log — co się ostatnio zmieniło (ujawnia aktywne obszary)
git log --oneline -20
git log --oneline --since="2 weeks ago" -- src/

Wynik: Mapa architektury

Po archeologii stwórz:

## Mapa architektury: {nazwa projektu}

### Stack
- Runtime: {Node 22 / Python 3.12 / ...}
- Framework: {Next.js / Express / Django / ...}
- Baza danych: {PostgreSQL / MongoDB / ...}
- Kluczowe biblioteki: {top 5 zależności kształtujących architekturę}

### Punkty wejścia
- {Web: Next.js app router pod /app}
- {API: REST pod /api, {N} endpointów}
- {Background: {opis kolejek/cronów}}

### Model domenowy (top 5 konceptów)
1. {User} — {co reprezentuje, kluczowe relacje}
2. {Order} — ...

### Kluczowe wzorce
- {Repository pattern dla dostępu do danych}
- {Warstwa serwisów dla logiki biznesowej}
- {Łańcuch middleware dla auth/walidacji}

### Gdzie szukać
- Żeby dodać nowy endpoint API: {ścieżka}
- Żeby zmienić logikę biznesową X: {ścieżka}
- Żeby zmodyfikować schema bazy: {ścieżka}
- Żeby dodać nowy background job: {ścieżka}

### Pułapki
- {Rzeczy nieoczywiste ze struktury kodu}
- {Ukryte konwencje zespołu}
- {Znany dług techniczny lub kruche obszary}

Antywzorce

• Czytanie każdego pliku (utoniesz zanim zrozumiesz)
• Zaczynanie od testów (testy mówią co, ale nie dlaczego ani jak to pasuje razem)
• Pytanie „co robi ten codebase" bez zawężenia pytania
• Ignorowanie historii git (ostatnie commity ujawniają aktywne obszary)
• Pomijanie .env.example (konfiguracja mówi, od czego system zależy)