Przejdź do głównej treści
Polski— Wybierz język
Menu

Praca nad projektami wielorepozytoryjnymi

Lekcja 13 z 20 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zarządzanie złożonością architektur rozproszonych
  2. Rzeczywisty koszt zmian obejmujących wiele warstw
  3. Koordynacja wielu repozytoriów
  4. Konfigurowanie pliku AGENTS.md w monorepo
  5. Dwa referencyjne przepływy pracy obejmujące wiele repozytoriów
  6. Czego Codex nie zrobi za Ciebie
  7. Kluczowe wnioski

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:

  1. Scal poszczególne pull requesty
  2. Uruchom testy integracyjne z poziomu swojego potoku CI/CD
  3. 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