Jak zrozumieć nieznany codebase z Claude Code

Poziom 4 Poradnik Zaktualizowano 2026-10-12

Claude Code mapuje nieznany codebase z terminala w sesji tylko do odczytu, w trybie planowania: najpierw przegląd z lotu ptaka, potem prześledzenie jednego przepływu, który zmiana obejmuje, a równolegle subagenci, którzy trzymają zawartość plików poza głównym kontekstem. Mapa jest wiarygodna dopiero wtedy, gdy jej cytowania plik:linia przejdą skrypt, a główne twierdzenie przejdzie test.

Dołączyłeś do zespołu w poniedziałek. Repozytorium ma siedem lat historii, architekt, który zaprojektował obsługę zamówień, odszedł rok temu, a README opisuje kolejkę, której kod już nie używa. Twój pierwszy ticket dotyczy zwrotów i nikt nie potrafi powiedzieć, gdzie naprawdę zapisywany jest stan zwrotu. Ta strona jest dla takiego developera oraz dla tech leada, który chce, żeby każda nowa osoba doszła do pierwszej bezpiecznej zmiany bez tygodnia chodzenia za kimś krok w krok.

Co daje mapowanie codebase’u z Claude Code

Konfigurację sesji tylko do odczytu, w której Claude nie zmieni plików podczas eksploracji, z ostrzejszym wariantem dla kodu, któremu nie ufasz.
Sześć promptów do skopiowania: prześledzenie przepływu, odkrywanie konwencji, archeologia w historii git, równoległe zadania dla subagentów, adwersarialna weryfikacja mapy i aktualizacja CLAUDE.md.
Krótki skrypt powłoki, który sprawdza, czy każde cytowanie ścieżka:linia w mapie istnieje, więc weryfikujesz mapę bez ponownego czytania kodu.
Test charakteryzujący, który zamienia zdanie „tak działają zwroty” w twierdzenie sprawdzane przez CI przy każdym commicie.
ARCHITECTURE.md i aktualizację CLAUDE.md, od których zacznie następna osoba i następna sesja.

Uruchom sesję eksploracji tylko do odczytu

Od Claude Code v2.1.283 (oba kanały wydań na 2026-10-12) sesje interaktywne startują w trybie auto, w którym klasyfikator zatwierdza akcje, w tym edycje. Wyjątkiem są sesje, w których plik ustawień ustawia disableAutoMode, oraz sesje na modelu nieobsługiwanym przez tryb auto: te startują w trybie Manual. Eksploracja wymaga czegoś odwrotnego, więc tryb planowania wybierz świadomie. W trybie planowania Claude czyta pliki i, tam gdzie tryb auto jest dostępny, uruchamia polecenia zatwierdzone przez klasyfikator. Niczego nie zmieni, dopóki nie zatwierdzisz planu.

Uruchom to w terminalu w katalogu głównym repozytorium:

claude --permission-mode plan

W sesji, która już działa, naciskaj Shift+Tab, aż wskaźnik pokaże tryb planowania, albo wpisz /plan.

Tryb planowania to zabezpieczenie w procesie pracy, a nie granica izolacji. Dla repozytorium, któremu nie ufasz, na przykład kodu od dostawcy albo z przejętej firmy, dodaj --restricted. W Claude Code 2.1.283 ta flaga usuwa Bash i pozostałe narzędzia uruchamiające kod oraz WebFetch, ignoruje pliki ustawień użytkownika, projektu i lokalne, a narzędzia plikowe ogranicza do katalogu roboczego. Serwery MCP nadal się wczytują, chyba że dodasz --strict-mcp-config (sprawdzone w claude --help 2.1.283), a plik .mcp.json w niezaufanym repozytorium może uruchomić taki serwer, więc dodaj obie flagi:

claude --restricted --strict-mcp-config --permission-mode plan

Plik CLAUDE.md lub AGENTS.md z repozytorium nadal jest wczytywany jako instrukcje; traktuj go jako niezaufane dane wejściowe albo dodaj --safe-mode, która według claude --help 2.1.283 wyłącza CLAUDE.md, skille, hooki, serwery MCP i własnych agentów.

Koszt tej decyzji: bez Basha Claude nie uruchomi git log ani git blame, więc krok z historią git zrób później, w zwykłej sesji w trybie planowania, gdy już przeczytasz, co robią skrypty budowania i hooki. Mocniejszą izolację daje kontener albo sandboxowany Bash.

Zmapuj codebase od ogółu do szczegółu

Kolejność ma znaczenie. Każdy krok zawęża pytanie, więc Claude czyta coraz mniej plików, a odpowiedzi stają się coraz konkretniejsze.

Zacznij od przeglądu. Claude czyta pliki manifestu, drzewo katalogów, konfigurację i punkty wejścia, a potem zwraca krótkie podsumowanie. To podsumowanie jest indeksem, a nie zrozumieniem.

Give me a map of this repository for a new engineer. Cover: what the
system does, the tech stack with versions from the lockfile, the
entry points (HTTP server, workers, CLIs, cron jobs), and the top-level
directories with one line each. Cite the file that proves every
claim as path:line. Mark anything you inferred rather than read as
(inferred). Keep it under 60 lines.

Nazwij podsystemy i ich zależności. Zapytaj o moduły i kierunek zależności. Kierunek mówi, co możesz bezpiecznie zmienić: moduł, którego nikt nie importuje, jest tani w modyfikacji.

List the main subsystems. For each: purpose in one sentence, the
directories it owns, which subsystems it imports, and which import
it. Finish with the three most-imported modules, because those are
where a change has the widest blast radius.

Prześledź jeden przepływ, który musisz zmienić. Ogranicz go do swojego ticketu. Jedna ścieżka przez kod jest warta więcej niż wycieczka po wszystkich modułach.

Trace a refund request from the HTTP handler to the database write
and every side effect after it. For each hop give: the function name,
path:line, what it validates or transforms, and the shape of the data
leaving it. Then list every place refund state is written, including
background jobs, webhooks and scripts. End with the open questions you
could not answer from the code. Do not guess: if a call goes through
dependency injection or a dynamic dispatch you cannot resolve, say so.

Poznaj konwencje, zanim napiszesz kod. Konwencje to niepisane zasady, za które reviewer odrzuci twój pierwszy PR.

Read at least 10 source files from different subsystems plus their
tests. Report the conventions actually in use: naming, error handling,
logging, test layout and mocking style, import order, and API response
shape. Give one path:line example for each. Then list the places where
two conventions compete, and say which one is newer according to git
log, because that is the one I should follow.

Zapytaj git, skąd się wziął dziwny kod. Opisy commitów i blame wyjaśniają decyzje, których sam kod nie wyjaśni, na przykład pozornie zbędną pętlę ponowień albo komentarz „nie zmieniać”.

In src/payments/refunds.ts there is a comment "DO NOT REORDER" above
the ledger writes. Use git log -L and git blame to find the commit that
introduced that ordering and every later commit that touched it. Quote
the commit messages, name linked issue or PR numbers if the messages
contain them, and explain what breaks if the order changes. If the
history does not say, tell me that instead of inferring a reason.

Utrzymaj czysty główny kontekst dzięki subagentom

Każdy plik przeczytany w głównej sesji zostaje w oknie kontekstu. Szerokie śledztwo potrafi wypchnąć z niego rozmowę, na której ci zależy, a jakość odpowiedzi spada, gdy okno się zapełnia. Rozwiązaniem są subagenci: każdy eksploruje we własnym kontekście i zwraca tylko podsumowanie. Claude Code ma wbudowanych subagentów Explore, Plan i general-purpose, a subagenci domyślnie działają w tle, więc możesz pracować dalej, gdy oni czytają.

Use the Explore subagent to run three investigations in parallel. Each
one returns at most 30 lines with path:line citations, and marks
anything inferred as (inferred).

1. Payments: trace checkout to payment confirmation, including retries,
   idempotency keys and what happens when the provider times out.
2. Caching: find every cache layer (Redis, in-process, HTTP headers),
   what each stores, its TTL, and how it is invalidated.
3. Background jobs: find the queue, list every job type, and document
   retry limits and where failed jobs end up.

When all three finish, merge them into one summary and list any
contradiction between them.

Poleceniem /context sprawdzisz, jak pełne jest główne okno. Uruchom /compact, gdy długa eksploracja spełniła swoje zadanie, albo /clear, gdy przechodzisz do niezwiązanego obszaru. Jeśli co tydzień definiujesz to samo śledztwo, zapisz je jako własnego subagenta w .claude/agents/; zobacz stronę o tworzeniu własnych subagentów. Mechanikę budżetu kontekstu opisuje strona o oknach kontekstu i limitach tokenów.

W bardzo dużym repozytorium najdroższą częścią eksploracji są wyszukiwanie tekstu i czytanie plików. Serwer MCP do analizy kodu odpowiada na pytanie „kto wywołuje tę funkcję” przez serwer języka (language server). Jedną z opcji jest Serena, serwer społecznościowy od Oraios (PyPI serena-agent 1.7.0, sprawdzone 2026-09-26). Jej autorzy odradzają instalację z marketplace’ów MCP i pluginów, bo tamtejsze wpisy mają nieaktualne polecenia, więc instaluj ją ze źródła:

uv tool install -p 3.13 serena-agent
serena init
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

Porównanie z alternatywami znajdziesz na stronie o serwerach MCP do analizy kodu.

Udowodnij mapę, zanim jej zaufasz

Płynne podsumowanie to nie to samo co poprawne. Agent może zacytować plik, którego nazwę zmieniono, opisać middleware zarejestrowane, ale wyłączone, albo prześlizgnąć się nad dynamicznym wywołaniem, którego nie rozwiązał. Nie naprawisz tego, czytając sam każdy plik. Naprawisz to, gdy każde twierdzenie da się sprawdzić, a sprawdzanie zostawisz maszynom. Wykonaj trzy kontrole w kolejności od najtańszej do najmocniejszej.

Sprawdź mechanicznie każde cytowanie. Powyższe prompty wymagają path:line przy każdym twierdzeniu. Zapisz mapę w ARCHITECTURE.md, a potem uruchom to w terminalu w katalogu głównym repozytorium. Skrypt wypisze każde cytowanie, którego plik nie istnieje albo którego numer linii wykracza poza koniec pliku:
Okno terminala
```
grep -oE '[A-Za-z0-9_./-]+\.[A-Za-z0-9]+:[0-9]+' ARCHITECTURE.md \
  | sort -u | while IFS=: read -r f l; do
    if [ ! -f "$f" ]; then echo "missing file: $f"
    elif [ "$l" -gt "$(wc -l < "$f")" ]; then echo "line out of range: $f:$l"
    fi
  done
```
Wzorzec dopasowuje ścieżka:linia dla każdej ścieżki, która ma rozszerzenie pliku, więc sprawdza też cytowania z plików Java, Rust, SQL czy YAML. Cytowań plików bez rozszerzenia, takich jak Dockerfile czy Makefile, skrypt nie sprawdza, a host:port w mapie pojawi się jako brakujący plik, który możesz zignorować. Pusty wynik oznacza, że każde cytowanie wskazuje prawdziwy kod. Twierdzeń bez cytowania skrypt w ogóle nie sprawdza, i to kolejny powód, dla którego prompty wymagają cytowania przy każdym twierdzeniu. Skrypt nie dowodzi, że twierdzenia są trafne, tylko że są zakotwiczone w czymś, co możesz otworzyć.

Zaatakuj mapę ze świeżym kontekstem. Drugie przejście, które nie pisało mapy, nie ma interesu w jej bronieniu. Zacznij nową sesję przez /clear albo zleć przegląd subagentowi, żeby recenzent nie odziedziczył założeń pierwszego przejścia.

Read ARCHITECTURE.md. You did not write it and you should assume it
contains mistakes. For each claim: open the cited path:line and mark it
CONFIRMED, WRONG (quote the code that contradicts it) or UNSUPPORTED
(the citation does not show it). Pay special attention to anything
marked (inferred), to dependency-injection wiring, feature flags and
code registered but never called. Output a table, then the five
claims a new engineer is most likely to be hurt by if they are wrong.

Zamień główne twierdzenie w test. Wybierz jedno twierdzenie, od którego zależy twój ticket, na przykład „zwrot większy niż pobrana kwota jest odrzucany przed jakimkolwiek zapisem do księgi”. Wyjdź z trybu planowania, poproś Claude o test charakteryzujący, który sprawdza dokładnie to obecne zachowanie, i uruchom go. Zielony test to dowód, że mapa zgadza się z kodem. Czerwony to najcenniejsze odkrycie tygodnia, a po zmergowaniu CI sprawdza to twierdzenie przy każdym commicie. Technikę opisuje dokładnie strona o testach charakteryzujących.

Kto zatwierdza. Developer zatwierdza mapę obszaru, który zaraz zmieni, gdy wszystkie trzy kontrole przejdą. Zmiana w ARCHITECTURE.md albo CLAUDE.md idzie zwykłym pull requestem, a tech lead lub właściciel kodu tego obszaru przegląda diff dokumentu, czyli kilkadziesiąt linii, a nie kod, który za nim stoi. Na tym polega przejście od czytania kodu do przeglądania dowodów, opisane na stronie dowody zamiast diffów.

Zapisz to, czego się dowiedziałeś, dla następnej sesji

Eksploracja, której nikt nie zapisał, zostanie powtórzona przez następną osobę i przez twoją własną następną sesję. Prowadź dwa pliki dla dwóch różnych czytelników.

Plik	Czytelnik	Co do niego trafia
`ARCHITECTURE.md`	Ludzie	Sprawdzona mapa: podsystemy, prześledzone przepływy, kierunek zależności, otwarte pytania.
`CLAUDE.md` (lub `AGENTS.md`)	Każda przyszła sesja agenta	Polecenia budowania i testów, konwencje oraz pułapki, w jak najmniejszej liczbie linii.

Update CLAUDE.md with only what a future session needs and cannot
cheaply rediscover: the exact build, test and lint commands, the
conventions you confirmed (one line each), and the traps, such as code
that looks dead but is called through the job registry. Do not restate
what is already in ARCHITECTURE.md; link to it. Remove any line in
CLAUDE.md that the code now contradicts. Show me the diff before
writing.

Jak pliki CLAUDE.md się wczytują i nakładają, opisuje strona o systemie pamięci Claude Code. Jeśli repozytorium nie ma żadnego pliku z instrukcjami, najpierw uruchom /init, jak opisano w sekcji o uruchamianiu /init w codebasie, do którego właśnie dołączyłeś.

Uruchamiaj cykliczny raport o codebasie w trybie headless

Dla raportu, którego tech lead chce co sprint, na przykład modułów bez testów albo skupisk TODO, uruchom Claude Code w trybie headless. Sesje claude -p startują w trybie Manual (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią); w trybie Manual czytanie plików nie wymaga zgody. --permission-mode dontAsk odrzuca u każdego dostawcy wszystko, co wymagałoby pytania, więc przebieg nie zmieni plików, --permission-prompts none gwarantuje, że nic nie czeka na odpowiedź, a --allowedTools przepuszcza jedyne polecenie potrzebne do raportu:

claude -p "List source files under src/ that have no test file importing them. \
Group by top-level directory and give each file's last commit date from git log. \
Return only JSON: {\"untested\": [{\"path\": string, \"lastCommit\": string}]}" \
  --permission-mode dontAsk \
  --permission-prompts none \
  --allowedTools "Bash(git log *)" \
  --max-budget-usd 5 \
  --output-format json | jq -r '.result' > untested-report.json

--output-format json opakowuje odpowiedź w kopertę z wynikiem, więc jq -r '.result' wyciąga JSON, o który prosi prompt. Commituj poprzedni raport albo trzymaj go jako artefakt CI i pozwól skryptowi porównać oba, żeby człowiek oglądał tylko to, co się zmieniło. --max-budget-usd ogranicza wydatki i działa tylko z --print (-p); wszystkie cztery flagi pochodzą z claude --help 2.1.283. Podpięcie tego pod CI opisuje strona o automatyzacji Claude Code.

Gdzie eksploracja codebase’u zawodzi i jak z tego wyjść

Objaw	Prawdopodobna przyczyna	Jak naprawić
Przegląd jest ogólnikowy („używa architektury warstwowej”)	Prompt prosił o podsumowanie, nie o cytowania	Zapytaj ponownie z „cite `path:line` for every claim, mark inferences”. Ogólnikowa proza bez cytowań to zgadywanie.
Cytowania nie przechodzą skryptu	Od czasu dokumentu, który Claude przeczytał, zmieniono nazwy plików albo model odtworzył ścieżkę z pamięci	Wskaż Claude cytowania, które nie przeszły, i każ mu ponownie otworzyć te pliki. Nigdy nie poprawiaj cytowania ręcznie bez ponownego przeczytania kodu.
Odpowiedzi robią się coraz bardziej mgliste	Okno kontekstu jest pełne zawartości plików	Sprawdź `/context`. Przenieś szerokie czytanie do subagentów, potem `/compact` albo `/clear` i kontynuuj od `ARCHITECTURE.md`.
Claude opisuje system z README, a nie ten z kodu	Nieaktualna dokumentacja została potraktowana jako źródło prawdy	Napisz „when documentation and code disagree, the code wins; list every disagreement you find”. Te rozbieżności same w sobie są cennym wynikiem.
Śledzenie urywa się na wstrzykiwaniu zależności albo rejestrze pluginów	Statyczne czytanie nie rozwiąże powiązań z czasu wykonania	Poproś o miejsce rejestracji, a potem potwierdź testem charakteryzującym albo logiem w lokalnym uruchomieniu, nie dłuższym promptem.
Claude zaczął edytować w trakcie eksploracji	Sesja była w trybie auto, startowym od v2.1.283	Naciśnij Esc, uruchom `/rewind`, żeby przywrócić pliki, przełącz na tryb planowania i kontynuuj.
Nietypowa architektura odczytana jako standardowe MVC	Nietypowe nazewnictwo (katalog `handlers/` z logiką domenową)	Popraw to raz i dopisz do `CLAUDE.md`, żeby następna sesja nie powtórzyła błędu.

Jak to samo zadanie wygląda w Codex i Cursorze

Ta strona dotyczy tylko Claude Code. Workflow „zmapuj, prześledź, udowodnij, zapisz” przenosi się na inne narzędzia, ale mechanizmy kontroli są inne: Codex ma własne profile uprawnień i /plan, a Cursor ma Plan Mode w edytorze. Zobacz zrozumienie codebase’u z Codex i strategie Cursora dla dużych codebase’ów. Podejście niezależne od narzędzia, dla monorepo i repozytoriów z milionami linii, opisuje strona o strategiach dla bardzo dużych codebase’ów.

Dokąd dalej po zmapowaniu codebase’u

Gdy mapa przejdzie kontrole, zaplanuj zmianę w oparciu o nią. Tech leadzi, którzy mierzą, jak szybko nowi inżynierowie dochodzą do pierwszej bezpiecznej zmiany, mogą użyć metryki wdrożenia developera.

Planowanie funkcji z Claude Code Zamień ticket w przejrzany plan w trybie planowania, korzystając z mapy, którą właśnie udowodniłeś.

Praca w dużych codebase'ach z Claude Code Równoległe sesje, worktree i budżety tokenów, gdy zaczynasz zmieniać duże repozytorium.