Agentes en paralelo con git worktrees

Cuando trabajas con un solo agente, las tareas hacen fila: tú revisas una, le das la siguiente, esperas, revisas otra. La última tarea de la cola puede esperar horas para ejecutar 30 minutos de trabajo real.

Un modelo más rápido ayuda poco con eso. Lo que ayuda es tener más carriles en paralelo: varios agentes, cada uno con su tarea, trabajando al mismo tiempo sobre el mismo proyecto. El problema es que, si todos comparten una sola carpeta, se estorban. Esta guía explica cómo evitarlo con git worktree.

La idea es partir una funcionalidad en roles y abrir una sesión de Claude Code por rol. La regla de oro: ninguna carpeta pertenece a dos roles.

El revisor es la pieza que más se subestima. El fallo típico del trabajo en paralelo no es un bug de código sino un desacuerdo: el frontend manda email y el backend espera correo.

• Contexto limpio: cada agente tiene su propia ventana de contexto y no arrastra ruido de las otras tareas.
• Revisión independiente: quien escribe el código es mal revisor de su propio trabajo.
• Diseño por interfaces: trabajar en paralelo te obliga a definir el contrato antes de empezar, y eso mejora el diseño.
• De ejecutor a director: tu trabajo pasa a ser decidir qué se construye y en qué orden.
• Costos honestos: ahorras tiempo de reloj, pero gastas más tokens, porque cada agente carga su propio contexto.

Antes de lanzar a nadie, escribe un CONTRATO-API.md y haz commit en la rama principal, para que todos los worktrees partan de la misma versión. Es el documento que evita que frontend y backend se desencuentren. Un ejemplo para un endpoint de login debería incluir:

• Endpoint: POST /api/auth/login.
• Request: email (texto, obligatorio, formato válido, máximo 254 caracteres) y password (texto, obligatorio, entre 8 y 128 caracteres).
• Respuesta 200: token (JWT), expiresIn (3600) y user con id y name.
• Formato único de error: { "error": { "code": ..., "message": ... } }.
• Códigos de error: 400 VALIDATION_ERROR, 401 INVALID_CREDENTIALS (el mismo mensaje para correo o contraseña incorrectos, por seguridad) y 429 TOO_MANY_ATTEMPTS (más de 5 intentos fallidos en 15 minutos por IP).
• Decisiones abiertas: por ejemplo, 'recordarme' con sesiones de 30 días queda fuera de esta versión.

Si dejas a cuatro agentes en la misma carpeta y la misma rama, aparecen archivos a medio escribir, tests que fallan por código de otro agente, checkouts que cambian los archivos bajo los pies de los demás y commits mezclados por un git add ..

Un repositorio tiene una base de historial (.git) y una carpeta de trabajo. Un worktree te da varias carpetas de trabajo que comparten el mismo historial. Una rama no puede estar activa en dos worktrees a la vez, y eso es justo lo que necesitas.

# Una carpeta hermana por rol, cada una con su rama nueva
git worktree add ../app-frontend -b feat/frontend
git worktree add ../app-backend  -b feat/backend
git worktree add ../app-docs     -b docs/api
git worktree add ../app-review   -b review/contract

# Ver todas las carpetas de trabajo y su rama
git worktree list

# Al terminar: quitar una carpeta y limpiar referencias
git worktree remove ../app-frontend
git worktree prune

Cada agente arranca con un archivo de instrucciones propio, por ejemplo en una carpeta agentes/. Estas son las partes que no deben faltar, con el backend como ejemplo:

• Misión: implementar POST /api/auth/login tal como está en el contrato.
• Dónde trabajas: worktree ../app-backend, rama feat/backend. No cambiar de rama, no hacer merge ni push. Si levantas un servidor, usa el puerto 3002.
• Carpetas permitidas: api/ y tests/api/.
• Prohibido: web/, docs/, CONTRATO-API.md, agentes/, y package.json con su lockfile. Preguntar antes de añadir una dependencia.
• Regla del contrato: CONTRATO-API.md es la fuente de verdad. Si algo no encaja, detenerse y reportarlo.
• Terminado: un test por cada caso del contrato (200, 400, 401, 429), los tests de la carpeta pasan y todo está commiteado con git status limpio.
• Reporte: cerrar con un mensaje que empiece con TERMINADO: e indique qué se construyó, qué archivos cambiaron, cómo se probó y cualquier diferencia con el contrato.

Paraleliza cuando las tareas son independientes, las fronteras entre carpetas son claras, el contrato se puede escribir de antemano, las tareas tienen tamaño parecido y duran más de una hora, y existen tests.

No lo hagas cuando los roles tocan los mismos archivos, los cambios están muy acoplados, todavía estás explorando, el proyecto es diminuto o no hay tests (sin ellos no puedes comprobar que el merge no rompió nada).

El escenario: tienes una app con frontend y API y necesitas añadir el login con email y contraseña. Quieres que frontend, backend y documentación avancen a la vez, con un revisor que verifique que encajan. Este es el flujo de punta a punta, un prompt por paso.

Revisa el contrato tú mismo y haz commit en la rama principal. Todo lo que se decida aquí te ahorra discusiones después.

Ahora abre una terminal por carpeta (o usa tmux) e inicia Claude Code en cada una pasándole su archivo, por ejemplo claude "$(cat agentes/backend.md)".

Fíjate en el orden del merge: primero la documentación, luego el backend y al final el frontend, para que cada integración se apoye en lo anterior ya probado.