Projektowanie systemów z Codeksem

Codex wspiera projektowanie systemów, dzieląc pracę między swoje narzędzia (CLI, tryb Plan, chmurę, worktree): uruchomienie CLI tylko do odczytu mapuje obecną architekturę, tryb Plan szkicuje warianty, Codex cloud sprawdza najbardziej ryzykowne założenia jednorazowymi spike’ami, a równoległe worktree budują konkurencyjne projekty na tych samych scenariuszach. Decyzja trafia potem do ADR i do reguły w CI.

Ta strona jest dla programisty lub tech leada, który odpowiada za decyzję architektoniczną i musi jej bronić. Sytuacja: każde wdrożenie monolitu to loteria, zespół zgodził się wydzielić moduł płatności do osobnego serwisu, a nikt nie jest zgodny co do granicy API, migracji danych ani tego, co się dzieje, gdy oba systemy działają równolegle. Do końca sprintu potrzebujesz decyzji popartej dowodami, a nie planu, który przeczytała jedna osoba.

Co zyskasz, projektując wydzielenie serwisu z Codeksem

• Sześciokrokową pętlę projektowania z narzędziem Codeksa, poleceniem i plikiem wynikowym dla każdego kroku
• Siedem promptów do skopiowania: mapa z dowodami, porównanie wariantów, dwa spike’i w chmurze, porównanie prototypów w worktree, ADR z regułą egzekwującą i przegląd projektu
• Tabelę weryfikacji, która mówi, czym udowodnić każdy rodzaj tezy projektowej i kto ją zatwierdza
• Sposoby wyjścia z sytuacji, w których projektowanie z Codeksem idzie źle

Metodę niezależną od narzędzia (krótkie ADR-y plus ograniczenia sprawdzalne maszynowo) opisuje strona decyzje architektoniczne, których agenci przestrzegają. Ta strona to jej implementacja w Codeksie.

Które narzędzie Codeksa obsługuje którą część projektu?

Każdy krok zostawia plik, który da się sprawdzić, więc projekt nigdy nie żyje wyłącznie w historii czatu.

Krok	Narzędzie Codeksa	Polecenie	Co zostaje
1. Mapa obecnego systemu	CLI, sandbox tylko do odczytu	codex exec -s read-only -o …	docs/architecture/payments-map.md
2. Porównanie wariantów	Interaktywne CLI w trybie Plan	/plan	docs/architecture/payments-options.md
3. Test ryzykownych założeń	Codex cloud, best-of-N	codex cloud exec --env … --attempts 2	Diffy spike’ów i notatka z wnioskami, nigdy nie scalane
4. Konkurencyjne projekty	Zarządzane worktree	codex --worktree	Dwie gałęzie z prototypami i jedna tabela porównawcza
5. Zapis i egzekwowanie decyzji	CLI	codex	ADR, reguła w AGENTS.md i reguła zależności w CI
6. Przegląd i pilnowanie dryfu	CLI (tylko do odczytu), @codex review, automatyzacje	codex exec -s read-only …	Uwagi z przeglądu i cotygodniowy raport dryfu

Projektowanie zyskuje na dłuższym rozumowaniu, niż daje mu domyślny wysiłek Codeksa (aktualny domyślny model i wysiłek podaje przegląd modeli), więc w tych sesjach podnieś wysiłek, zanim zaczniesz rozważać inny model. Dodaj -c model_reasoning_effort="high" do dowolnego polecenia z tej strony; klucz istnieje w Codex CLI 0.157.1.

Zmapuj obecną architekturę z cytowanymi dowodami

Projekt jest tak dobry jak jego obraz obecnego systemu. Pierwsze przejście uruchom bez interfejsu i tylko do odczytu, żeby Codex mógł wszystko przejrzeć i niczego nie zmienić. Uruchom to w terminalu z katalogu głównego repozytorium:

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

-s read-only blokuje zapisy w katalogu roboczym, a -o zapisuje ostatnią wiadomość Codeksa do pliku, który tworzy samo CLI. Ten prompt umieść w prompts/payments-map.md:

Prompt do skopiowania: mapa modułu płatności z dowodami

Map the architecture of the payments module in this repository. Change nothing.

1. Every file under src/services/payments/ and src/routes/payments/, grouped by responsibility.
2. Inbound dependencies: every module outside payments that imports or calls into it.
3. Outbound dependencies: everything payments imports or calls outside itself.
4. Database tables payments reads or writes, and which other modules touch the same tables.
5. Shared state: caches, queues, config values, feature flags, transactions that span modules.
6. Every HTTP endpoint and background job that payments exposes or consumes.

Rules:
- Cite path:line for every claim. If you infer something from a name or a config file rather than a call site, mark it INFERRED.
- List anything wired at runtime (dependency injection, event handlers, plugin registries, config-driven routing) in a section called "Not visible statically".
- End with the three most tightly coupled integration points and why each one would block an extraction.
Output Markdown only.

Model językowy słabo liczy importy i gubi zależności wiązane w czasie działania, więc część mapy dotyczącą zależności traktuj jako szkic, a statyczny graf policz narzędziem. Dla bazy kodu w TypeScripcie (sprawdzone 2026-09-26 z dependency-cruiser 18.4.0):

npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt
npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd

Plik z metrykami podaje sprzężenie każdego modułu (dośrodkowe, odśrodkowe i niestabilność), a plik Mermaid zawiera każdą statyczną krawędź importu. Potem w nowej sesji poproś Codeksa, żeby przeczytał docs/architecture/deps.mmd i wypisał każdą krawędź, którą narzędzie znalazło, a mapa pominęła, oraz każdą krawędź z mapy, której narzędzie nie pokazuje. Każda rozbieżność to albo powiązanie w czasie działania, o którym teraz wiesz, albo błąd, który usuwasz. Dokładniejsze wdrożenie w nieznane repozytorium opisuje strona zrozumienie bazy kodu z Codeksem.

Porównaj warianty projektu w trybie Plan

Uruchom sesję interaktywną poleceniem codex -c model_reasoning_effort="high" -c plan_mode_reasoning_effort="high", przełącz ją w tryb Plan komendą /plan i daj Codeksowi mapę. Codex CLI 0.157.1 ma osobny klucz plan_mode_reasoning_effort dla trybu Plan, więc ustaw oba, żeby wyższy wysiłek został po przełączeniu. W trybie Plan sesja tworzy plan, zanim powstanie jakikolwiek kod, i właśnie tam jest miejsce na dyskusję o projekcie.

Prompt do skopiowania: warianty projektu oparte na mapie

Read docs/architecture/payments-map.md and docs/architecture/metrics.txt. They describe the current system.

We are extracting payments into a separate service. Hard constraints:
- Zero downtime; both systems run side by side during the transition.
- No payment record becomes unreadable at any point.
- Existing API consumers keep working without changes.
- In the final state the payments service owns its tables; no shared tables.

For each decision below, propose two or three options. For every option give: the trade-off, the files and tables it touches (cite the map), the reversibility (how we back out after it ships), and the one assumption that would kill it if false.
1. The API boundary: which endpoints move and which stay.
2. Data migration: how the shared tables are split without downtime.
3. Routing during the transition: proxy, feature flag or both.
4. Service-to-service authentication.
5. Behaviour when the payments service is down or slow.

Recommend one option per decision. Then list the killer assumptions we must test before committing, ranked by risk. Do not edit any files until I approve the plan; after approval, write the result to docs/architecture/payments-options.md.

Uszeregowana lista krytycznych założeń to wejście do następnego kroku. Wariant, którego nie da się sprawdzić, to wariant przyjmowany na wiarę, i dokument powinien to mówić wprost.

Sprawdź najbardziej ryzykowne założenia spike’ami w Codex cloud

Spike to kod napisany po to, żeby odpowiedzieć na jedno pytanie, a potem wyrzucony. Codex cloud uruchamia go w kontenerze przygotowanym dla twojego repozytorium, więc spike nie dotyka twojej maszyny ani gałęzi. ENV_ID to identyfikator środowiska w chmurze: uruchom codex cloud, żeby przejrzeć środowiska, a konfigurację środowiska z testową bazą danych i skryptem przygotowującym opisuje strona środowiska Codex cloud. W Codex CLI 0.157.1 codex cloud jest oznaczone jako eksperymentalne, więc jeśli któraś z poniższych flag zostanie odrzucona, sprawdź codex cloud exec --help.

Najpierw zacommituj docs/architecture/ i wypchnij gałąź. codex cloud exec działa na gałęzi w zdalnym repozytorium (--branch, domyślnie bieżąca gałąź), a nie na twoim katalogu roboczym, więc spike nie przeczyta pliku z wariantami, który istnieje tylko na twojej maszynie. Poniższe polecenia podają gałąź wprost jako design/payments.

--attempts 2 zamawia dwie niezależne próby (best-of-N), co tu się przydaje: jeśli dwie próby dają różne odpowiedzi na to samo pytanie, sprawa nie jest rozstrzygnięta.

Prompt do skopiowania: czy granica API się utrzyma?

codex cloud exec --env ENV_ID --branch design/payments --attempts 2 "Spike, not production code. Question: can the payments endpoints listed in docs/architecture/payments-options.md be served without reading any table outside the payments tables?

For each endpoint:
1. Trace the handler down to every query it runs. Cite path:line.
2. Flag every read of users, orders or any other non-payments table.
3. For each flagged read, propose one fix: the caller passes the data, the payments service calls a monolith API, or the data is replicated. State the cost of each.
Run the existing payments tests and report which ones would break if payments lost access to the non-payments tables.
Write everything to docs/architecture/spikes/boundary.md: the path:line traces, the flagged reads with their fixes, the test output, and on the first line a verdict: BOUNDARY HOLDS, HOLDS WITH N CHANGES, or DOES NOT HOLD."

Prompt do skopiowania: podwójny zapis czy przechwytywanie zmian

codex cloud exec --env ENV_ID --branch design/payments --attempts 2 "Spike, not production code. Compare two ways to migrate the payments tables with zero downtime.

A. Dual-write: the monolith writes to both databases; reads move to the new service gradually.
B. Change data capture: replicate the payments tables to the new database; switch reads when lag is acceptable.

For each approach, build the smallest proof of concept that answers these questions, using the test database in this environment:
1. After 1,000 writes that include updates and refunds, do both databases hold identical rows? Show the comparison query and its output.
2. What happens to a write when the new database is unavailable? Reproduce it and show the resulting state.
3. How do you roll back to the monolith alone at each phase?
Write the evidence, not an opinion, to docs/architecture/spikes/migration.md: the queries, their output and the reproduced failure state for each approach. If a question cannot be answered in this environment, say so in that file."

codex cloud diff pokazuje tylko pliki zmienione przez zadanie, a nie jego końcową wiadomość. Dlatego oba prompty zapisują wnioski do pliku w docs/architecture/spikes/: werdykt i dowody pojawiają się wtedy w diffie każdej próby. Gdy zadania się zakończą, porównaj próby z terminala:

codex cloud list --env ENV_ID
codex cloud diff TASK_ID --attempt 1
codex cloud diff TASK_ID --attempt 2

Werdykty i dowody z tych plików spike’ów przenieś do docs/architecture/payments-options.md. Nie uruchamiaj codex cloud apply na spike’u: jego zadaniem była odpowiedź, nie kod.

Zbuduj konkurencyjne projekty w równoległych worktree

Gdy zespół dzieli się między dwa projekty, na przykład synchroniczne wywołania REST i zdarzenia na czas przejściowy, zbuduj oba i zmierz je na tych samych scenariuszach. Scenariusze napisz, zanim powstanie którykolwiek prototyp; inaczej każdy prototyp po cichu wybierze scenariusze, w których wygrywa.

1. Zacommituj wspólny plik ze scenariuszami, docs/architecture/payments-scenarios.md, z 10 ponumerowanymi przypadkami: zwykłe obciążenie karty, zwrot, zduplikowany webhook, serwis płatności niedostępny przez 30 sekund, wolna baza danych i tak dalej. Każdy przypadek podaje oczekiwany wynik.

2. Uruchom po jednej sesji Codeksa na projekt, każdą we własnym zarządzanym worktree, w dwóch terminalach:

   codex --worktree "$(cat prompts/prototype-rest.md)"
   codex --worktree "$(cat prompts/prototype-events.md)"

3. Gdy obie się zakończą, uruchom ten sam skrypt scenariuszy w każdym worktree i wypełnij jedną tabelę porównawczą.

4. Przenieś oba pliki z wynikami na gałąź projektu, bo każdy prototyp zapisał swój plik we własnej gałęzi worktree. W głównym katalogu roboczym, na gałęzi design/payments, uruchom git checkout <gałąź-worktree-rest> -- docs/architecture/results-rest.md oraz git checkout <gałąź-worktree-events> -- docs/architecture/results-events.md i zacommituj oba pliki. To działa, bo każdy prompt prototypu kończy się commitem pliku z wynikami na gałęzi swojego worktree. Prompt z następnego kroku czyta oba.

Oba pliki z promptami różnią się tylko pierwszą linią. Poniżej wersja REST; w drugim pliku zastąp pierwszą linię opisem projektu opartego na zdarzeniach:

Prompt do skopiowania: prototyp jednego projektu na wspólnych scenariuszach

Design under test: the monolith calls the payments service over REST through a proxy with a circuit breaker.

Build the smallest prototype of this design that can run every case in docs/architecture/payments-scenarios.md. Do not change that file.
1. Implement only what the scenarios need. No production hardening.
2. Write one automated test per scenario, named after its number, and a script scripts/run-scenarios.sh that runs them all.
3. For each scenario record: pass or fail, the consistency guarantee you actually observed, and the latency added by the design (median of 20 runs).
4. Write the results to docs/architecture/results-rest.md as a table with one row per scenario.
5. Commit the prototype, the tests, scripts/run-scenarios.sh and the results file on this worktree's branch.
Stop and ask if a scenario cannot be expressed in this design; do not redefine it.

Porównanie staje się tabelą wyników scenariuszy, a nie sporem przy tablicy. Przygotowanie i sprzątanie worktree opisuje strona izolowane zadania Codeksa w worktree Gita, a strona przepływy wieloagentowe przyda się, gdy wariantów jest więcej niż dwa.

Zapisz decyzję tak, żeby kolejne sesje agentów jej przestrzegały

Decyzja, która istnieje tylko w dokumencie, rozmywa się przy pierwszym skrócie, na jaki pójdzie agent. Zapisz ją na trzy sposoby: jako ADR dla ludzi, jako regułę w AGENTS.md, którą Codex czyta na początku każdej sesji, i jako test w CI, który zawodzi, gdy reguła zostanie złamana.

Prompt do skopiowania: ADR i reguła, która go egzekwuje

Read docs/architecture/payments-options.md, the spike verdicts in it, and docs/architecture/results-rest.md and results-events.md.

1. Write docs/adr/0007-extract-payments-service.md with these sections: Context, Decision, Options considered (one line each, with the evidence that ruled it out), Consequences, Rollback plan per migration phase, and Enforcement.
2. Under Enforcement, add a dependency-cruiser rule to .dependency-cruiser.cjs that forbids any import of src/services/payments/** from outside that folder except through src/services/payments/client.ts. Name the rule after the ADR. Set the rule's severity to "error".
3. Add a short "Payments boundary" section to AGENTS.md: two or three sentences stating the rule and linking the ADR.
4. Run npx dependency-cruiser@18.4.0 src --config .dependency-cruiser.cjs and show me the output. List every current violation instead of fixing it.

Obecne naruszenia stają się listą prac migracji, a reguła nie pozwala dodać nowych, dopóki migracja trwa, ale tylko wtedy, gdy CI ją uruchamia i może na niej zawieść. Prompt ustawia w regule severity na "error", więc dependency-cruiser kończy się niezerowym kodem przy naruszeniu; sprawdź, czy tak się stało, i dodaj ten krok do CI:

npx dependency-cruiser@18.4.0 src --config .dependency-cruiser.cjs

Pełne zadanie CI pokazuje przewodnik po funkcjach dopasowania. Znajdziesz tam też odpowiedniki tej reguły dla Pythona i Javy, a o tym, jak utrzymać AGENTS.md na tyle krótki, żeby był użyteczny, mówi strona optymalizacja AGENTS.md.

Przejrzyj projekt i pilnuj dryfu

Zanim gałąź z projektem zostanie scalona, zamów niezależny przegląd. codex review --base main daje ogólny przegląd gałęzi, ale nie przyjmie własnej listy kontrolnej: w Codex CLI 0.157.1 codex review przyjmuje własne instrukcje tylko wtedy, gdy nie podasz --base, --commit ani --uncommitted, a --base main "…" kończy się błędem argumentów. Przegląd pod kątem architektury uruchom więc jako codex exec tylko do odczytu na diffie gałęzi:

Prompt do skopiowania: przegląd projektu względem gałęzi bazowej

codex exec -s read-only -c model_reasoning_effort="high" "Review the diff of this branch against main (git diff main...HEAD) for architecture decisions, not style. Check: the API boundary in docs/adr/0007-extract-payments-service.md matches the endpoints in code; no shared table survives in the final phase; every migration phase has a rollback that is actually possible; the dependency-cruiser rule matches the ADR. Flag anything that makes rollback hard, with file:line."

Na GitHubie wspomnij @codex review w pull requeście; Codex stosuje też reguły przeglądu zapisane w AGENTS.md (dokumentacja integracji z GitHubem od OpenAI, sprawdzona 2026-08-28). Konfigurację opisuje strona code review z Codeksem.

Przez miesiące trwania migracji uruchamiaj co tydzień kontrolę dryfu jako automatyzację Codeksa w aplikacji desktopowej albo jako zaplanowane zadanie codex exec w CI; oba warianty pokazuje strona zaplanowane automatyzacje Codeksa. Przekaż jej ADR i poproś o raport nowych importów przez granicę, nowych endpointów dodanych do monolitu zamiast do serwisu oraz sekcji ADR, które nie zgadzają się już z kodem. Blokowanie zostaw regule dependency-cruiser; automatyzacja zgłasza to, czego reguła statyczna nie widzi.

Skąd wiesz, że projekt jest dobry, bez czytania każdej linii?

Nikt nie powinien czytać każdej linii dwóch prototypów i trzech spike’ów. Każdy rodzaj tezy sprawdzaj dowodem, który go potwierdza:

Teza	Dowód	Kto zatwierdza
„Mapa jest kompletna”	Każda krawędź zacytowana jako path:line; zero niewyjaśnionych różnic względem wyniku dependency-cruiser; wyrywkowo sprawdzasz trzy cytowania	Programista, który odpowiada za moduł
„Granica się utrzyma”	Obie próby w chmurze dają ten sam werdykt, a oznaczone odczyty mają uzgodnioną poprawkę	Tech lead
„Migracja jest bezpieczna”	Wynik porównania wierszy ze spike’a, odtworzony przypadek awarii i pisemny rollback dla każdego etapu	Tech lead i właściciel bazy danych
„Projekt A jest lepszy od B”	Oba prototypy przeszły te same 10 zacommitowanych scenariuszy; tabele wyników pochodzą ze scripts/run-scenarios.sh, a nie z podsumowania Codeksa	Zespół, na jednym spotkaniu przeglądowym
„Decyzja się utrzyma”	Reguła dependency-cruiser działa w CI z severity: "error" i powoduje niepowodzenie buildu przy celowym naruszeniu testowym	Tech lead

Ostatni wiersz zespoły najczęściej pomijają. Dodaj na gałęzi jednorazowy import przez granicę i upewnij się, że CI robi się czerwone, zanim zaufasz regule.

Kiedy projektowanie systemu z Codeksem idzie źle

Mapa pomija ukryte sprzężenia. Codex znajduje importy i wywołania, ale może przeoczyć sprzężenia przez wspólne wartości konfiguracji, granice transakcji albo middleware wstrzykujące zależności w czasie działania. Wyjście: porównaj sekcję „Not visible statically” z wynikiem narzędzia, a potem dodaj logowanie w trzech punktach integracji wskazanych przez Codeksa i uruchom testy płatności, żeby zobaczyć, co naprawdę przechodzi przez granicę.

Kod ze spike’a trafia na produkcję. Spike’i z założenia pomijają obsługę błędów i bezpieczeństwo. Wyjście: nigdy nie uruchamiaj codex cloud apply na spike’u; każdy prompt spike’a zaczynaj od „Spike, not production code”, a wybrany projekt zbuduj od nowa na podstawie ADR w świeżym zadaniu.

Dwie próby się nie zgadzają. Przy --attempts 2 różne werdykty oznaczają, że odpowiedź zależy od czegoś, czego prompt nie ustalił. Wyjście: porównaj próby przez codex cloud diff TASK_ID --attempt N, znajdź założenie, w którym się różnią, dopisz je do promptu i uruchom zadanie ponownie.

Prototypów nie da się porównać. Jeden prototyp przedefiniował scenariusz albo mierzył opóźnienie inaczej. Wyjście: plik ze scenariuszami jest zacommitowany, zanim ruszą prototypy, a prompt zabrania jego edycji; scripts/run-scenarios.sh uruchom sam w obu worktree, zamiast ufać któremukolwiek podsumowaniu.

Sesja gubi wątek w dużym monolicie. Domyślne okno kontekstu Codeksa (zob. przegląd modeli) ma skończoną pojemność, a pełna mapa dużego monolitu razem z dyskusją o wariantach potrafi je zapełnić. Wyjście: każdy krok prowadź w osobnej sesji i przekazuj stan przez pliki w docs/architecture/, a nie przez rozmowę.

Dokumentacja architektury się dezaktualizuje. Migracja, która trwa trzy miesiące, w drugim miesiącu odbiega już od planu. Wyjście: reguła w CI blokuje nowe naruszenia, cotygodniowy raport dryfu wypisuje resztę, a jedna wskazana osoba odpowiada za aktualizację ADR, gdy raport znajdzie rozbieżność.

Co dalej z wydzielaniem płatności

Decyzje architektoniczne, których agenci przestrzegają Metoda niezależna od narzędzia: krótkie ADR-y plus ograniczenia sprawdzalne maszynowo

Funkcje dopasowania architektury Reguły zależności, warstw i złożoności jako bramki CI dla trzech stosów technologicznych

Modernizacja bazy kodu z Codeksem Przeprowadź migrację falami, gdy projekt jest już zdecydowany

Analiza architektury z Claude Code Ten sam przepływ projektowania w trybie Plan w Claude Code