Zrozumienie dużych codebase'ów przez CLI

To Twój pierwszy tydzień w nowym zespole. Repozytorium ma 400,000 linii kodu, siedem lat historii git i oryginalny architekt odszedł dwa lata temu. README nie było aktualizowane od 2023 roku. Musisz dostarczyć feature do piątku, ale nawet nie wiesz, gdzie znajduje się logika uwierzytelniania.

To dokładnie problem, do którego Claude Code został zbudowany. Zamiast spędzać trzy dni na czytaniu plików źródłowych i ręcznym śledzeniu łańcuchów wywołań, możesz systematycznie eksplorować codebase z terminala — używając sub-agentów do równoległego badania wielu obszarów bez spalania okna kontekstu Twojej głównej sesji.

Co z tego wyniesiesz

• Systematyczny workflow eksploracji, który działa na dowolnej wielkości codebase
• Prompty, które wyodrębniają architekturę, przepływ danych i konwencje w minuty
• Wzorce sub-agentów, które utrzymują Twój główny kontekst czysty podczas głębokiego badania
• Techniki budowania mentalnego modelu kodu, którego nigdy wcześniej nie widziałeś

Workflow eksploracji

Efektywna analiza codebase podąża za wzorcem top-down: zacznij od szerokiej architektury, zidentyfikuj podsystemy, potem wgłębiaj się w konkretny obszar, który musisz zmodyfikować.

1. Zacznij od przeglądu wysokiego poziomu

   Otwórz Claude Code w katalogu głównym projektu i zapytaj o ogólny obraz. Claude czyta kluczowe pliki jak package.json, strukturę katalogów, pliki konfiguracyjne i punkty wejścia, aby zbudować podsumowanie architektury.

   Give me a high-level overview of this codebase. What does it do,
   what's the tech stack, and how is the code organized? Focus on
   the main entry points and the directory structure.

   Claude czyta dziesiątki plików, aby na to odpowiedzieć, ale odpowiedź jest zwięzłym podsumowaniem. To jest Twoja mapa do głębszej eksploracji.

2. Zidentyfikuj kluczowe podsystemy

   What are the main modules or subsystems in this project? For each one,
   tell me: what it does, where the code lives, and what other modules
   it depends on. Keep it brief -- one paragraph per module.

3. Wgłębiaj się w obszar, który musisz zmodyfikować

   Teraz, gdy znasz krajobraz, skup się na konkretnym podsystemie istotnym dla Twojego zadania.

   Wskazówka

   Prompt gotowy do skopiowania do celowanej eksploracji kodu:

   I need to understand the authentication system. Trace the complete
   login flow from the HTTP request handler to the database query.
   Show me:
   1. The entry point (route/controller)
   2. Each middleware in the chain
   3. The session/token management logic
   4. The database queries involved
   5. How errors are handled at each step
   
   Reference specific file paths and line numbers.

4. Zmapuj przepływ danych

   Zrozumienie jak dane poruszają się przez system jest często cenniejsze niż zrozumienie pojedynczego pliku.

   Trace how a "create order" request flows through the system.
   Start from the API endpoint, follow it through validation,
   business logic, database writes, and any events/notifications
   that get triggered. Show the data shape at each step.

Używanie sub-agentów do głębokiej investigacji

Oto krytyczna technika, która oddziela efektywną eksplorację codebase od eksploracji spalającej kontekst: sub-agenci.

Gdy Claude czyta pliki, aby odpowiedzieć na Twoje pytania, każdy plik trafia do Twojego okna kontekstu. W dużym codebase pojedyncza głęboka investigacja może skonsumować połowę Twojego kontekstu. Sub-agenci rozwiązują to, działając we własnych oknach kontekstu i raportując zwrotnie podsumowania.

Use sub-agents to investigate these three areas in parallel:

1. How does the payment processing work? Trace from checkout to
   payment confirmation, including error handling and retries.

2. What's the caching strategy? Find all caching layers (Redis,
   in-memory, CDN) and document what's cached, TTLs, and
   invalidation patterns.

3. How are background jobs handled? Find the job queue system,
   list all job types, and document retry/failure handling.

For each investigation, report back: key files involved,
the main flow, and any potential issues you notice.

Każdy sub-agent eksploruje niezależnie, czyta tyle plików ile potrzeba i zwraca skoncentrowane podsumowanie. Twój główny kontekst pozostaje czysty.

Uwaga

Nie proś Claude o “investigate everything about the codebase” bez zawężania zakresu. Nieograniczona eksploracja wypełnia okno kontekstu zawartością plików, których możesz nigdy nie użyć. Zawsze określaj, co chcesz się dowiedzieć, lub deleguj do sub-agentów, gdy investigacja może być szeroka.

Odczytywanie konwencji z kodu

Każdy codebase ma niepisane zasady. Claude może je zidentyfikować, analizując wzorce w plikach.

Wskazówka

Prompt gotowy do skopiowania do odkrywania konwencji:

Analyze the coding conventions used in this project by examining
at least 10 different source files. Report on:

- Naming conventions (variables, functions, files, directories)
- Error handling patterns (try/catch, Result types, error boundaries)
- Testing patterns (file naming, assertion style, mock approach)
- Import organization (ordering, aliasing, barrel exports)
- State management approach
- API response format

For each convention, show a concrete example from the codebase.
Flag any inconsistencies where different parts of the codebase
follow different conventions.

Ten prompt jest szczególnie użyteczny, gdy zamierzasz napisać nowy kod i chcesz dopasować istniejący styl bez bycia informowanym przez członka zespołu.

Historia Git jako źródło dokumentacji

Log git często mówi więcej o ewolucji codebase niż jakakolwiek dokumentacja.

Look through the git history of src/auth/ and summarize how
the authentication system evolved. Focus on:
- Major refactors (what changed and why, based on commit messages)
- Recent changes in the last month
- Files that change frequently (likely hot spots)
- Contributors who know this code best

Do zrozumienia dlaczego konkretny fragment mylącego kodu istnieje:

Show me the git blame for src/middleware/rateLimit.ts and explain
why it's implemented this way. Look at the original commit and any
PRs that modified it. There's a comment saying "DO NOT CHANGE"
on line 47 -- find out why.

Tryb Plan do bezpiecznej eksploracji

Gdy chcesz eksplorować codebase bez ryzyka przypadkowej modyfikacji plików, użyj Plan Mode. Claude może czytać pliki i uruchamiać komendy tylko do odczytu, ale nie może niczego edytować.

claude --permission-mode plan

To jest szczególnie użyteczne podczas pierwszego dnia w nowym projekcie. Możesz zadać dowolne pytanie, prześledzić dowolny przepływ i przeczytać dowolny plik — wszystko z gwarancją, że Claude nie zmieni ani jednej linii kodu.

I'm in Plan Mode. Walk me through the request lifecycle for
this Express application. Start from the server entry point,
follow a request through all middleware, and explain what each
middleware layer does. I want to understand the system before
making any changes.

Budowanie bazy wiedzy

Po przebadaniu codebase, przechwyć to, czego się nauczyłeś, abyś nie musiał ponownie eksplorować w przyszłych sesjach.

1. Wygeneruj dokument architektury

   Based on everything you've learned about this codebase, create
   an ARCHITECTURE.md file that covers:
   - System overview and tech stack
   - Directory structure with explanations
   - Key data flows (request lifecycle, background job processing)
   - External dependencies and integrations
   - Development workflow (how to run, test, deploy)

2. Zaktualizuj CLAUDE.md ze swoimi odkryciami

   Update CLAUDE.md with the conventions and gotchas you discovered.
   Include the build/test commands, code style rules, and any
   "traps" where the code does something non-obvious. Keep it
   under 50 lines.

3. Stwórz słowniczek terminów domenowych

   This codebase uses domain-specific terms I keep seeing: "fulfillment",
   "settlement", "reconciliation", "provider". Create a GLOSSARY.md
   that defines each domain term as used in THIS codebase, with
   references to where the concept is implemented.

Tryb headless do raportów codebase

Do automatycznej lub powtarzalnej analizy, użyj trybu headless do generowania raportów bez interaktywnej sesji.

claude -p "Analyze the test coverage in this project. List all \
source files that have no corresponding test file. Group by \
directory and sort by most recently modified." \
--output-format json > coverage-gaps.json

To jest użyteczne do raportów onboardingowych, audytów długu technicznego lub okresowych kontroli zdrowia codebase, które działają w CI.

Wskazówka

Prompt gotowy do skopiowania do automatycznego raportu zdrowia codebase:

claude -p "Generate a codebase health report covering:
1. Files with no test coverage
2. Functions longer than 50 lines
3. Files that import more than 10 modules
4. TODO/FIXME/HACK comments with their locations
5. Dependencies that are more than 2 major versions behind

Format as markdown with sections and tables." > health-report.md

Gdy to się psuje

Claude daje płytki przegląd, który omija ważne szczegóły. Zadawaj pytania uzupełniające, które wymuszają głębsze czytanie: “Trace the actual function calls, not just the module names” lub “Show me the specific database query, not just ‘it queries the database’.”

Kontekst wypełnia się podczas eksploracji. Używaj sub-agentów do każdej investigacji, która może dotknąć więcej niż 5-10 plików. Uruchom /compact, jeśli Twoja główna sesja staje się ciężka, lub /clear, jeśli przełączasz się do innego obszaru codebase.

Claude błędnie identyfikuje architekturę. To się zdarza z niekonwencjonalnymi strukturami projektu. Popraw to explicite: “This is not a standard MVC app. The ‘handlers’ directory contains business logic, not HTTP handlers. Re-analyze with that understanding.”

Stara dokumentacja jest sprzeczna z kodem. Powiedz Claude, aby zawsze ufał kodowi nad dokumentacją: “When the README and the actual code disagree, the code is correct. Flag the documentation as outdated.”

Co dalej

Teraz, gdy możesz nawigować po dowolnym codebase, czas zaplanować feature, który musisz zbudować.

Planowanie funkcjonalności Transformuj wymagania w szczegółowe plany implementacji używając Plan Mode i rozszerzonego myślenia

Implementacja Zamień swój plan w gotowy do produkcji kod za pomocą cyklu explore-plan-implement Claude Code