Arbeiten an Projekten mit mehreren Repositories
Auf dieser Seite
Lektion aktualisiert am 3. November 2026 basierend auf der Codex Cloud-Dokumentation: Mehrere Repositories leben nun gemeinsam in einer Codex Cloud-Umgebung (die alte Adresse codex.openai.com ist nicht mehr der Einstiegspunkt). Quelle: Codex Cloud.
Umgang mit der Komplexität verteilter Architekturen
Moderne Projekte erstrecken sich häufig über mehrere Repositories: eine Frontend-Anwendung, ein Backend, eine gemeinsame Bibliothek, ein Zahlungsservice. Jedes hat seinen eigenen Lebenszyklus, seine CI-Pipeline und seine Maintainer. Diese Aufteilung funktioniert einwandfrei – bis eine Änderung die Grenzen der Repositories überschreitet. Hier ändert Codex das Spiel: Er kann gleichzeitig über mehrere Repositories hinweg arbeiten.
Die tatsächlichen Kosten einer übergreifenden Änderung
Betrachten Sie eine Routineaufgabe: Sie fügen im Backend-Repository ein Feld zur API-Antwort hinzu. Anschließend müssen Sie das API-Client im Frontend-Repository, die gemeinsamen Typen im gemeinsamen Repository, die Dokumentation im docs-Repository und die Integrationstests im e2e-Repository aktualisieren. Keine dieser vier Aufgaben ist isoliert schwierig. Zusammen bedeuten sie vier Kontextwechsel, vier Branches, vier Pull Requests und vier Gelegenheiten, etwas zu vergessen. In der Praxis werden die Dokumentation oder die e2e-Tests übersprungen, und das Problem taucht drei Wochen später als Bug wieder auf, den niemand auf den ursprünglichen Commit zurückverfolgen kann.
Koordination mehrerer Repositories
In Codex Cloud kann eine Umgebung mehrere GitHub-Repositories zusammenbringen: Sie wählen sie beim Erstellen der Umgebung aus, Codex richtet deren Abhängigkeiten und Tools ein, und jede in dieser Umgebung gestartete Aufgabe wirkt auf den gesamten Satz ein. Ihre Eingabe beschreibt die Änderung dann als Ganzes anstatt isolierter 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 wendet die Änderungen in jedem Repository an und öffnet koordinierte Pull Requests. Die Ausbreitung eines gemeinsamen Typs folgt derselben Logik, mit einer zusätzlichen Anforderung, die Sie explizit angeben sollten: Stellen Sie sicher, dass die Kompilierung in jedem betroffenen Repository erfolgreich ist. Ohne diese Anweisung entdecken Sie den Typfehler erst zwei Stunden nach dem Zusammenführen aller anderen Änderungen in der CI des mobilen Repositories.
"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."
Konfigurieren von AGENTS.md in einem Monorepo
Wenn Ihr Projekt ein Monorepo ist (Turborepo, Nx, Lerna), kehrt sich die Logik um: Pakete teilen sich einen einzigen Dateibaum, und die Hierarchie der AGENTS.md-Dateien trägt die Unterscheidungen zwischen ihnen. Die Datei an der Wurzel beschreibt die Gesamtstruktur und die Regeln, die überall gelten:
# 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`
Jedes Unterpaket baut darauf auf und definiert seine eigenen Konventionen, ohne jemals zu wiederholen, was bereits in der Wurzel-Datei steht:
# 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__/
Zwei Referenz-Workflows für übergreifende Änderungen
Der erste Workflow deckt eine Funktion ab, die die gesamte Kette durchläuft. Achten Sie auf die vierte Anweisung: Die Verknüpfung zwischen den Pull Requests mag optional erscheinen, doch sie ermöglicht es dem Prüfer im Frontend-Repository zu verstehen, warum dieser Button existiert, ohne nach dem entsprechenden Backend-Pull Request suchen zu müssen.
"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"
Der zweite Workflow betrifft die Migration einer versionierten API. Hier ist die Reihenfolge der Schritte nicht kosmetisch: Sie garantiert, dass kein Client mitten in der Migration strandet, wobei v2 bereitgestellt ist und v1 während des Migrationsfensters der Konsumenten weiterhin aktiv bleibt.
"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"
Was Codex für Sie nicht tun kann
Codex arbeitet Repository für Repository in separaten Sandboxes. Er kann zwei Repositories nicht gleichzeitig ausführen: Beispielsweise können Sie Backend und Frontend nicht gleichzeitig für einen echten Integrationstest starten. Für übergreifende Tests bleibt die Sequenz manuell:
- Zusammenführen der einzelnen Pull Requests
- Ausführen von Integrationstests aus Ihrer CI/CD-Pipeline
- Codex nutzen, um festgestellte Probleme zu beheben
Mit anderen Worten: Codex garantiert die Konsistenz des geschriebenen Codes, niemals die Konsistenz des laufenden Systems. Ihre CI/CD bleibt das letzte Urteil, und Vorsicht diktiert, dass Sie eine Reihe koordinierter Pull Requests nicht bereitstellen sollten, bis sie ihr Urteil gefällt haben.
Kernaussagen
- Codex kann koordinierte Pull Requests über mehrere Repositories hinweg erstellen
- Gemeinsame Typen sind ein idealer Anwendungsfall für Workflows mit mehreren Repositories
- Konfigurieren Sie AGENTS.md in jedem Paket eines Monorepos
- Übergreifende Integrationstests müssen weiterhin in der CI/CD verifiziert werden
- Dokumentieren Sie Abhängigkeiten zwischen Repositories in AGENTS.md