Claude Code y Codex en paralelo: cómo aislar cada agente sin malgastar tokens

Ver el vídeo: cómo aislar agentes de código que trabajan en paralelo

Lanzar más agentes es la parte fácil

Ejecuto decenas de agentes Claude Code y Codex las 24 horas. Ponerlos a trabajar en paralelo es fácil. Evitar que interfieran entre sí es mucho más difícil.

Un worktree de Git entrega a cada agente un directorio y una rama propios. Es un primer paso necesario, pero no aísla todo el entorno de ejecución. Los agentes todavía pueden compartir una base de datos, un puerto, variables de entorno, un servidor de desarrollo, migraciones, datos de prueba o el navegador utilizado por los tests E2E.

Aprendí esta diferencia con un fallo costoso: un ciclo completo de 24 horas quemó 12 millones de tokens sin producir nada útil. Los agentes escribían código, ejecutaban tests, analizaban errores e intentaban corregirlos. Sin embargo, una parte de esos errores procedía de recursos compartidos, no de la implementación de cada agente.

Un agente puede pasar horas modificando código válido porque está intentando explicar el efecto secundario provocado por otra historia.

Por qué los worktrees no bastan

El worktree aísla los archivos controlados por Git. No aísla automáticamente el estado de la aplicación ni los procesos en ejecución.

El repositorio puede estar limpio mientras el entorno de ejecución está contaminado.

Fallos que parecen errores del código

Una colisión no suele indicar que otro agente acaba de cambiar un recurso compartido. Parece un fallo normal de la aplicación: una restricción que falta, un usuario inexistente, un servidor inaccesible, una sesión caducada, una migración ya aplicada o un elemento que nunca aparece en pantalla.

El agente observa el síntoma, inspecciona su rama y escribe una corrección local. Cuando la causa está fuera de esa rama, cada corrección puede alejarlo más de la solución.

Una sandbox completa para cada user story

La unidad correcta de aislamiento es la user story, no el proceso del agente.

Cada historia necesita sus propios recursos:

• una rama;
• un worktree;
• un puerto reservado;
• una base de datos;
• un archivo de entorno;
• un servidor de aplicación;
• un destino E2E;
• migraciones y datos de prueba limitados a esa sandbox.

El número de la historia debe aparecer en todos los nombres. Así se convierte en una clave común que permite a personas, scripts y agentes relacionar y comprobar los recursos.

Ejemplo de convención para rama, worktree, puerto, base y E2E

La sintaxis puede adaptarse a cada proyecto. Lo importante es conservar el mismo identificador a lo largo de toda la cadena.

La descripción completa de una sandbox puede seguir este formato:

story       = STORY-<numero>
branch      = story/<numero>-<tema>
worktree    = ../worktrees/story-<numero>
port        = PORT_<numero>
database    = app_story_<numero>
env         = .env.story-<numero>
server      = server-story-<numero>
e2e_project = e2e-story-<numero>
e2e_baseUrl = http://127.0.0.1:${PORT_<numero>}

El agente no debería inventar ninguno de estos valores. Un gestor de sandboxes crea o reserva los recursos, escribe la configuración y entrega al agente un contexto coherente.

El ciclo de vida de una historia aislada

Preparar el entorno antes de delegar

Antes de iniciar Claude Code o Codex, el sistema crea la rama y el worktree, reserva el puerto, prepara la base de datos y genera el archivo de entorno. Las migraciones se ejecutan contra la base de esa historia, nunca contra una base compartida por defecto.

La preparación debe detenerse de inmediato si el recurso solicitado ya está ocupado. Un error claro antes de iniciar el agente cuesta menos que una investigación prolongada sobre una colisión de infraestructura.

Arrancar el servidor desde el worktree correcto

El servidor debe iniciarse desde el worktree de la historia y recibir su archivo de entorno de forma explícita. El directorio actual no es una garantía suficiente. Los logs del proceso deben mostrar la historia, el puerto y la base utilizados.

Después conviene comprobar la salud del servidor en la URL reservada. Sin esa comprobación, el navegador E2E podría conectarse a un proceso antiguo que sigue activo.

Apuntar los tests E2E a un destino explícito

Cada proyecto E2E recibe una baseURL propia de la historia. También hay que separar sesiones del navegador, archivos temporales y datos de prueba cuando el framework los conserva entre ejecuciones.

El agente siempre debería poder responder a tres preguntas:

1. ¿Qué commit se está probando?
2. ¿Qué servidor ejecuta ese commit?
3. ¿Qué base contiene el estado observado por el test?

Si falta una respuesta, el resultado E2E no es una prueba fiable.

Eliminar únicamente la sandbox terminada

Cuando una historia se integra o se abandona, el sistema detiene su servidor, libera su puerto, elimina su base y retira su worktree. Las tareas de limpieza deben usar nombres completos derivados del número de historia. Una limpieza global puede borrar el entorno que otro agente todavía está utilizando.

Reglas para los agentes autónomos

El aislamiento técnico funciona mejor con reglas explícitas y fáciles de verificar:

• no utilizar nunca un puerto o una base por defecto;
• no ejecutar una migración sin mostrar primero su destino;
• rechazar un test E2E si la baseURL no corresponde a la historia;
• registrar la rama, el commit, el puerto y la base;
• comprobar la salud del servidor antes de abrir el navegador;
• tratar un recurso ocupado como un error de configuración, no como un bug de la aplicación;
• limitar cada agente al worktree y a los servicios de su historia.

Estas reglas también simplifican la investigación humana. Cuando un test falla, los logs indican qué versión, servidor y datos produjeron el resultado.

Qué cambia con este método

Una sandbox aislada no garantiza que el código sea correcto. Un agente todavía puede interpretar mal una tarea, introducir una regresión o escribir un test débil. El aislamiento no sustituye la revisión, una buena especificación ni el diseño de pruebas.

Sí elimina una categoría completa de señales falsas provocadas por el estado compartido. El agente puede modificar, reiniciar, migrar, cargar datos y restaurar su entorno sin alterar el de otra historia. Sus observaciones se vuelven reproducibles: la migración pertenece a la historia, los datos de prueba pertenecen a la historia y el navegador apunta al servidor construido desde su worktree.

Además, el límite del fallo queda claro. Si la historia falla dentro de una sandbox completa, la investigación puede concentrarse en ella sin tener que reconstruir primero la actividad de todos los agentes vecinos.

Conclusión

Ejecutar Claude Code y Codex en paralelo exige más que crear ramas separadas. Todo lo que el código utiliza durante la ejecución necesita un límite por historia: worktree, puerto, base de datos, entorno, migraciones, datos de prueba, servidor y navegador E2E.

Incluye el número de historia en cada recurso, prepara la sandbox antes de lanzar el agente, verifica el destino antes de ejecutar los tests y elimina solo esa sandbox cuando termine el trabajo. Así evitas que un agente dedique su ciclo a corregir efectos secundarios creados por otro.

Ver en vídeo el flujo completo de aislamiento

Suscribirse a The Agentic Dev para recibir más experiencias prácticas