Zrozumienie baz kodu z Codex

Odziedziczyłeś serwis z 200 tysiącami linii kodu, bez dokumentacji architektury, a ostatnia osoba, która rozumiała przepływ płatności, odeszła sześć miesięcy temu. Twój pierwszy ticket to “napraw logikę ponawiania webhooków”, ale nie możesz nawet znaleźć, gdzie webhooks są przetwarzane. Mógłbyś spędzić dwa dni czytając kod. Albo mógłbyś poprosić Codex o zmapowanie terenu za ciebie w dwadzieścia minut.

Czego się nauczysz

Wielopowierzchniowe podejście do eksploracji bazy kodu — aplikacja do głębokich analiz, CLI do szybkich zapytań, IDE do kontekstu na poziomie plików
Prompty wyciągające architekturę, przepływy danych i granice modułów z dowolnej bazy kodu
Przepływ pracy do tworzenia dokumentacji onboardingowej, która pozostaje aktualna dzięki zaplanowanym automatyzacjom
Techniki śledzenia konkretnych przepływów żądań przez nieznany kod

Przepływ pracy

Wybierz swoją powierzchnię

Codex daje ci wiele punktów wejścia do eksploracji bazy kodu, każdy z innymi mocnymi stronami:

Najlepsza do ciągłej eksploracji, gdzie chcesz podążać wątkami dociekań. Aplikacja utrzymuje pełny kontekst konwersacji, synchronizuje się z twoim IDE i pozwala zostawiać komentarze inline przy kodzie, do którego chcesz wrócić.

Otwórz projekt w aplikacji Codex, wybierz tryb Local (tylko czytasz, nie modyfikujesz) i zacznij zadawać pytania.

Najlepsze do szybkich, ukierunkowanych zapytań, gdy już wiesz mniej więcej, gdzie szukać. CLI czyta twój katalog roboczy i pozwala użyć @ do odwoływania się do konkretnych plików.

codex

Użyj @ w kompozerze, aby wyszukiwać rozmycie i dołączać pliki do promptu.

Krok 1: Uzyskaj ogólny obraz

Zacznij od pytania na najwyższym poziomie. Nie określaj plików — pozwól Codex przeskanować strukturę repozytorium i zorientować się, co jest ważne.

Prompt do skopiowania — przegląd architektury:

Explain the architecture of this codebase. Include:

1. What this project does (in one paragraph)
2. The main modules/packages and their responsibilities
3. How requests flow from entry point to response
4. The database schema (tables and key relationships)
5. External services this project depends on
6. One or two architectural decisions that are unusual or surprising

Format as a brief document I could hand to a new team member.

W aplikacji Codex ten prompt w trybie Local pozwala Codex odczytać całe drzewo projektu, przeskanować kluczowe pliki (package.json, punkty wejścia, pliki konfiguracyjne, definicje schematów) i zsyntetyzować przegląd. Wynik jest znacznie bardziej przydatny niż samodzielne grepowanie kodu, ponieważ Codex łączy kropki między plikami.

Krok 2: Prześledź konkretny przepływ

Gdy zrozumiesz architekturę na wysokim poziomie, przybliż się do konkretnego obszaru, w którym musisz pracować. Najbardziej efektywna technika to opisanie zachowania, które cię interesuje, i poproszenie Codex o prześledzenie go od początku do końca.

Prompt do skopiowania — śledzenie przepływu żądania:

Trace the complete flow when a Stripe webhook hits this service:

1. Which file/route handles the incoming webhook POST?
2. How is the webhook signature verified?
3. What happens for each event type (payment_succeeded, payment_failed, subscription_updated)?
4. Which database tables are written to?
5. Are there any retry or idempotency mechanisms?
6. What error handling exists, and what happens on failure?

Include the exact file paths and function names at each step.

W CLI możesz to jeszcze bardziej ukierunkować, dołączając pliki, które podejrzewasz:

I need to understand the webhook retry logic. Read @src/routes/webhooks.ts @src/services/stripe.ts and trace what happens when a webhook delivery fails. Focus on retry behavior and idempotency.

Krok 3: Zmapuj granice modułów

Dla dużych monorepo zrozumienie, gdzie jeden moduł się kończy, a drugi zaczyna, jest kluczowe przed wprowadzeniem zmian. Użyj rozszerzenia IDE do tego — otwórz kilka plików z badanego obszaru, a następnie zapytaj Codex z włączonym auto-kontekstem.

Prompt do skopiowania — mapowanie zależności:

Map the dependency relationships between the modules in this project:

1. Which modules import from which other modules?
2. Are there any circular dependencies?
3. Which modules are "leaf" nodes (depended on by many, depend on few)?
4. Which module boundaries are clean and which are leaky?

Present this as a list of modules with their inbound and outbound dependencies.

Krok 4: Generuj dokumentację onboardingową

Gdy zrozumiesz bazę kodu, zamień to zrozumienie w dokumentację, która pomoże następnej osobie. Jeszcze lepiej, skonfiguruj automatyzację, aby pozostawała aktualna.

W aplikacji Codex utwórz wątek worktree, aby wygenerowane dokumenty nie dotykały twojego katalogu roboczego, dopóki ich nie przejrzysz:

Based on your analysis of this codebase, create a docs/ARCHITECTURE.md file that covers:

1. System overview with a text-based component diagram
2. Key data flows (user registration, payment processing, webhook handling)
3. Database schema overview with table relationships
4. Environment variables and configuration
5. Common development tasks (adding a new API endpoint, adding a migration)

Write it for a mid-level developer joining the team. Keep it under 500 lines.

Następnie skonfiguruj cotygodniową automatyzację, aby utrzymywać aktualność:

Review the last week of commits that touch src/. If any architectural changes were made (new modules, changed data flows, new database tables), update docs/ARCHITECTURE.md to reflect them. If nothing architectural changed, report that no updates are needed.

Używanie chmury do głębokiej analizy

Dla bardzo dużych repozytoriów, gdzie lokalna analiza napotyka limity kontekstu, deleguj do zadania w chmurze. Środowiska chmurowe mogą działać dłużej, mają dostęp do pełnego repozytorium i obsługują podejście best-of-N dla złożonych analiz.

W aplikacji Codex przełącz się na tryb Cloud i prześlij prompt analityczny. Agent chmurowy może uruchamiać kroki budowania, wykonywać zapytania wobec testowych baz danych i poświęcić więcej czasu na dokładną eksplorację bazy kodu.

Z CLI możesz również uruchomić analizę w chmurze:

codex cloud exec --env my-env "Analyze the authentication subsystem in src/auth/. Map every entry point, middleware chain, and session management flow. Report the findings as a structured document."

Kiedy to nie działa

Codex błędnie identyfikuje główny punkt wejścia. W monorepo z wieloma serwisami Codex czasami przyczepia się do złego package.json lub pliku wejściowego. Bądź wyraźny: “The service I care about is in packages/billing-api/. Ignore all other packages.”

Analiza jest zbyt płytka na dużych bazach kodu. Jeśli Codex daje powierzchowne odpowiedzi, prawdopodobnie nie czytał wystarczająco głęboko. Zawęź zakres: zamiast “explain the architecture” zapytaj “explain how the order fulfillment pipeline works, starting from src/services/orders/index.ts.”

Wygenerowana dokumentacja jest przestarzała w momencie przeglądu. Jeśli generujesz dokumenty w worktree, ale nie scalasz ich przez tydzień, baza kodu mogła się zmienić. Użyj Sync with local, aby wciągnąć wszelkie lokalne zmiany do worktree przed finalizacją.

Zadanie w chmurze wybiera złą gałąź. Zadania w chmurze uruchamiają się wobec domyślnej gałęzi w mapie repozytoriów twojego środowiska. Jeśli potrzebujesz analizy gałęzi funkcjonalności, określ gałąź w prompcie lub zaktualizuj konfigurację środowiska.

Co dalej

Budowanie funkcjonalności z równoległymi agentami Teraz, gdy rozumiesz bazę kodu, buduj funkcjonalności jednocześnie w wielu worktree

Przegląd kodu wspomagany AI Wykorzystaj swoje zrozumienie architektury, aby skonfigurować skuteczne wytyczne przeglądu w AGENTS.md