Flujo de trabajo multiagente en Claude Code: roles, aislamiento y revisión manual
Guía práctica de un flujo de trabajo multiagente en Claude Code: separación de roles, aislamiento con Git worktrees, tarjeta de traspaso y aprobación manual.
Crear «equipos de agentes de IA» plenamente autónomos que fusionen código de forma automática suele introducir defectos arquitectónicos sutiles, ciclos de refactorización y degradación de la base de código. Dos agentes ejecutándose en paralelo no constituyen una fuente de verdad independiente: si el agente autor comete un error lógico, un agente revisor que trabaja con fundamentos de prompt parecidos puede pasarlo por alto.
Un flujo de trabajo multiagente fiable no se basa en la ilusión de una autonomía total, sino en una separación estricta de responsabilidades: un implementador (Author), un verificador independiente (Reviewer) y una persona desarrolladora que toma la decisión final de fusionar.
1. Límites de rol: Author, Reviewer y responsable humano
En un flujo de desarrollo eficaz, cada participante tiene un ámbito de responsabilidad definido y cerrado:
2. Aislamiento del contexto y del espacio de trabajo
No ejecute nunca los agentes Author y Reviewer en el mismo directorio de trabajo ni en el mismo hilo de conversación. Aíselos en tres niveles operativos:
- Contexto de sesión: los hilos de conversación independientes evitan alucinaciones mutuas y confirmaciones circulares.
- Aislamiento del sistema de archivos: Git worktrees separados garantizan que el reviewer inspeccione únicamente un diff confirmado, sin estado local sin confirmar.
- Seguridad del entorno: las claves API y credenciales de ejecución permanecen en variables de entorno y nunca se pasan como texto dentro de un prompt.
Comandos para preparar los worktrees
[!IMPORTANT]
Configuración de la API: cada sesión de Claude Code opera con sus propias credenciales de API configuradas mediante variables de entorno del sistema operativo. Consulte la guía de BetterToken para Claude Code.
3. El contrato de traspaso estructurado
Cuando el agente Author termina la implementación, prepara una tarjeta de traspaso concisa. Se excluyen estrictamente las transcripciones de chat sin procesar, los secretos y las suposiciones no verificadas:
Handoff Card
- Task: Add HTTP 429 retry support in payment client with exponential backoff.
- Branch:
feat/payment-retry - Changed Files:
src/client/http.ts,tests/http-retry.test.ts - Verification Command:
npm test -- tests/http-retry.test.ts(Passed) - Risks & Blockers: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- Next Step: Reviewer agent validates Retry-After header handling.
4. Protocolo de aprobación con intervención humana
El agente Reviewer realiza una evaluación aislada:
- Se desplaza al worktree limpio:
../agent-reviewer. - Ejecuta el comando de verificación registrado.
- Inspecciona el diff de manera independiente en busca de efectos secundarios y casos límite.
- Genera un resumen estructurado para la persona responsable de ingeniería.
La persona ingeniera realiza la aprobación final:
- revisa los hallazgos del reviewer;
- confirma que no haya regresiones frente a
main; - ejecuta la fusión manualmente:
git merge feat/payment-retry.
Esta canalización evita los bucles de confirmación mutua y mantiene el control de la calidad y de las decisiones de arquitectura en manos de la persona desarrolladora.