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
Dział zatytułowany „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
Dział zatytułowany „Przepływ pracy”Krok 1: Przeanalizuj obecną architekturę
Dział zatytułowany „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.
Krok 2: Zaprojektuj docelową architekturę
Dział zatytułowany „Krok 2: Zaprojektuj docelową architekturę”Po zakończeniu analizy zaprojektuj nową architekturę. Użyj umiejętności $plan, jeśli jest dostępna, lub strukturalnego promptu planistycznego w aplikacji Codex:
Krok 3: Zwaliduj z zadaniami w chmurze
Dział zatytułowany „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
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
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 databases3. Measure the latency overhead of each approach4. 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
Dział zatytułowany „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
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
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ę
Dział zatytułowany „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 strategy6. 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:
Używanie Codex do przeglądów projektowych
Dział zatytułowany „Używanie Codex do przeglądów projektowych”Przed zatwierdzeniem architektury uzyskaj przegląd projektowy. Użyj /review z niestandardowym fokusem:
/review 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 przegląd projektowy na 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
Dział zatytułowany „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.