Travailler sur des projets multi-repos

Gérer la complexité des architectures distribuées

Les projets modernes se répartissent souvent sur plusieurs repositories : un frontend, un backend, une bibliothèque partagée, un service de paiement. Chacun a son cycle de vie, sa CI et ses mainteneurs, et cette organisation fonctionne parfaitement — jusqu’au jour où une modification traverse la frontière. Codex sait travailler sur plusieurs repos en même temps, ce qui change précisément la donne dans ces moments-là.

Le vrai coût d’un changement transverse

Prenez un cas banal : vous ajoutez un champ à une réponse d’API dans le repository backend. Il faut alors mettre à jour le client API dans le repository frontend, les types partagés dans le repository common, la documentation dans le repository docs et les tests d’intégration dans le repository e2e. Aucune de ces quatre tâches n’est difficile prise isolément. Ensemble, elles représentent quatre changements de contexte, quatre branches, quatre PRs et quatre occasions d’en oublier une. Dans la pratique, ce sont la documentation ou les tests e2e qui sautent, et le problème refait surface trois semaines plus tard sous la forme d’un bug que personne ne relie à ce commit.

Coordonner plusieurs repositories

Sur l’app web codex.openai.com, vous connectez plusieurs repositories de votre organisation, et chaque tâche indique explicitement les repos concernés. La demande décrit alors le changement dans son ensemble au lieu d’en isoler un fragment :

"Dans le repo backend (api-service) :
- Ajoute un endpoint GET /api/v2/products avec pagination

Dans le repo frontend (web-app) :
- Mets à jour le client API pour utiliser le nouvel endpoint
- Ajoute la pagination dans le composant ProductList"

Codex applique les modifications dans chaque repo et ouvre des PRs coordonnées. La propagation d’un type partagé suit la même logique, avec une exigence de plus qu’il vaut mieux formuler noir sur blanc : la vérification de compilation dans chacun des repos touchés. Sans cette phrase, vous découvrez l’erreur de type dans la CI du repo mobile, deux heures après avoir mergé les autres.

"Le type Product dans shared-types/src/product.ts a été 
modifié (ajout du champ tags: string[]). 
Mets à jour tous les usages dans :
- api-service : les routes et services qui utilisent Product
- web-app : les composants qui affichent un Product
- mobile-app : les écrans qui affichent un Product
Assure-toi que chaque repo compile sans erreur."

Configurer AGENTS.md dans un monorepo

Si votre projet est un monorepo (Turborepo, Nx, Lerna), la logique s’inverse : les paquets partagent un seul arbre de fichiers, et c’est la hiérarchie des AGENTS.md qui porte la distinction entre eux. Le fichier racine décrit la structure globale et les règles valables partout :

# AGENTS.md (racine du monorepo)

## Structure
Monorepo Turborepo avec les packages suivants :
- packages/api — Backend Fastify
- packages/web — Frontend Next.js
- packages/shared — Types et utilitaires partagés
- packages/e2e — Tests end-to-end Playwright

## Règles
- Les modifications de packages/shared DOIVENT être 
  suivies d'un build de tous les packages dépendants
- Commande de build global : `turbo run build`
- Commande de test global : `turbo run test`

Chaque sous-package complète ensuite ce socle avec ses conventions propres, sans jamais répéter celles du fichier racine :

# packages/api/AGENTS.md

## API Backend
- Framework : Fastify
- Validation : Zod (schémas dans src/schemas/)
- Les types de packages/shared sont importés via @myorg/shared
- Chaque nouvelle route nécessite un test dans __tests__/

Deux workflows transverses de référence

Le premier concerne une fonctionnalité qui traverse toute la chaîne. Arrêtez-vous sur la quatrième instruction : le lien croisé entre les PRs paraît accessoire, mais c’est lui qui permet au relecteur du repo frontend de comprendre pourquoi ce bouton existe sans partir à la recherche de la PR backend correspondante.

"Nouvelle feature : système de favoris.
1. shared-types : Ajoute le type Favorite
2. api-service : CRUD /api/favorites avec auth
3. web-app : Bouton coeur sur les cartes produit
4. Crée une PR dans chaque repo avec le lien 
   vers les PRs des autres repos dans la description"

Le second porte sur la migration d’une API versionnée. Ici, l’ordre des étapes n’est pas cosmétique : c’est lui qui garantit qu’aucun client ne se retrouve orphelin en cours de route, la v2 étant en place et la v1 encore vivante pendant toute la durée de la migration des consommateurs.

"L'API v1 /users est dépréciée. Crée la v2 :
1. api-service : Ajoute les routes v2 avec le nouveau format
2. api-service : Marque les routes v1 comme deprecated (header)
3. web-app : Migre tous les appels de v1 vers v2
4. mobile-app : Migre tous les appels de v1 vers v2
5. docs : Mets à jour la documentation API"

Ce que Codex ne peut pas faire pour vous

Codex travaille repo par repo, dans des sandboxes séparés. Il ne peut pas exécuter deux repos ensemble : impossible, par exemple, de lancer le backend et le frontend simultanément pour un test d’intégration réel. Pour les tests cross-repos, la séquence reste manuelle :

1. Merger les PRs individuelles
2. Lancer les tests d’intégration depuis votre CI/CD
3. Utiliser Codex pour corriger les éventuels problèmes détectés

Autrement dit, Codex garantit la cohérence du code écrit, jamais celle du système en fonctionnement. Votre CI/CD reste l’arbitre final, et la prudence commande de ne pas mettre en production une série de PRs coordonnées avant qu’elle ait rendu son verdict.

Points clés à retenir

• Codex peut créer des PRs coordonnées sur plusieurs repositories
• Les types partagés sont un cas d’usage idéal pour le multi-repos
• Configurez AGENTS.md dans chaque package d’un monorepo
• Les tests d’intégration cross-repos restent à vérifier dans la CI/CD
• Documentez les dépendances entre repos dans AGENTS.md