Ir al contenido principal
Español— Elegir un idioma
Menú

Trabajar en proyectos con múltiples repositorios

Lección 13 de 20 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Gestión de la complejidad en arquitecturas distribuidas
  2. El coste real de un cambio transversal
  3. Coordinación de múltiples repositorios
  4. Configuración de AGENTS.md en un monorepositorio
  5. Dos flujos de trabajo transversales de referencia
  6. Lo que Codex no puede hacer por ti
  7. Puntos clave

Lección actualizada el 3 de noviembre de 2026 según la documentación de Codex Cloud: varios repositorios conviven ahora en un entorno de Codex Cloud (la antigua dirección codex.openai.com ya no es el punto de entrada). Fuente: Codex Cloud.

Gestión de la complejidad en arquitecturas distribuidas

Los proyectos modernos suelen abarcar múltiples repositorios: un frontend, un backend, una biblioteca compartida, un servicio de pagos. Cada uno tiene su propio ciclo de vida, su canalización de integración continua (CI) y sus mantenedores. Esta configuración funciona a la perfección hasta que un cambio cruza los límites de los repositorios. Ahí es donde Codex cambia las reglas del juego: puede trabajar en varios repositorios simultáneamente.

El coste real de un cambio transversal

Piensa en una tarea rutinaria: añades un campo a una respuesta de API en el repositorio del backend. A continuación, debes actualizar el cliente de API en el repositorio del frontend, los tipos compartidos en el repositorio común, la documentación en el repositorio de docs y las pruebas de integración en el repositorio e2e. Ninguna de estas cuatro tareas es difícil por separado. Juntas, implican cuatro cambios de contexto, cuatro ramas, cuatro solicitudes de extracción (pull requests) y cuatro oportunidades de olvidar una. En la práctica, se suele omitir la documentación o las pruebas e2e, y el problema resurge tres semanas después como un error que nadie logra rastrear hasta ese commit original.

Coordinación de múltiples repositorios

En Codex Cloud, un entorno puede reunir varios repositorios de GitHub: los seleccionas al crear el entorno, Codex configura sus dependencias y herramientas, y cada tarea lanzada en ese entorno opera sobre todo el conjunto. Tu indicación (prompt) describe entonces el cambio en su totalidad en lugar de aislar fragmentos:

"En el repositorio backend (api-service):
- Añadir un endpoint GET /api/v2/products con paginación

En el repositorio frontend (web-app):
- Actualizar el cliente de API para usar el nuevo endpoint
- Añadir paginación al componente ProductList"

Codex aplica los cambios en cada repositorio y abre solicitudes de extracción coordinadas. La propagación de un tipo compartido sigue la misma lógica, con un requisito adicional que debes indicar explícitamente: verifica que la compilación se complete con éxito en todos los repositorios afectados. Sin esa instrucción, descubrirás el error de tipo en la canalización de CI del repositorio móvil dos horas después de haber fusionado todo lo demás.

"El tipo Product en shared-types/src/product.ts ha sido 
modificado (se ha añadido el campo tags: string[]). 
Actualiza todos los usos en:
- api-service: rutas y servicios que usan Product
- web-app: componentes que muestran un Product
- mobile-app: pantallas que muestran un Product
Asegúrate de que cada repositorio se compile sin errores."

Configuración de AGENTS.md en un monorepositorio

Si tu proyecto es un monorepositorio (Turborepo, Nx, Lerna), la lógica se invierte: los paquetes comparten un único árbol de archivos y la jerarquía de archivos AGENTS.md contiene las distinciones entre ellos. El archivo raíz describe la estructura general y las reglas que se aplican en todas partes:

# AGENTS.md (raíz del monorepositorio)

## Estructura
Monorepositorio Turborepo con los siguientes paquetes:
- packages/api — backend Fastify
- packages/web — frontend Next.js
- packages/shared — tipos y utilidades compartidos
- packages/e2e — pruebas end-to-end con Playwright

## Reglas
- Los cambios en packages/shared DEBEN ir seguidos de una compilación 
  de todos los paquetes dependientes
- Comando de compilación global: `turbo run build`
- Comando de prueba global: `turbo run test`

Cada subpaquete construye sobre esta base con sus propias convenciones, sin repetir nunca lo que ya está en el archivo raíz:

# packages/api/AGENTS.md

## API del backend
- Framework: Fastify
- Validación: Zod (esquemas en src/schemas/)
- Los tipos de packages/shared se importan vía @myorg/shared
- Cada nueva ruta requiere una prueba en __tests__/

Dos flujos de trabajo transversales de referencia

El primero cubre una función que abarca toda la cadena. Presta atención a la cuarta instrucción: el enlace cruzado entre solicitudes de extracción podría parecer opcional, pero es lo que permite al revisor del repositorio del frontend entender por qué existe ese botón sin tener que buscar la solicitud de extracción correspondiente del backend.

"Nueva función: sistema de favoritos.
1. shared-types: Añadir el tipo Favorite
2. api-service: CRUD /api/favorites con autenticación
3. web-app: Botón de corazón en las tarjetas de producto
4. Crear una PR en cada repositorio con enlaces 
   a las PR de los otros repositorios en la descripción"

El segundo cubre la migración de una API versionada. Aquí, el orden de los pasos no es cosmético: garantiza que ningún cliente se quede aislado a mitad de la migración, con la v2 en su lugar y la v1 aún activa durante toda la ventana de migración del consumidor.

"La API v1 /users está obsoleta. Crear v2:
1. api-service: Añadir rutas v2 con el nuevo formato
2. api-service: Marcar las rutas v1 como obsoletas (cabecera)
3. web-app: Migrar todas las llamadas de v1 a v2
4. mobile-app: Migrar todas las llamadas de v1 a v2
5. docs: Actualizar la documentación de la API"

Lo que Codex no puede hacer por ti

Codex trabaja repositorio por repositorio, en entornos aislados (sandboxes) separados. No puede ejecutar dos repositorios juntos: por ejemplo, no puedes lanzar el backend y el frontend simultáneamente para una prueba de integración real. Para las pruebas entre repositorios, la secuencia sigue siendo manual:

  1. Fusionar las solicitudes de extracción individuales
  2. Ejecutar las pruebas de integración desde tu canalización de CI/CD
  3. Usar Codex para corregir cualquier problema detectado

En otras palabras, Codex garantiza la coherencia del código escrito, nunca la coherencia del sistema en ejecución. Tu CI/CD sigue siendo el árbitro final, y la prudencia dicta que no debes desplegar una serie de solicitudes de extracción coordinadas hasta que haya emitido su veredicto.

Puntos clave

  • Codex puede crear solicitudes de extracción coordinadas en varios repositorios
  • Los tipos compartidos son un caso de uso ideal para flujos de trabajo con múltiples repositorios
  • Configura AGENTS.md en cada paquete de un monorepositorio
  • Las pruebas de integración entre repositorios deben verificarse aún en CI/CD
  • Documenta las dependencias entre repositorios en AGENTS.md