Poznawanie nieznanej bazy kodu z Codex

Codex mapuje nieznaną bazę kodu w sandboksie tylko do odczytu: interaktywna sesja CLI daje przegląd od góry i śledzenie jednego przepływu, subagenci prowadzą równoległe dochodzenia, codex exec zapisuje mapę do pliku, a Codex cloud przejmuje bardzo duże repozytoria. Mapie można ufać dopiero wtedy, gdy jej cytowania path:line przejdą skrypt, a kluczowe twierdzenie przejdzie test.

Przejmujesz serwis płatności bez dokumentu architektury, a inżynier, który rozumiał obsługę webhooków, odszedł pół roku temu. Pierwszy ticket brzmi „napraw logikę ponawiania webhooków”, a ty nie potrafisz jeszcze wskazać, gdzie webhooki są przetwarzane. Ta strona jest dla takiego dewelopera 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 zyskujesz, mapując bazę kodu z Codex

• Konfigurację Codex tylko do odczytu, która może przejrzeć wszystko i niczego nie zmienia, oraz jej surowszy wariant dla kodu, któremu nie ufasz.
• Sześć promptów do skopiowania: przegląd, śledzenie przepływu, odkrywanie konwencji, archeologię w gicie, równoległe dochodzenie subagentów i krytyczną weryfikację mapy.
• Polecenie codex exec i polecenie codex cloud exec, po których mapa zostaje w pliku, a nie w transkrypcie czatu.
• Skrypt powłoki, który sprawdza, czy każde cytowanie path:line istnieje, oraz test charakteryzacyjny, który zamienia kluczowe twierdzenie w coś, co CI sprawdza przy każdym commicie.
• ARCHITECTURE.md dla ludzi i aktualizację AGENTS.md dla każdej przyszłej sesji Codex.

Która powierzchnia Codex pasuje do którego pytania?

Wybieraj powierzchnię według pytania, nie z przyzwyczajenia. Każdy wiersz poza rozszerzeniem IDE zostawia artefakt, który da się sprawdzić.

Pytanie	Powierzchnia	Jak zacząć	Co zostaje
„Czym jest ten system i gdzie leży mój ticket?”	Interaktywne CLI, tylko odczyt	codex -s read-only	Szkic ARCHITECTURE.md
„Co robi funkcja, którą mam otwartą?”	Rozszerzenie IDE (VS Code i jego forki, np. Cursor)	Zaznacz kod i zapytaj w panelu Codex	Nic trwałego; ważne ustalenia przenieś do mapy
„Chcę tę samą mapę co sprint”	CLI bez interakcji	codex exec -s read-only -o …	Datowany plik raportu
„Zbadaj repozytorium za duże na mój laptop albo gałąź, której nie mam lokalnie”	Codex cloud	codex cloud exec --env … --branch …	Zadanie w chmurze, którego diff zawiera raport
„Chcę prowadzić kilka wątków dochodzenia obok siebie”	Aplikacja desktopowa Codex (codex app lub /app, tylko macOS i Windows)	Kontynuuj sesję CLI przez /app	Te same pliki, przeglądane w aplikacji

Według Neowin (źródło wtórne) aplikacja desktopowa Codex trafiła 9 lipca 2026 roku do aplikacji desktopowej ChatGPT jako tryb Codex; CLI Codex nadal nazywa ją aplikacją desktopową (Desktop app). Pracę w aplikacji opisuje strona Aplikacja desktopowa Codex: równoległe wątki, worktree i przegląd. Ta strona korzysta z CLI, bo tam każdy krok kończy się plikiem.

Uruchom sesję Codex tylko do odczytu

Eksploracja nie powinna edytować plików, więc wybierz sandbox świadomie. Uruchom w terminalu, w katalogu głównym repozytorium:

codex -s read-only -c model_reasoning_effort="high"

-s read-only pozwala Codex czytać pliki i uruchamiać polecenia tylko do odczytu, takie jak git log, a blokuje zapisy w katalogu roboczym. Domyślny model Codex, GPT-6 Astra, pracuje domyślnie z wysiłkiem rozumowania low (dla zalogowanych kont serwer może to nadpisać; /status pokaże faktyczny model); mapowanie zyskuje na głębszym rozumowaniu, więc najpierw podnieś wysiłek, a dopiero potem rozważ inny model (aktualne ustawienia domyślne znajdziesz w przeglądzie modeli). Obie flagi są w codex --help 0.157.1.

OpenAI preferuje profile uprawnień, które są w wersji beta: codex -c default_permissions=":read-only". Używaj profilu albo -s, nie obu naraz, bo według OpenAI profile i starszy system sandboksów „do not compose”. W trakcie sesji /permissions zmienia uprawnienia Codex, a /status pokazuje bieżącą konfigurację i zużycie tokenów.

Dla repozytorium, któremu nie ufasz, na przykład kodu od dostawcy lub z przejętej firmy, działają dwa zabezpieczenia. Od Codex 0.150.0 projekt, którego nie oznaczysz jako zaufany, nie dostarcza swojego AGENTS.md, więc nie oznaczaj go jako zaufanego, gdy Codex o to zapyta. Hooki uruchamiają się dopiero po nadaniu im trwałego zaufania, więc tego też odmów. Mocniejszą izolację da uruchomienie sesji w kontenerze.

Notatka

W zaufanym projekcie Codex czyta AGENTS.md jako instrukcje. Nieaktualny plik wprowadza w błąd pierwsze odpowiedzi tak samo jak nieaktualne README. Zanim zaufasz przeglądowi, zapytaj Codex, które pliki instrukcji wczytał. Jak te pliki się nakładają, opisuje konfiguracja AGENTS.md.

Zmapuj bazę kodu od góry do dołu

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

1. Zdobądź przegląd. Codex czyta manifesty, drzewo katalogów, konfigurację i punkty wejścia, a potem zwraca krótkie podsumowanie. To podsumowanie jest twoim indeksem, a nie zrozumieniem systemu.

   Prompt do skopiowania: przegląd nieznanego repozytorium

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

2. Prześledź jeden przepływ, który musisz zmienić. Ogranicz śledzenie do swojego ticketu. Jedna ścieżka przebyta od początku do końca jest warta więcej niż wycieczka po wszystkich modułach. Wpisz @ w polu promptu albo użyj /mention, żeby dołączyć pliki, które już podejrzewasz.

   Prompt do skopiowania: śledzenie webhooka od początku do końca

   Trace what happens when a Stripe webhook reaches this service, from the
   HTTP route to the last 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. Cover signature
   verification, each event type the code handles, retries and
   idempotency, and what happens when a handler throws. End with the open
   questions you could not answer from the code. Do not guess: if a call
   goes through dependency injection or dynamic dispatch you cannot
   resolve, say so.

3. Poznaj konwencje, zanim napiszesz kod. Konwencje to niepisane zasady, za których złamanie recenzent odrzuci twój pierwszy pull request.

   Prompt do skopiowania: odkrywanie konwencji zespołu

   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, and API response shape. Give
   one path:line example for each. Then list the places where two
   conventions compete, and use git log to say which one is newer,
   because that is the one I should follow.

4. Zapytaj gita, skąd wziął się dziwny kod. Historia commitów wyjaśnia decyzje, których sam kod nie wyjaśni, na przykład pozornie zbędną pętlę ponawiania albo komentarz „nie zmieniać”.

   Prompt do skopiowania: archeologia w gicie dla niejasnego fragmentu

   In src/webhooks/stripe.ts the retry handler sleeps before re-reading
   the event from the database. Use git log -L and git blame to find the
   commit that introduced that pattern and every later commit that touched
   it. Quote the commit messages, name any linked issue or PR numbers they
   contain, and explain what breaks if the sleep is removed. If the history
   does not say, tell me that instead of inferring a reason.

Utrzymaj główny wątek w czystości dzięki subagentom

Każdy plik przeczytany przez Codex zostaje w kontekście sesji, a odpowiedzi tracą precyzję, gdy kontekst się zapełnia. Subagenci są w Codex 0.157.1 domyślnie włączeni (multi_agent ma status stable w codex features list): każdy bada kod we własnym kontekście i zwraca podsumowanie. /subagents przełącza między nimi, a /side pozwala zadać szybkie pytanie w efemerycznym forku bez zaśmiecania głównego wątku.

Prompt do skopiowania: równoległe dochodzenie subagentów

Spawn three subagents and run these investigations in parallel. Each
returns at most 30 lines with path:line citations and marks anything
inferred as (inferred). None of them edits files.

1. Webhooks: every inbound webhook route, how each is authenticated,
   and where failed deliveries are retried or dropped.
2. Data: every table the webhook code writes, the migration that created
   it, and which other code reads it.
3. Background jobs: the queue, every job type, retry limits and where
   failed jobs end up.

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

Gdy /status pokazuje, że kontekst się zapełnia, uruchom /compact, żeby streścić rozmowę, albo /new, żeby zacząć od nowa na podstawie zapisanej mapy. Budżet kontekstu w długich sesjach opisuje zarządzanie kontekstem na powierzchniach Codex.

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

uv tool install -p 3.13 serena-agent
serena init
codex mcp add serena -- serena start-mcp-server --project-from-cwd --context=codex

Własna konfiguracja Sereny dla Codex (serena setup codex) dodatkowo podnosi startup_timeout_sec do 15 w config.toml; zrób to samo, jeśli serwer przekroczy limit czasu przy pierwszym uruchomieniu.

Porównanie z alternatywami znajdziesz w artykule serwery MCP do analizy kodu.

Zapisz mapę do pliku przez codex exec

Mapy w transkrypcie czatu nie da się sprawdzić ani porównać. Uruchom przegląd bez interakcji, żeby wynik trafił do pliku. Zapisz prompt przeglądu z pierwszego kroku w prompts/architecture-map.md, a potem uruchom w terminalu, w katalogu głównym repozytorium:

mkdir -p docs
codex exec -s read-only -c model_reasoning_effort="high" \
  -o docs/ARCHITECTURE.md \
  "$(cat prompts/architecture-map.md)"

-s read-only nie pozwala agentowi niczego zapisać, a -o (--output-last-message) sprawia, że to samo CLI zapisuje ostatnią wiadomość Codex do pliku. Obie flagi są w codex exec --help 0.157.1. Uruchomienia skryptowe, wyjście JSON i uwierzytelnianie w CI opisuje uruchamianie Codex bez interakcji.

Przekaż bardzo duże repozytorium do Codex cloud

Gdy repozytorium jest za duże, żeby wygodnie badać je na twojej maszynie, albo potrzebny kod leży na gałęzi, której nie masz lokalnie, zleć analizę jako zadanie w chmurze. Najpierw musi istnieć środowisko; zobacz środowiska chmurowe Codex.

codex cloud exec --env ENV_ID --branch release/2026-09 \
  "Map the authentication subsystem under src/auth/: every entry point, the \
middleware chain and session handling, with path:line citations. Write the \
result to docs/analysis/auth-map.md and change no other file."

Zastąp ENV_ID identyfikatorem swojego środowiska; codex cloud bez podpolecenia pozwala je przeglądać. --branch domyślnie wskazuje twoją bieżącą gałąź, więc podawaj ją zawsze, gdy chodzi ci o inną. codex cloud status TASK_ID pokazuje postęp, a codex cloud diff TASK_ID wyświetla raport jako diff, który czytasz bez nakładania. --attempts uruchamia best-of-N, co opłaca się bardziej przy zmianach w kodzie niż przy raportach. Polecenie codex cloud jest w 0.157.1 oznaczone jako eksperymentalne.

Udowodnij mapę, zanim jej zaufasz

Płynne podsumowanie nie musi być poprawne. Agent może zacytować plik o zmienionej nazwie, opisać middleware, który jest zarejestrowany, ale wyłączony, albo przemilczeć dynamiczne wywołanie, którego nie rozwiązał. Nie naprawisz tego, czytając każdy plik od nowa. Sprawiasz, że każde twierdzenie da się sprawdzić, i zostawiasz sprawdzanie maszynom. Wykonaj te trzy kontrole po kolei, od najtańszej.

1. Sprawdź każde cytowanie automatycznie. Powyższe prompty wymagają path:line dla każdego twierdzenia. Uruchom w terminalu, w katalogu głównym repozytorium. Skrypt wypisuje każde cytowanie, którego plik nie istnieje albo którego numer linii wychodzi poza koniec pliku:

   grep -oE '[A-Za-z0-9_./-]+\.[A-Za-z0-9]+:[0-9]+' docs/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

   Pusty wynik oznacza, że każde cytowanie wskazuje prawdziwy kod. Cytowania plików bez rozszerzenia, takich jak Dockerfile, nie są sprawdzane, a host:port pojawi się jako brakujący plik, który możesz zignorować. Kontrola dowodzi, że twierdzenia są zakotwiczone w kodzie, a nie że są prawdziwe.

2. Zaatakuj mapę ze świeżym kontekstem. Recenzent, który nie pisał mapy, nie ma interesu w jej obronie. Uruchom poniższą kontrolę jako osobne wywołanie codex exec -s read-only --ephemeral albo w nowej sesji po /new, żeby nie przejęła założeń pierwszego przebiegu.

   Prompt do skopiowania: krytyczna weryfikacja mapy architektury

   Read docs/ARCHITECTURE.md. You did not write it; 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), dependency-injection wiring, feature flags and code
   that is 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.

3. Zamień kluczowe twierdzenie w test. Wybierz twierdzenie, od którego zależy twój ticket, na przykład „zdarzenie webhooka oznaczone już jako przetworzone jest potwierdzane bez drugiego zapisu do bazy”. Uruchom sesję z prawem zapisu (codex -s workspace-write), poproś Codex o test charakteryzacyjny, który sprawdza dokładnie to obecne zachowanie, i uruchom go. Test, który przechodzi, jest dowodem, że mapa zgadza się z kodem; test, który nie przechodzi, jest najcenniejszym odkryciem tygodnia. Po scaleniu CI sprawdza to twierdzenie przy każdym commicie. Technikę opisują testy charakteryzacyjne.

Kto zatwierdza. Deweloper zatwierdza mapę obszaru, który zamierza zmienić, gdy wszystkie trzy kontrole przejdą. Zmiany w ARCHITECTURE.md i AGENTS.md przechodzą przez zwykły pull request, w którym właściciel kodu tego obszaru przegląda diff kilkudziesięciu linii dokumentacji, a nie kod, który ona opisuje. Na tym polega przejście od czytania kodu do przeglądania dowodów opisane w artykule dowody zamiast diffów.

Zapisz to, czego się nauczyłeś, na następną sesję

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 odbiorców.

Plik	Odbiorca	Co zawiera
docs/ARCHITECTURE.md	Ludzie	Sprawdzoną mapę: podsystemy, prześledzone przepływy, kierunek zależności, otwarte pytania
AGENTS.md	Każda przyszła sesja Codex	Polecenia budowania i testów, potwierdzone konwencje i pułapki, w jak najmniejszej liczbie linii

Jeśli repozytorium nie ma AGENTS.md, utwórz go przez /init, a potem dopracuj tym promptem w sesji z prawem zapisu:

Prompt do skopiowania: zamiana eksploracji w AGENTS.md

Update AGENTS.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
docs/ARCHITECTURE.md; link to it. Remove any line the code now
contradicts. Show me the diff before writing.

Żeby mapa pozostała aktualna, zaplanuj kontrolę dryfu. Automatyzacje w aplikacji desktopowej służą do tego, by „schedule recurring tasks to run in the background”; harmonogram w CI z codex exec działa tak samo i zostawia log. W obu przypadkach niech zadanie raportuje dryf, a nie przepisuje pliku, a skrypt sprawdzający cytowania z poprzedniej sekcji uruchamiaj w CI, żeby nieaktualne cytowanie wywracało build. Konfigurację i zabezpieczenia obu wariantów opisują zaplanowane automatyzacje Codex.

Prompt do skopiowania: cotygodniowy raport dryfu architektury

Compare docs/ARCHITECTURE.md with the commits to src/ from the last seven
days (git log --since="7 days ago" -- src/). List every claim in the
document that those commits made wrong or incomplete: new modules,
changed data flows, new tables, renamed files. Quote the commit and the
path:line that proves each item. If nothing architectural changed, reply
with exactly "No architectural drift". Do not edit any file.

Co psuje się przy eksploracji bazy kodu z Codex

Objaw	Prawdopodobna przyczyna	Jak wyjść z sytuacji
Przegląd jest ogólnikowy („używa architektury warstwowej”)	Prompt prosił o podsumowanie, a nie o cytowania	Zapytaj ponownie z dopiskiem „cite path:line for every claim, mark inferences”. Proza bez cytowań to zgadywanie.
Codex mapuje niewłaściwy serwis w monorepo	Uczepił się pierwszego manifestu lub pliku wejściowego, jaki znalazł	Nazwij zakres: „The service is packages/billing-api/. Ignore every other package.” Albo zacznij od codex -C packages/billing-api -s read-only.
Cytowania nie przechodzą skryptu	Pliki zmieniły nazwy albo model odtworzył ścieżkę z pamięci	Powiedz Codex, które cytowania nie przeszły, i poproś o ponowne otwarcie tych plików. Nigdy nie poprawiaj cytowania ręcznie bez ponownego przeczytania kodu.
Odpowiedzi z czasem tracą precyzję	Kontekst jest pełen zawartości plików	Sprawdź /status. Przenieś szerokie czytanie do subagentów, potem /compact albo /new i kontynuuj od docs/ARCHITECTURE.md.
Codex 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”. Te rozbieżności same są cennym wynikiem.
Śledzenie urywa się na wstrzykiwaniu zależności albo rejestrze wtyczek	Statyczne czytanie nie rozwiąże połączeń tworzonych w czasie działania	Poproś o miejsce rejestracji, a potem potwierdź je testem charakteryzacyjnym albo logiem debugowania w lokalnym uruchomieniu.
Raport z chmury opisuje nie ten kod	Zadanie uruchomiło się na twojej bieżącej gałęzi albo repozytorium środowiska jest nieaktualne	Podawaj --branch jawnie i sprawdź konfigurację środowiska przed ponownym uruchomieniem.
Zapis został zablokowany w trakcie eksploracji	Sandbox tylko do odczytu robi to, co powinien	Zostaw go. Na sesję z prawem zapisu przełącz się tylko na czas testu i aktualizacji AGENTS.md.

Jak to samo zadanie wygląda w Claude Code i Cursorze

Ta strona dotyczy wyłącznie Codex. Schemat „zmapuj, prześledź, udowodnij, zapisz” działa także gdzie indziej, ale mechanizmy są inne: Claude Code używa trybu planowania, flagi --restricted i wbudowanych subagentów Explore, a Cursor pracuje z poziomu edytora. Zobacz poznawanie nieznanej bazy kodu z Claude Code i strategie Cursora dla dużych baz kodu. Porady niezależne od narzędzia dla monorepo i repozytoriów z milionami linii znajdziesz w artykule strategie dla bardzo dużych baz kodu, a cechy repozytorium, które ułatwiają sprawdzenie każdej mapy, w artykule jak przygotować repozytorium do pracy agentów.

Dokąd dalej po zmapowaniu bazy kodu

Gdy mapa przejdzie kontrole, zaprojektuj lub zaplanuj zmianę na jej podstawie. Tech leadzi, którzy mierzą, jak szybko nowi inżynierowie dochodzą do pierwszej bezpiecznej zmiany, mogą użyć metryki czasu wdrożenia dewelopera.

Projektowanie systemu z Codex Na podstawie sprawdzonej mapy porównaj warianty projektu, przetestuj ryzykowne założenia w chmurze i zapisz decyzję.

Przepływy wieloagentowe w Codex Podziel zmianę na równoległe ścieżki, gdy już wiesz, gdzie leży każdy jej fragment.