Werken aan multi-repo-projecten
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van de Codex Cloud-documentatie: meerdere repositories leven nu samen in een Codex Cloud-omgeving (het oude adres codex.openai.com is niet langer het toegangspunt). Bron: Codex Cloud.
De complexiteit van gedistribueerde architecturen beheren
Moderne projecten beslaan vaak meerdere repositories: een frontend, een backend, een gedeelde bibliotheek, een betaalservice. Elk heeft zijn eigen levenscyclus, CI-pipeline en beheerders. Deze opzet werkt perfect—totdat een wijziging de grenzen van repositories overschrijdt. Daar verandert Codex het spel: het kan gelijktijdig over meerdere repositories heen werken.
De werkelijke kosten van een grensoverschrijdende wijziging
Neem een routinetaak: u voegt een veld toe aan een API-respons in de backend-repository. Vervolgens moet u de API-client in de frontend-repository bijwerken, de gedeelde typen in de common-repository, de documentatie in de docs-repository en de integratietests in de e2e-repository. Geen van deze vier taken is op zich moeilijk. Samen betekenen ze vier contextwisselingen, vier branches, vier pull requests en vier kansen om er één te vergeten. In de praktijk worden de documentatie of de e2e-tests overgeslagen, en duikt het probleem drie weken later weer op als een bug die niemand terugleidt naar die oorspronkelijke commit.
Meerdere repositories coördineren
In Codex Cloud kan een omgeving meerdere GitHub-repositories samenbrengen: u selecteert ze bij het aanmaken van de omgeving, Codex stelt hun afhankelijkheden en tooling in, en elke taak die in die omgeving wordt gestart, werkt over de hele set heen. Uw prompt beschrijft vervolgens de wijziging als geheel in plaats van fragmenten te isoleren:
"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 past de wijzigingen in elke repo toe en opent gecoördineerde pull requests. Het propageren van een gedeeld type volgt dezelfde logica, met één extra vereiste dat u expliciet moet vermelden: verifieer dat de compilatie in elke getroffen repo slaagt. Zonder die instructie ontdekt u de typefout in de CI van de mobile-repository pas twee uur nadat u al het andere hebt samengevoegd.
"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."
AGENTS.md configureren in een monorepo
Als uw project een monorepo is (Turborepo, Nx, Lerna), draait de logica om: packages delen een enkele bestandsboom, en de hiërarchie van AGENTS.md-bestanden bevat de onderscheiden tussen hen. Het root-bestand beschrijft de algehele structuur en regels die overal gelden:
# 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`
Elk sub-package bouwt vervolgens voort op deze basis met zijn eigen conventies, zonder ooit te herhalen wat al in het root-bestand staat:
# 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__/
Twee referentie-workflows voor grensoverschrijdende taken
De eerste behandelt een functie die de hele keten beslaat. Let op de vierde instructie: de cross-link tussen pull requests lijkt misschien optioneel, maar het is juist wat de reviewer van de frontend-repository laat begrijpen waarom deze knop bestaat zonder de bijbehorende backend-PR op te hoeven sporen.
"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"
De tweede behandelt het migreren van een geversioneerde API. Hier is de volgorde van stappen niet cosmetisch: het garandeert dat geen enkele client halverwege de migratie vast komt te zitten, met v2 op zijn plaats en v1 nog steeds actief gedurende het migratievenster voor de consument.
"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"
Wat Codex niet voor u kan doen
Codex werkt repo per repo, in gescheiden sandboxes. Het kan niet twee repos tegelijk draaien: u kunt bijvoorbeeld niet de backend en frontend gelijktijdig starten voor een echte integratietest. Voor cross-repo-tests blijft de reeks handmatig:
- Voeg de individuele PR’s samen
- Voer integratietests uit vanuit uw CI/CD-pipeline
- Gebruik Codex om gedetecteerde problemen op te lossen
Met andere woorden, Codex garandeert consistentie van de geschreven code, nooit consistentie van het draaiende systeem. Uw CI/CD blijft de uiteindelijke arbiter, en voorzichtigheid gebiedt dat u een reeks gecoördineerde PR’s niet deployt totdat deze zijn oordeel heeft geveld.
Belangrijkste punten
- Codex kan gecoördineerde PR’s maken over meerdere repositories heen
- Gedeelde typen zijn een ideaal gebruiksscenario voor multi-repo-workflows
- Configureer AGENTS.md in elk package van een monorepo
- Cross-repo-integratietests moeten nog steeds worden geverifieerd in CI/CD
- Documenteer inter-repo-afhankelijkheden in AGENTS.md