Cómo integrar el trabajo de varios agentes de IA sin romper main

Respuesta corta: integra en serie, en una rama de integración separada de main, con una puerta automática (tests, lint, análisis estático) decidiendo si cada merge existe, y nunca dejes que un agente de IA haga el merge de su propio trabajo. El paralelismo ocurre al producir el código; la integración es serial por naturaleza, y aceptar ese hecho es lo que mantiene main sin romper.

Por qué la integración es donde el paralelismo pasa la cuenta

Tres agentes de IA producen tres ramas que pasan los tests por separado y aun así se rompen juntas: uno renombró un método que otro llama, dos tocaron el mismo archivo de rutas, el tercero asumió un esquema que cambió. Git acusa el conflicto textual, pero el conflicto semántico (código que compila y hace lo incorrecto) solo aparece cuando los trabajos se encuentran. Cuantos más agentes en paralelo, más cara es cada hora sin integrar.

La receta: rama de integración y merges en serie

El arreglo que ha demostrado ser estable: main recibe solo lo ya integrado y validado; una rama de integración (llámala stage, develop, el nombre no importa) recibe los merges; y cada agente de IA trabaja en su propia rama, salida de la integración, de preferencia en una worktree de git para ni siquiera compartir directorio. El sitio donde lees este texto se construyó así: 59 merges de ramas de agente en tres semanas, medidos en el propio repositorio en agosto de 2026, ninguno directo a main.

La puerta: el merge solo existe si la verificación pasa

Una puerta es un único script que ejecuta la suite de tests, el formateador, el análisis estático y el build antes de cualquier merge, y bloquea el merge si cualquier etapa falla. El punto es que sea binaria y automática: sin "pasó casi todo". Con agentes de IA la puerta importa más que con humanos, porque el agente confía demasiado en su propio diff y declarará listo lo que no lo está.

¿Cómo es el script de la puerta en la práctica?

El nuestro es más largo, sobre todo por los mensajes de error legibles y las banderas para saltar las etapas lentas, pero la idea entera cabe en diez líneas de shell. Esta es la versión simplificada del script que guarda los merges en el repositorio de este sitio:

#!/usr/bin/env bash
set -euo pipefail

php artisan test --compact             # la suite entera
vendor/bin/pint --test                 # estilo, solo comprueba, no muta nada
vendor/bin/phpstan analyse             # análisis estático
if ! git diff --quiet origin/stage... -- resources/ package.json; then
  npm run build                        # build solo cuando el diff toca el front
fi
composer audit --no-scripts            # CVE conocida en dependencias PHP
npm audit --audit-level=high           # CVE conocida en dependencias JS

echo "la puerta pasó"

Dos detalles importan más que la lista de etapas. La puerta solo comprueba, nunca arregla: un formateador que reescribe archivos durante la verificación esconde el problema en lugar de reportarlo. Y cada etapa sale con código distinto de cero cuando falla, que es lo que, junto con set -e, vuelve el resultado binario en vez de un informe que alguien tiene que interpretar.

¿Quién debe hacer el merge, tú o el agente de IA?

El agente propone, el humano integra. Dejar que el agente de IA haga merge de su propio trabajo junta al autor y al juez en la misma cabeza, y el sesgo de quien escribió sobrevive a la revisión de quien escribió. Vale también para la revisión: revisar con un agente nuevo, que no produjo el código, encuentra lo que el autor no ve. El merge es una decisión, no un paso del script.

¿Y cuando dos agentes de IA terminan al mismo tiempo?

Fila, y el mecanismo es más interesante de lo que parece. El primero integra; el segundo actualiza su rama con el resultado del primero, corre la puerta de nuevo y recién entonces integra. La fila serializa exactamente el paso que necesita ser serial, y nada más: la producción de código sigue paralela todo el tiempo.

Dónde vive la fila es la parte que casi todos erran. No puede vivir en el repositorio, porque un archivo commiteado en una rama no existe en la otra, y cada agente está sentado en su rama y en su worktree. Así que el estado va a un directorio compartido fuera del git: un archivo con quién está esperando, otro con el nombre de quien conduce el turno. Quien entra primero se vuelve conductor y hace el merge; los demás leen que están esperando y cierran el turno. Cuando el conductor termina, el mismo script promueve al siguiente de la fila, y eso es lo que decide el orden: la llegada, no la antigüedad ni quién grita más fuerte.

La única etapa que necesita un cerrojo es entrar en la fila contra elegir al próximo conductor, porque dos agentes haciendo las dos cosas en el mismo instante podrían creerse conductores a la vez. El resto puede ser archivo simple, y el archivo simple es lo que hace que esto sobreviva a un reinicio de máquina en medio de una integración.

¿Cuánto cuesta integrar en serie?

El costo es real: con la puerta tomando unos minutos por ronda, integrar cinco ramas es media hora solo de verificación, y el segundo de la fila espera al primero. La alternativa cuesta más: un main roto para todos los agentes a la vez, y una tarde entera de arqueología para hallar qué combinación de merges lo rompió. Media hora de espera es un precio que puedes prever; la tarde de arqueología, no.