Budowanie funkcji z równoległymi agentami

Twój product manager właśnie podzielił jeden epic na pięć podzadań: nowy endpoint API, migracja bazy danych, formularz frontendowy, powiadomienia email i testy end-to-end. Tradycyjnie realizowałbyś je sekwencyjnie — każde blokujące przez poprzednie. Z worktree Codex możesz uruchomić pięciu równoległych agentów, którzy pracują nad wszystkimi pięcioma jednocześnie, każdy w swojej izolowanej gałęzi. Przeglądasz diffy, synchronizujesz wyniki i wdrażasz całą funkcję w jedno popołudnie.

Co wyniesiesz z tej lekcji

Workflow planuj-potem-zrównoleglaj, który rozbija funkcje na niezależne strumienie pracy
Prompty do lokalnego planowania w rozszerzeniu IDE, po którym następuje równoległe wykonanie w worktree
Techniki łączenia wyników z wielu worktree w jedną gałąź funkcji
Wzorzec delegowania do chmury dla długotrwałych zadań implementacyjnych

Workflow

Krok 1: Zaplanuj lokalnie w IDE

Zanim uruchomisz jakichkolwiek równoległych agentów, potrzebujesz planu, który rozkłada pracę na niezależne części. Użyj do tego rozszerzenia IDE — ma kontekst twoich otwartych plików i szybko odpowiada na zadania planistyczne.

Gotowy prompt do dekompozycji funkcji:

I need to implement a user notification preferences feature:

- Users can choose email, SMS, or push for each notification type
- Preferences are stored in the database
- A new API endpoint manages CRUD for preferences
- The notification service reads preferences before sending
- Frontend settings page for managing preferences

Break this into independent implementation tasks that can run in parallel. For each task:
1. What files need to be created or modified
2. What the task depends on (if anything)
3. A clear "definition of done" including tests

Identify which tasks can run simultaneously and which must be sequential.

Codex zazwyczaj zidentyfikuje graf zależności. Na przykład migracja bazy danych musi wejść pierwsza, potem endpoint API i zmiany w serwisie powiadomień mogą biec równolegle, a frontend zależy od zdefiniowanego API. Plan pozwala ci wiedzieć, które worktree uruchomić natychmiast, a które kolejkować.

Krok 2: Zacznij od fundamentów w trybie Local

Dla zadań, od których zależy inna praca — jak migracja bazy danych — użyj trybu Local, aby zmiany trafiły bezpośrednio do twojego katalogu roboczego, a kolejne worktree mogły na nich budować.

Gotowy prompt do pracy fundamentowej:

Create a database migration for notification preferences:

- New table: notification_preferences
  - id (uuid, primary key)
  - user_id (uuid, foreign key to users, unique per notification_type)
  - notification_type (enum: order_update, marketing, security_alert, system)
  - channel (enum: email, sms, push)
  - enabled (boolean, default true)
  - created_at, updated_at timestamps

- Use Drizzle ORM schema definition matching our existing patterns
- Generate the migration file
- Add the schema to our barrel export in src/lib/db/schema.ts
- Run the migration against the dev database

Follow conventions in AGENTS.md.

Zacommituj migrację do swojej gałęzi funkcji. Teraz każdy worktree, który utworzysz z tej gałęzi, będzie zawierać nowy schemat.

Krok 3: Uruchom równoległe wątki Worktree

Teraz niezależne części mogą biec jednocześnie. W Codex App utwórz nowy wątek dla każdego zadania, wybierając tryb Worktree i wskazując gałąź funkcji (z już zacommitowaną migracją) jako punkt wyjścia.

Wątek 1: Endpoint API

Implement CRUD endpoints for notification preferences:

- GET /api/users/:userId/notification-preferences
- PUT /api/users/:userId/notification-preferences/:type
- Zod validation for all inputs
- Auth middleware (user can only access their own preferences)
- Default preferences created on first GET if none exist
- Unit tests for validation, integration tests for the full endpoint

Use the notification_preferences schema from src/lib/db/schema.ts.
Run tests after implementation.

Wątek 2: Aktualizacja serwisu powiadomień

Update the notification service to check user preferences before sending:

- Before sending any notification, query notification_preferences for the user
- If no preferences exist, use defaults (all channels enabled)
- If the user has disabled a channel for that notification type, skip it
- Add structured logging for skipped notifications
- Unit tests with mocked preferences
- Do not change the existing notification sending interface

Read the current notification service in src/services/notifications/ first.

Wątek 3: Strona ustawień frontendowych

Create a notification preferences settings page:

- Route: /settings/notifications
- Fetch current preferences from GET /api/users/:userId/notification-preferences
- Display a grid: notification types as rows, channels as columns
- Toggle switches for each combination
- Save changes with PUT on toggle
- Loading states and error handling
- Match the existing settings page styling in src/pages/settings/

Use React and follow our component patterns. Include tests.

Wszystkie trzy wątki biegną jednocześnie w oddzielnych worktree. Możesz obserwować ich postęp na pasku bocznym Codex App, przełączać się między wątkami i zostawiać komentarze inline, jeśli zauważysz coś wymagającego korekty.

Krok 4: Przejrzyj i połącz wyniki

Gdy każdy wątek zakończy pracę, przejrzyj diff w panelu recenzji. Masz dwie strategie na odzyskanie zmian:

Strategia A: Utwórz gałęzie i połącz przez Git. Kliknij Create branch here na każdym wątku worktree. Wypchnij każdą gałąź i dołącz je do gałęzi funkcji po kolei, rozwiązując ewentualne konflikty.

Strategia B: Synchronizuj do lokalnego sekwencyjnie. Użyj Sync with local na każdym worktree, wybierając metodę Apply, aby nałożyć każdy zestaw zmian na lokalny checkout. To utrzymuje czystszą historię commitów, ponieważ zmiany przychodzą jako patche, a nie merge commity.

Krok 5: Deleguj długie zadania do chmury

Dla zadań, które trwają dłużej — uruchamianie pełnych zestawów testów, budowanie kontenerów lub implementowanie złożonej logiki biznesowej — deleguj do wykonania w chmurze. Agent chmurowy ma więcej zasobów, może działać dłużej i wspiera próby best-of-N.

W Codex App wybierz ikonę chmury pod edytorem i wybierz swoje środowisko chmurowe:

Implement Milestone 1 from the plan: the notification preferences API endpoints with full test coverage. Run the complete test suite after implementation and fix any failures.

Zadania chmurowe generują diff, który możesz przejrzeć i zamienić bezpośrednio w PR lub pobrać lokalnie do dalszej iteracji.

Gdy coś się nie uda

Worktree współdzielą node_modules przez git worktree, ale nie zawsze. Jeśli twój projekt ma zależności na poziomie workspace, worktree powinny je dziedziczyć. Ale jeśli każdy worktree uruchamia npm install niezależnie, możesz napotkać konflikty lockfile. Skonfiguruj skrypt konfiguracyjny środowiska lokalnego, aby używał npm ci (który respektuje lockfile) zamiast npm install.

Równoległe wątki podejmują sprzeczne decyzje architektoniczne. Jeśli wątek 1 decyduje, że format odpowiedzi powinien być { data: [...] }, a wątek 2 oczekuje { preferences: [...] }, nie zintegrują się czysto. Dlatego krok 1 jest ważny — plan powinien określać współdzielone interfejsy przed rozpoczęciem pracy równoległej.

Czyszczenie worktree usuwa wątek, którego potrzebowałeś. Worktree kwalifikują się do czyszczenia po 4 dniach lub gdy przekroczysz 10 łącznie. Przypnij ważne wątki lub dodaj worktree do paska bocznego, aby zapobiec automatycznemu usuwaniu. Jeśli worktree został już wyczyszczony, Codex zapisuje migawkę, z której możesz przywrócić dane z widoku wątku.

Zadanie chmurowe używa złej gałęzi. Zadania chmurowe domyślnie korzystają z domyślnej gałęzi repozytorium. Jeśli twoja migracja fundamentowa jest na gałęzi funkcji, agent chmurowy nie zobaczy nowego schematu. Określ gałąź jawnie w ustawieniach środowiska chmurowego lub opisz schemat w prompcie.

Co dalej

Debugowanie z Codex na różnych powierzchniach Gdy twoje równoległe funkcje tworzą nieoczekiwane interakcje, debuguj je efektywnie

Wieloagentowa równoległa praca nad funkcjami Skaluj wzorzec równoległych worktree do koordynowania całych zespołów agentów