Projektowanie systemów z Codex

Twój monolit urósł do punktu, w którym każde wdrożenie to 45-minutowa przygoda w stylu “czy to zepsuje coś niezwiązanego?” Zespół zdecydował się wyodrębnić moduł płatności do osobnego serwisu, ale nikt nie może się zgodzić co do granicy API, strategii migracji danych ani sposobu obsługi okresu przejściowego, gdy oba systemy działają jednocześnie. Decyzje architektoniczne takie jak ta są zbyt ważne, aby się spieszyć, i zbyt złożone, aby mieściły się w głowie jednej osoby. Codex daje ci iteracyjny proces projektowania: planuj w IDE z pełnym kontekstem bazy kodu, waliduj założenia z zadaniami w chmurze i eksploruj alternatywy w równoległych worktree.

Czego się nauczysz

Wielopowierzchniowy przepływ planowania architektonicznego wykorzystujący IDE do projektowania i chmurę do walidacji
Prompty do dekompozycji monolitów, projektowania granic API i planowania migracji danych
Techniki oceniania alternatyw architektonicznych z równoległymi zadaniami w chmurze
Przepis na automatyzację wykrywania dryfu architektonicznego w czasie

Przepływ pracy

Krok 1: Przeanalizuj obecną architekturę

Przed projektowaniem nowej architektury zrozum, co masz. Użyj rozszerzenia IDE z włączonym auto-kontekstem — widzi twoje otwarte pliki i daje szybkie odpowiedzi na pytania analityczne.

Prompt do skopiowania — analiza architektoniczna:

Analyze the current architecture of this monolith, focusing on the payments module:

1. Map every file in src/services/payments/ and src/routes/payments/
2. Identify all inbound dependencies (who calls into the payments module)
3. Identify all outbound dependencies (what the payments module calls)
4. Map shared database tables (tables used by payments AND other modules)
5. Identify shared state (caches, queues, configuration) between payments and other modules
6. List every API endpoint that the payments module exposes
7. Estimate the "blast radius" -- what breaks if you rip out src/services/payments/ entirely

Present the dependency graph as a text diagram. Highlight the three most tightly coupled integration points.

Krok 2: Zaprojektuj docelową architekturę

Po zakończeniu analizy zaprojektuj nową architekturę. Codex dostarcza eksperymentalną umiejętność $create-plan, która strukturyzuje przebieg planowania — zainstaluj ją raz poleceniem $skill-installer install the create-plan skill from the .experimental folder, a następnie wywołaj ją wewnątrz strukturalnego promptu planistycznego w aplikacji Codex. (Jedyne umiejętności dołączone domyślnie to $skill-creator i $skill-installer; $create-plan trzeba zainstalować przed pierwszym użyciem.)

Prompt do skopiowania — projektowanie architektury:

$create-plan

Design the architecture for extracting the payments module into a separate service.

Constraints:
- Zero downtime during migration (both systems run simultaneously during transition)
- No data loss -- all payment records must be accessible throughout
- Existing API consumers must not break (backward-compatible interface)
- The new service must own its own database (no shared tables in the final state)
- Communication between services via REST API initially (event-driven later)

Design decisions needed:
1. API boundary: which endpoints move to the new service, which stay
2. Data migration: how to split the shared tables without downtime
3. Transition period: how calls are routed during migration (proxy, feature flags, etc.)
4. Authentication: how the services authenticate with each other
5. Error handling: what happens when the payment service is down

For each decision, propose 2-3 options with trade-offs.
Recommend one option per decision with justification.
Include a phased migration plan with clear milestones.

Krok 3: Zwaliduj z zadaniami w chmurze

Plany architektoniczne wymagają walidacji. Użyj zadań w chmurze, aby przetestować konkretne założenia dotyczące projektu.

Walidacja 1: Wykonalność granicy API

Prompt do skopiowania — walidacja granicy API w chmurze:

codex cloud exec --env arch-test "Test the proposed API boundary for the payments service extraction.

Create a minimal Express server that exposes the 6 payment endpoints from the design plan:
- POST /payments/charge
- POST /payments/refund
- GET /payments/:id
- GET /payments/customer/:customerId
- POST /payments/webhooks/stripe
- POST /payments/webhooks/paypal

For each endpoint, verify that the request/response can be served without accessing any database tables outside of the payments schema. If an endpoint requires data from the users or orders table, report the dependency and suggest how to resolve it (pass the data as a parameter, or the caller enriches the request before forwarding).

Run the existing payment-related tests against this server to verify coverage."

Walidacja 2: Strategia migracji danych

Prompt do skopiowania — porównanie strategii migracji danych w chmurze:

codex cloud exec --env arch-test --attempts 2 "Test two data migration approaches for the payments extraction:

Approach A (dual-write): During migration, all writes go to both the monolith DB and the new service DB. Reads gradually shift to the new service.

Approach B (CDC): Use change data capture to replicate the payments tables to the new service's database. Switch reads to the new service when replication lag is acceptable.

For each approach:
1. Write a proof-of-concept implementation (enough to test the concept)
2. Simulate 1000 writes and verify data consistency between both databases
3. Measure the latency overhead of each approach
4. Identify failure modes (what happens if the new service DB is down during a write)

Report which approach is more reliable and has lower latency overhead."

Krok 4: Eksploruj alternatywy równolegle

Dla spornych decyzji projektowych, w których zespół nie może się zgodzić, uruchom równoległe wątki eksploracyjne:

Worktree 1: Komunikacja REST API

Prompt do skopiowania — prototyp komunikacji REST:

Prototype the payments service using REST for inter-service communication.

Implement:
- A payments service with the 6 endpoints from the design
- A proxy in the monolith that forwards payment requests to the new service
- Error handling: what happens when the payment service returns 500 or times out
- Circuit breaker pattern for the proxy

Measure: latency overhead of the proxy, behavior under the payment service being down for 30 seconds.

Worktree 2: Komunikacja zdarzeniowa

Prompt do skopiowania — prototyp komunikacji zdarzeniowej:

Prototype the payments service using events for inter-service communication.

Implement:
- A payments service that emits events (payment.created, payment.refunded, etc.)
- The monolith subscribes to events and updates its local state
- Commands are still synchronous (monolith calls the payment service API)
- Event store or message queue (use Redis Streams for simplicity)

Measure: eventual consistency delay, behavior when events are lost or duplicated.

Porównaj prototypy obok siebie. Konkretne implementacje znacznie ułatwiają ocenę kompromisów niż abstrakcyjne dyskusje przy tablicy.

Krok 5: Dokumentuj i monitoruj architekturę

Po podjęciu decyzji architektonicznej udokumentuj ją i skonfiguruj monitorowanie dryfu:

Create docs/ARCHITECTURE-PAYMENTS.md documenting the payments service extraction:

1. Target architecture diagram (text-based)
2. API boundary definition (endpoints, request/response schemas)
3. Data ownership map (which tables belong to which service)
4. Communication patterns (synchronous calls, events)
5. Migration plan with phases and rollback strategy
6. Decision log: key decisions made and the reasoning behind each one

Format for an audience of senior engineers who will implement the migration.

Skonfiguruj cotygodniową automatyzację do wykrywania dryfu architektonicznego:

Prompt automatyzacji do skopiowania — monitorowanie architektury:

Weekly architecture compliance check for the payments extraction:

1. Verify no new direct database queries from the monolith to payment-owned tables (check for imports of payment table schemas outside src/services/payments/)
2. Verify no new direct function calls between the monolith and payment service (all communication should go through the API proxy)
3. Check that new payment-related endpoints are added to the new service, not the monolith
4. Verify that the API boundary documentation in docs/ARCHITECTURE-PAYMENTS.md matches the actual endpoints

If any violations are found, report them with file paths and explain which architectural rule was broken.

Używanie Codex do przeglądów projektowych

Przed zatwierdzeniem architektury uzyskaj przegląd projektowy. W CLI uruchom /review, aby rozpocząć przegląd drzewa roboczego, a następnie pokieruj nim wiadomością uzupełniającą:

/review

Gdy przegląd się rozpocznie, wyślij fokus jako kolejną wiadomość:

Focus on the architectural decisions in this branch. Are the API boundaries clean? Is the data migration strategy sound? Are there coupling points that will cause problems during the transition? Flag anything that will make rollback difficult.

Lub poproś o ukierunkowany przegląd projektowy na GitHub, wspominając Codex w PR. Sufiks for <focus> to udokumentowany sposób na zawężenie zakresu przeglądu GitHub:

@codex review for architectural soundness. Focus on: separation of concerns between the monolith and the new payments service, data consistency during migration, and failure mode handling.

Kiedy to nie działa

Analiza pomija ukryte powiązania. Codex znajduje jawne importy i wywołania funkcji, ale może pominąć niejawne powiązania: współdzielone wartości konfiguracji, założenia dotyczące granic transakcji bazodanowych lub zależności runtime wstrzykiwane przez middleware. Po analizie ręcznie zweryfikuj trzy najważniejsze punkty integracji zidentyfikowane przez Codex, śledząc je w debuggerze lub z logowaniem.

Walidacja w chmurze używa uproszczonego testu, który nie odzwierciedla złożoności produkcji. Proof-of-concept z 1000 zapisów nie ujawnia problemów pojawiających się przy 10 milionach zapisów. Użyj walidacji w chmurze do testowania poprawności i identyfikacji oczywistych awarii, a następnie zaplanuj bardziej realistyczny test obciążeniowy na środowisku staging.

Równoległe wątki prototypowe przyjmują różne założenia. Jeśli prototyp REST zakłada synchroniczne zapisy, a prototyp zdarzeniowy zakłada spójność ostateczną, nie porównujesz jabłek z jabłkami. Zdefiniuj kryteria porównania z góry: “Both prototypes must handle the same 10 test scenarios. Report latency, consistency guarantee, and failure behavior for each scenario.”

Dokumentacja architektury starzeje się natychmiast. Migracja trwa trzy miesiące. W drugim miesiącu faktyczna implementacja odbiega od udokumentowanego planu. Cotygodniowa automatyzacja pomaga wyłapać dryf, ale działa tylko wtedy, gdy ktoś reaguje na ustalenia. Przydziel konkretną osobę (lub rotuj odpowiedzialność) do przeglądania skrzynki automatyzacji i aktualizowania dokumentów.

Co dalej

Modernizacja bazy kodu na skalę Zastosuj planowanie architektoniczne do modernizacji starszego kodu

Wieloagentowa równoległa praca nad funkcjonalnościami Użyj wzorców równoległych worktree do implementacji planu architektonicznego