Praca nad projektami wielorepozytoryjnymi
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 r. na podstawie dokumentacji Codex Cloud: wiele repozytoriów funkcjonuje teraz wspólnie w środowisku Codex Cloud (stary adres codex.openai.com nie jest już punktem wejścia). Źródło: Codex Cloud.
Zarządzanie złożonością architektur rozproszonych
Nowoczesne projekty często obejmują wiele repozytoriów: frontend, backend, bibliotekę współdzieloną, usługę płatności. Każde z nich ma własny cykl życia, potok CI i opiekunów. Taki układ działa idealnie – dopóki zmiana nie przekroczy granic repozytoriów. W tym miejscu Codex zmienia zasady gry: potrafi pracować jednocześnie nad wieloma repozytoriami.
Rzeczywisty koszt zmian obejmujących wiele warstw
Rozważ typowe zadanie: dodajesz pole do odpowiedzi API w repozytorium backendu. Następnie musisz zaktualizować klienta API w repozytorium frontendu, wspólne typy w repozytorium common, dokumentację w repozytorium docs oraz testy integracyjne w repozytorium e2e. Żadne z tych czterech zadań nie jest trudne samo w sobie. Razem oznaczają cztery przełączenia kontekstu, cztery gałęzie, cztery pull requesty i cztery szanse na zapomnienie o jednym elemencie. W praktyce dokumentacja lub testy e2e zostają pominięte, a problem pojawia się ponownie trzy tygodnie później jako błąd, którego nikt nie potrafi powiązać z tamtym oryginalnym committem.
Koordynacja wielu repozytoriów
W Codex Cloud środowisko może łączyć wiele repozytoriów GitHub: wybierasz je podczas tworzenia środowiska, Codex konfiguruje ich zależności i narzędzia, a każde zadanie uruchomione w tym środowisku działa na całym zestawie. Twój prompt opisuje wówczas zmianę jako całość, zamiast izolować fragmenty:
"In the backend repo (api-service):
- Add a GET /api/v2/products endpoint with pagination
In the frontend repo (web-app):
- Update the API client to use the new endpoint
- Add pagination to the ProductList component"
Codex wprowadza zmiany w każdym repozytorium i otwiera skoordynowane pull requesty. Propagowanie wspólnego typu遵循 tę samą logikę, z jednym dodatkowym wymogiem, który musisz wyraźnie zaznaczyć: zweryfikuj, czy kompilacja kończy się sukcesem w każdym dotkniętym repozytorium. Bez tej instrukcji odkryjesz błąd typów w potoku CI repozytorium mobilnego dwie godziny po scaleniu wszystkiego innego.
"The Product type in shared-types/src/product.ts has been
modified (added tags: string[] field).
Update all usages in:
- api-service: routes and services that use Product
- web-app: components that display a Product
- mobile-app: screens that display a Product
Ensure each repo compiles without errors."
Konfigurowanie pliku AGENTS.md w monorepo
Jeśli Twój projekt jest monorepo (Turborepo, Nx, Lerna), logika się odwraca: pakiety współdzielą pojedyncze drzewo plików, a hierarchia plików AGENTS.md przenosi rozróżnienia między nimi. Plik główny opisuje ogólną strukturę i zasady obowiązujące wszędzie:
# AGENTS.md (monorepo root)
## Structure
Turborepo monorepo with the following packages:
- packages/api — Fastify backend
- packages/web — Next.js frontend
- packages/shared — Shared types and utilities
- packages/e2e — Playwright end-to-end tests
## Rules
- Changes to packages/shared MUST be followed by a build
of all dependent packages
- Global build command: `turbo run build`
- Global test command: `turbo run test`
Każdy podpakiet buduje następnie na tej podstawie, stosując własne konwencje, bez powtarzania tego, co znajduje się już w pliku głównym:
# packages/api/AGENTS.md
## Backend API
- Framework: Fastify
- Validation: Zod (schemas in src/schemas/)
- Types from packages/shared are imported via @myorg/shared
- Every new route requires a test in __tests__/
Dwa referencyjne przepływy pracy obejmujące wiele repozytoriów
Pierwszy dotyczy funkcji obejmującej cały łańcuch. Zwróć uwagę na czwartą instrukcję: łącze między pull requestami może wydawać się opcjonalne, ale to właśnie ono pozwala recenzentowi repozytorium frontendu zrozumieć, dlaczego ten przycisk istnieje, bez konieczności tropienia odpowiadającego mu pull requesta w backendzie.
"New feature: favorites system.
1. shared-types: Add the Favorite type
2. api-service: CRUD /api/favorites with auth
3. web-app: Heart button on product cards
4. Create a PR in each repo with links
to the other repos' PRs in the description"
Drugi dotyczy migracji wersjonowanego API. Tutaj kolejność kroków nie jest kosmetyczna: gwarantuje, że żaden klient nie zostanie porzucony w trakcie migracji, przy czym v2 jest już dostępne, a v1 nadal działa przez cały okres migracji po stronie konsumenta.
"API v1 /users is deprecated. Create v2:
1. api-service: Add v2 routes with the new format
2. api-service: Mark v1 routes as deprecated (header)
3. web-app: Migrate all calls from v1 to v2
4. mobile-app: Migrate all calls from v1 to v2
5. docs: Update the API documentation"
Czego Codex nie zrobi za Ciebie
Codex pracuje repozytorium po repozytorium, w oddzielnych piaskownicach. Nie może uruchomić dwóch repozytoriów jednocześnie: na przykład nie możesz uruchomić backendu i frontendu równocześnie w celu przeprowadzenia rzeczywistego testu integracyjnego. W przypadku testów międzyrepozytoryjnych sekwencja pozostaje manualna:
- Scal poszczególne pull requesty
- Uruchom testy integracyjne z poziomu swojego potoku CI/CD
- Wykorzystaj Codex do naprawy wszelkich wykrytych problemów
Innymi słowy, Codex gwarantuje spójność napisanego kodu, nigdy zaś spójność działającego systemu. Twój potok CI/CD pozostaje ostatecznym arbitrem, a ostrożność nakazuje, abyś nie wdrażał serii skoordynowanych pull requestów, dopóki nie wyda on swojego werdyktu.
Kluczowe wnioski
- Codex może tworzyć skoordynowane pull requesty w wielu repozytoriach
- Wspólne typy stanowią idealny przypadek użycia dla przepływów pracy wielorepozytoryjnych
- Skonfiguruj plik AGENTS.md w każdym pakiecie monorepo
- Testy integracyjne międzyrepozytoryjne muszą być nadal weryfikowane w CI/CD
- Udokumentuj zależności międzyrepozytoryjne w pliku AGENTS.md