---
name: codebase-archaeology
title: "Archeologia Codebase'u"
description: "Systematyczna metoda szybkiego zrozumienia nieznanego codebase'u. Zamiast czytać kod od góry do dołu, śledź przepływ danych: punkty wejścia → routing → logika biznesowa → warstwa danych → integracje zewnętrzne. Tworzy mapę architektury, listę kluczowych abstrakcji i przewodnik „gdzie szukać\" w mniej niż 30 minut. Działa dla dowolnego stacku."
category: coding
tags:
  - eksploracja
  - onboarding
  - architektura
  - zrozumienie
  - dokumentacja
source: https://madejski.ai/pl/promptoteka/codebase-archaeology
locale: pl
license: MIT
---

# 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?

```bash
# 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ę:

```bash
# 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:

```markdown
## 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)