Rad na projektima s više repozitorija
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju dokumentacije Codex Cloud: više repozitorija sada živi zajedno u okruženju Codex Cloud (stara adresa codex.openai.com više nije ulazna točka). Izvor: Codex Cloud.
Upravljanje složenošću distribuiranih arhitektura
Suvremeni projekti često obuhvaćaju više repozitorija: frontend, backend, zajedničku knjižnicu, uslugu plaćanja. Svaki ima svoj životni ciklus, CI pipeline i održavatelje. Ova postavka savršeno funkcionira – sve dok promjena ne prijeđe granice repozitorija. Tu Codex mijenja pravila igre: može raditi istovremeno kroz više repozitorija.
Stvarna cijena promjene koja zahvaća više sustava
Razmotri rutinski zadatak: dodaješ polje u API odgovor u backend repozitoriju. Zatim moraš ažurirati API klijenta u frontend repozitoriju, zajedničke tipove u zajedničkom repozitoriju, dokumentaciju u docs repozitoriju i integracijske testove u e2e repozitoriju. Nijedan od ova četiri zadatka nije težak sam po sebi. Zajedno, oni znače četiri promjene konteksta, četiri grane, četiri pull requesta i četiri prilike da nešto zaboraviš. U praksi se dokumentacija ili e2e testovi preskoče, a problem se ponovno pojavi tri tjedna kasnije kao bug koji nitko ne može povezati s tim izvornim commitom.
Koordinacija više repozitorija
U Codex Cloudu, okruženje može objediniti više GitHub repozitorija: odabereš ih prilikom stvaranja okruženja, Codex postavlja njihove ovisnosti i alate, a svaki zadatak pokrenut u tom okruženju radi na cijelom skupu. Tvoj upit zatim opisuje promjenu kao cjelinu umjesto da izolira fragmente:
"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 primjenjuje promjene u svakom repozitoriju i otvara koordinirane pull requestove. Propagiranje zajedničkog tipa slijedi istu logiku, uz jedan dodatni zahtjev koji moraš eksplicitno navesti: provjeri uspješnost kompajliranja u svakom zahvaćenom repozitoriju. Bez te instrukcije, grešku tipa u CI-u mobilnog repozitorija otkrit ćeš dva sata nakon što si sve ostalo već spojio.
"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."
Konfiguriranje AGENTS.md u monorepu
Ako je tvoj projekt monorepo (Turborepo, Nx, Lerna), logika se okreće: paketi dijele jedno stablo datoteka, a hijerarhija datoteka AGENTS.md nosi razlike između njih. Korijenska datoteka opisuje ukupnu strukturu i pravila koja vrijede svugdje:
# 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`
Svaki pod-paket zatim gradi na tom temelju sa svojim vlastitim konvencijama, nikada ne ponavljajući ono što je već u korijenskoj datoteci:
# 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__/
Dva referentna tijeka rada koji zahvaćaju više repozitorija
Prvi pokriva značajku koja se proteže cijelim lancem. Obrati pozornost na četvrtu instrukciju: unakrsna poveznica između pull requestova može se činiti opcionalnom, no upravo ona omogućuje recenzentu u frontend repozitoriju da razumije zašto taj gumb postoji, a da ne mora loviti odgovarajući backend PR.
"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 pokriva migraciju verzioniranog API-ja. Ovdje redoslijed koraka nije kozmetičke prirode: jamči da nijedan klijent neće ostati zaglavljen usred migracije, s v2 na mjestu, a v1 još uvijek živim tijekom prozora migracije potrošača.
"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"
Što Codex ne može učiniti za tebe
Codex radi repozitorij po repozitorij, u odvojenim sandboxima. Ne može pokrenuti dva repozitorija zajedno: na primjer, ne možeš istovremeno pokrenuti backend i frontend za pravi integracijski test. Za testove između repozitorija, slijed ostaje ručan:
- Spoji pojedinačne PR-ove
- Pokreni integracijske testove iz svog CI/CD pipelinea
- Iskoristi Codex za ispravljanje svih otkrivenih problema
Drugim riječima, Codex jamči dosljednost napisanog koda, nikada dosljednost sustava u izvršavanju. Tvoj CI/CD ostaje konačni arbitar, a oprez nalaže da ne deployaš niz koordiniranih PR-ova dok on ne donese svoju presudu.
Ključne točke
- Codex može stvoriti koordinirane PR-ove kroz više repozitorija
- Zajednički tipovi idealan su slučaj upotrebe za tijekove rada s više repozitorija
- Konfiguriraj AGENTS.md u svakom paketu monorepa
- Integracijske testove između repozitorija i dalje treba verificirati u CI/CD-u
- Dokumentiraj međurepozitorijske ovisnosti u AGENTS.md