Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Lavorare su progetti multi-repo

Lezione 13 di 20 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Gestire la complessità delle architetture distribuite
  2. Il vero costo di una modifica trasversale
  3. Coordinare più repository
  4. Configurare AGENTS.md in un monorepo
  5. Due flussi di lavoro trasversali di riferimento
  6. Cosa Codex non può fare per te
  7. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione di Codex Cloud: più repository coesistono ora in un ambiente Codex Cloud (il vecchio indirizzo codex.openai.com non è più il punto di ingresso). Fonte: Codex Cloud.

Gestire la complessità delle architetture distribuite

I progetti moderni spesso si estendono su più repository: un frontend, un backend, una libreria condivisa, un servizio di pagamento. Ognuno ha il proprio ciclo di vita, la propria pipeline CI e i propri maintainer. Questa configurazione funziona alla perfezione, finché una modifica non attraversa i confini dei repository. È qui che Codex cambia le carte in tavola: può operare simultaneamente su più repo.

Il vero costo di una modifica trasversale

Prendi un’attività di routine: aggiungi un campo a una risposta API nel repository backend. Devi poi aggiornare il client API nel repository frontend, i tipi condivisi nel repository comune, la documentazione nel repository docs e i test di integrazione nel repository e2e. Nessuna di queste quattro attività è difficile se presa singolarmente. Insieme, significano quattro cambi di contesto, quattro branch, quattro pull request e quattro possibilità di dimenticarne una. Nella pratica, la documentazione o i test e2e vengono saltati e il problema riemerge tre settimane dopo come un bug che nessuno riesce a far risalire a quel commit originale.

Coordinare più repository

In Codex Cloud, un ambiente può riunire più repository GitHub: li selezioni durante la creazione dell’ambiente, Codex configura le loro dipendenze e gli strumenti necessari, e ogni attività lanciata in quell’ambiente opera sull’intero set. Il tuo prompt descrive quindi la modifica nel suo complesso invece di isolare frammenti:

"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 applica le modifiche in ogni repo e apre pull request coordinate. La propagazione di un tipo condiviso segue la stessa logica, con un requisito aggiuntivo che devi esplicitare chiaramente: verifica che la compilazione vada a buon fine in ogni repo interessato. Senza questa istruzione, scoprirai l’errore di tipo nella CI del repo mobile due ore dopo aver unito tutto il resto.

"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."

Configurare AGENTS.md in un monorepo

Se il tuo progetto è un monorepo (Turborepo, Nx, Lerna), la logica si inverte: i pacchetti condividono un unico albero di file e la gerarchia dei file AGENTS.md gestisce le distinzioni tra di essi. Il file root descrive la struttura generale e le regole valide ovunque:

# 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`

Ogni sotto-pacchetto costruisce poi su questa base con le proprie convenzioni, senza mai ripetere ciò che è già presente nel file root:

# 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__/

Due flussi di lavoro trasversali di riferimento

Il primo copre una funzionalità che attraversa l’intera catena. Presta attenzione alla quarta istruzione: il collegamento incrociato tra le pull request potrebbe sembrare opzionale, ma è ciò che permette al revisore del repo frontend di capire perché esiste quel pulsante senza dover cercare la PR backend corrispondente.

"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"

Il secondo copre la migrazione di un’API versionata. Qui, l’ordine dei passaggi non è cosmetico: garantisce che nessun client rimanga bloccato a metà migrazione, con la v2 attiva e la v1 ancora funzionante durante tutta la finestra di migrazione per i consumer.

"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"

Cosa Codex non può fare per te

Codex lavora repo per repo, in sandbox separate. Non può eseguire due repo insieme: ad esempio, non puoi avviare backend e frontend simultaneamente per un test di integrazione reale. Per i test cross-repo, la sequenza rimane manuale:

  1. Unisci le singole PR
  2. Esegui i test di integrazione dalla tua pipeline CI/CD
  3. Usa Codex per correggere eventuali problemi rilevati

In altre parole, Codex garantisce la coerenza del codice scritto, mai la coerenza del sistema in esecuzione. La tua CI/CD rimane l’arbitro finale e la prudenza impone di non distribuire una serie di PR coordinate finché non ha emesso il suo verdetto.

Punti chiave

  • Codex può creare PR coordinate su più repository
  • I tipi condivisi sono un caso d’uso ideale per i flussi di lavoro multi-repo
  • Configura AGENTS.md in ogni pacchetto di un monorepo
  • I test di integrazione cross-repo devono ancora essere verificati in CI/CD
  • Documenta le dipendenze inter-repo in AGENTS.md