Módulo 3: Parallel Sub-Agent Delegation
4. Timeout, Error Handling, y Fallback Strategies
4. Timeout, Error Handling, y Fallback Strategies
Descripción
Un sistema paralelo que solo funciona en el happy path no es un sistema — es una demo. Los agentes paralelos fallan: un subagent consume más turns de los esperados, otro necesita un permiso que no tiene pre-aprobado, un tercero produce output inconsistente que rompe el merge. ¿Qué pasa con los otros 3 subagents cuando uno falla? ¿Se cancelan todos? ¿Se continúa sin él? ¿Se reintenta? Estas decisiones definen la robustez de tu orquestación.
En ejecución secuencial, un error detiene todo — lo ves inmediatamente, lo corriges, y continúas. En ejecución paralela, un error en un subagent puede pasar desapercibido mientras los demás continúan, produciendo un resultado parcial que parece completo pero tiene un hueco. O peor: el subagent que falló era el que editaba el archivo compartido, y ahora los otros 3 tienen cambios que dependen de esa edición que nunca ocurrió.
Al terminar esta cápsula sabrás cómo prevenir la mayoría de fallos con configuración adecuada (maxTurns, permisos pre-aprobados), cómo detectar los que ocurren, cómo recuperarte de ellos (resume en foreground, retry, skip), y cómo diseñar tu flujo para que sea resiliente ante fallos parciales.
maxTurns: El Timeout de los Subagents
Qué es y por qué lo necesitas
maxTurns limita cuántos turnos agénticos puede tomar un subagent. Un "turno" es una interacción completa: Claude piensa, usa una herramienta, recibe el resultado. Si un subagent llega a su límite de turns sin completar la tarea, se detiene y reporta lo que pudo hacer.
---
name: quick-scanner
maxTurns: 10
---
Sin maxTurns, un subagent podría ejecutarse indefinidamente — leyendo archivos, buscando patrones, haciendo cambios, iterando... especialmente si el system prompt no tiene un scope bien acotado. En ejecución secuencial, puedes cancelarlo manualmente (Ctrl+C). En background, no tienes esa opción — necesitas un límite automático.
Elegir el valor correcto
| Tipo de tarea | maxTurns recomendado | Razonamiento |
|---|---|---|
| Análisis de 1-2 archivos | 5-8 | Read + Grep + reportar |
| Revisión de un módulo | 10-15 | Listar archivos + leer cada uno + reportar |
| Implementación de cambios | 15-25 | Leer + editar + verificar por archivo |
| Refactoring de un módulo completo | 20-30 | Múltiples archivos, ediciones iterativas |
| Investigación amplia del codebase | 10-15 | Búsqueda + lectura selectiva + reportar |
Regla para estimar: Cuenta las operaciones que esperas:
Ejemplo: refactorizar error handling en src/auth/ (5 archivos)
1. Glob para listar archivos → 1 turn
2. Read archivo 1 → 1 turn
3. Edit archivo 1 → 1 turn
4. Read archivo 2 → 1 turn
5. Edit archivo 2 → 1 turn
... (3 archivos más) → 6 turns
11. Verificar con Grep → 1 turn
12. Producir reporte → 1 turn
Total estimado: 12 turns
maxTurns recomendado: 15 (12 + margen del 25%)
Agrega un margen del 20-30% sobre tu estimación. Es mejor que el subagent termine con turns sobrantes a que se quede corto.
Qué pasa cuando se alcanza maxTurns
Cuando un subagent llega a su límite:
- El subagent se detiene — no ejecuta más herramientas
- Reporta lo que pudo completar hasta ese momento
- Claude (main) recibe el resultado parcial
- Tú puedes decidir si el resultado parcial es suficiente o necesitas más
Subagent con maxTurns: 10
Turn 1-8: Lee archivos, edita 3 de 5, produce reporte parcial
Turn 9: Edita archivo 4
Turn 10: LÍMITE — reporta: "Modifiqué 4 de 5 archivos. El archivo
src/auth/middleware.py no fue procesado por límite de turns."
El resultado parcial es mejor que ningún resultado. El subagent prioriza las tareas más importantes primero (si el system prompt está bien diseñado) y deja las menos críticas para el final.
maxTurns y tareas paralelas
En un flujo paralelo, maxTurns actúa como timeout individual por worker:
Worker auth (maxTurns: 20) → termina en turn 15 ✅
Worker products (maxTurns: 20) → termina en turn 18 ✅
Worker orders (maxTurns: 20) → alcanza turn 20 ⚠️ (resultado parcial)
Worker notif (maxTurns: 20) → termina en turn 8 ✅
El worker de orders produjo un resultado parcial. Los otros 3 completaron normalmente. El merge coordinator recibirá 3 resultados completos y 1 parcial — debe decidir qué hacer con el parcial.
Para manejar esto, instruye al merge coordinator:
## Handling Partial Results
If any worker reports a partial result (did not complete all tasks):
1. Note which tasks were not completed
2. Verify that completed tasks are internally consistent
3. Include partial worker's completed tasks in the merge
4. List uncompleted tasks as "PENDING — requires manual completion"
Errores de Permisos en Background
El problema
Un subagent en background no puede pedir confirmación. Si necesita un permiso que no está pre-aprobado por su allowlist de herramientas, falla en esa acción específica:
Subagent background con tools: [Read, Grep, Glob]
Turn 1: Read src/auth/models.py → ✅ (Read está en allowlist)
Turn 2: Grep "password" src/ → ✅ (Grep está en allowlist)
Turn 3: Bash "pip install bcrypt" → ❌ (Bash NO está en allowlist)
Turn 4: Write fix to models.py → ❌ (Write NO está en allowlist)
El subagent no crashea — la acción individual falla y el subagent continúa con lo que puede hacer. Pero si la acción que falló era crítica para la tarea, el resultado será incompleto o incorrecto.
Prevención: allowlist completa
La mejor estrategia es preventiva — asegúrate de que el frontmatter incluya todas las herramientas que el subagent podría necesitar:
---
name: module-refactorer
tools: Read, Write, Edit, Grep, Glob, Bash
background: true
isolation: worktree
---
Antes de lanzar un subagent en background, verifica su system prompt y pregúntate: "¿Qué herramientas usará?" Si lee archivos y los edita, necesita Read + Write + Edit. Si ejecuta comandos, necesita Bash. Si busca patrones, necesita Grep + Glob.
Detección: señales de fallo de permisos
Cuando un subagent background completa, su reporte puede tener señales de que algo falló:
Señales de fallo de permisos:
- "No pude ejecutar el comando X"
- "No pude modificar el archivo Y"
- Reporte parcial cuando esperabas completo
- Output que describe qué debería hacerse en lugar de hacerlo
Si ves estas señales, el subagent probablemente necesitaba una herramienta que no tenía.
Recuperación: resume en foreground
Cuando un subagent background falla, puedes resumirlo en foreground donde puede pedirte permisos:
Claude: "El module-refactorer no pudo completar la tarea.
Necesitó ejecutar Bash para instalar una dependencia."
Tú: "Resúmelo en foreground para que pueda pedir los permisos."
Claude: [re-ejecuta el subagent en foreground]
Claude: "¿Puedo ejecutar 'pip install bcrypt'?"
Tú: "Sí"
Claude: [completa la tarea]
Para facilitar el resume, el subagent puede diseñarse para ser idempotente — que pueda re-ejecutarse sin problemas aunque ya haya completado parte del trabajo.
Estrategias de Fallback
Estrategia 1: Retry (reintentar)
Si un subagent falla por un motivo transitorio (timeout, error de red, herramienta temporalmente no disponible), reintentarlo puede resolver el problema.
Flujo con retry:
Worker A → falla (timeout)
↓
Retry Worker A → éxito ✅
↓
Continuar con merge
Cuándo usar retry:
- El fallo es transitorio (no un error de lógica o configuración)
- El subagent es idempotente (re-ejecutar no causa problemas)
- El costo de reintentar es bajo (subagent rápido con haiku)
Cuándo NO usar retry:
- El fallo es consistente (mismo error cada vez)
- El subagent ya hizo cambios parciales que no se pueden deshacer fácilmente
- El costo es alto (subagent largo con opus)
Prompt para retry:
El worker de auth falló por timeout. Reintenta la misma tarea:
- Usa el module-worker para refactorizar src/auth/
- Aumenta maxTurns a 30 (antes era 20)
- Si falla de nuevo, reporta qué pudo completar
Estrategia 2: Skip (omitir)
Si un subagent falla y su tarea no es crítica, puedes omitirlo y continuar con los demás.
Flujo con skip:
Worker A → éxito ✅
Worker B → falla ❌ → SKIP
Worker C → éxito ✅
Worker D → éxito ✅
↓
Merge coordinator → reporta que B fue skipped
↓
Resultado: 3 de 4 módulos refactorizados
Cuándo usar skip:
- La tarea del subagent es independiente del resto
- El resultado parcial (N-1 de N) es aceptable
- Puedes completar la tarea skipped manualmente después
Cuándo NO usar skip:
- Otros subagents dependen del resultado del que falló
- Omitir produce un resultado inconsistente
- La tarea es crítica (security fix, data migration)
Prompt para skip:
Si alguno de los 4 workers falla, continúa con los que completaron.
El merge coordinator debe reportar:
- Workers exitosos y sus cambios
- Workers fallidos y la razón del fallo
- Tareas pendientes que necesitan atención manual
Estrategia 3: Manual intervention (intervención manual)
Si el fallo requiere decisión humana, el flujo se pausa para que tú intervengas.
Flujo con intervención manual:
Worker A → éxito ✅
Worker B → conflicto que requiere decisión ⚠️
↓
Claude: "Worker B encontró un conflicto en src/shared/utils.py.
Dos opciones:
1. Mantener la implementación actual
2. Reescribir con el nuevo pattern
¿Cuál prefieres?"
↓
Tú: "Opción 2"
↓
Continuar con merge
Cuándo usar manual intervention:
- El fallo involucra una decisión de arquitectura o negocio
- La resolución automática podría introducir errores
- El costo de equivocarse es alto (producción, datos de usuarios)
Estrategia 4: Graceful degradation
Diseña el flujo para que funcione incluso si algunos subagents fallan, produciendo un resultado de menor calidad pero funcional.
Flujo con graceful degradation:
4 workers para refactorizar error handling:
Worker auth → éxito ✅ (migrado a custom exceptions)
Worker products → falla ❌ (se queda con HTTPException)
Worker orders → éxito ✅ (migrado a custom exceptions)
Worker notif → éxito ✅ (migrado a custom exceptions)
Resultado: 3 de 4 módulos migrados.
El módulo products sigue funcional con el patrón anterior.
No hay inconsistencia que rompa nada — solo inconsistencia de estilo.
Para habilitar graceful degradation, diseña los cambios de cada worker para que sean autocontenidos — que el módulo funcione correctamente con o sin el refactor aplicado.
Monitoring de Ejecución Paralela
Observar subagents en background
Cuando lanzas subagents en background, Claude Code muestra indicadores de progreso. No ves el output detallado en tiempo real, pero sabes que están ejecutándose.
Si necesitas más visibilidad, usa la variable de entorno para debugging:
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude
Esto fuerza todos los subagents a ejecutarse en foreground, secuencialmente. Ves cada paso en tiempo real. Es más lento pero más transparente.
Cuándo usar debugging mode
| Situación | Modo recomendado |
|---|---|
| Desarrollo normal con subagents conocidos | Background (paralelo) |
| Desarrollando un nuevo subagent | Foreground (debugging) |
| Subagent falla silenciosamente | Foreground (debugging) |
| Verificando permisos de un subagent | Foreground (debugging) |
| Producción / uso diario | Background (paralelo) |
| Presentación o demostración | Foreground (visible) |
Diagnóstico post-ejecución
Cuando un subagent paralelo produce un resultado inesperado, estos pasos de diagnóstico ayudan:
1. Verificar el resultado:
¿El subagent produjo output? → Si no, probablemente falló por permisos
¿El output está en el formato esperado? → Si no, el system prompt necesita ajuste
¿El output está completo? → Si no, probablemente alcanzó maxTurns
2. Verificar los archivos:
git diff --stat
git diff --name-only
Si esperabas cambios en 5 archivos y solo ves 3, el subagent no terminó o no tenía permisos para editar los otros 2.
3. Re-ejecutar en foreground:
Ejecuta el module-worker para src/auth/ en foreground (no background).
Quiero ver cada paso que toma.
Esto te muestra exactamente qué hizo, qué herramientas usó, y dónde se detuvo.
Diseño Resiliente: Fail-Fast vs Resilient
Fail-fast: detenerse al primer error
En fail-fast, si un subagent falla, todo el flujo se detiene. Es la estrategia más conservadora.
Prompt fail-fast:
"Ejecuta los 4 workers en paralelo. Si CUALQUIER worker falla o
produce un resultado parcial, DETÉN todo. No hagas merge de resultados
parciales. Reporta qué falló y por qué."
Ventajas:
- No se aplican cambios parciales que podrían ser inconsistentes
- Fácil de razonar — funciona todo o no funciona nada
- Seguro para tareas donde la consistencia es crítica
Desventajas:
- Un fallo trivial en un worker no-crítico detiene todo
- Hay que re-ejecutar todo, incluyendo workers que ya completaron
- Ineficiente si los fallos son comunes
Resilient: continuar a pesar de errores
En resilient, los workers que fallan se omiten y los exitosos se mergean.
Prompt resilient:
"Ejecuta los 4 workers en paralelo. Si algún worker falla:
1. Continúa con los demás
2. El merge coordinator recibe los resultados disponibles
3. El reporte final lista qué workers completaron y cuáles fallaron
4. Las tareas de workers fallidos se listan como PENDIENTES"
Ventajas:
- Maximiza el trabajo completado
- Un fallo aislado no invalida todo el progreso
- Eficiente para tareas donde la completitud parcial es útil
Desventajas:
- El resultado puede ser inconsistente si los workers fallidos tenían dependencias
- Requiere un merge coordinator que maneje resultados parciales
- Más complejo de razonar
Cuándo usar cada enfoque
| Escenario | Fail-fast | Resilient |
|---|---|---|
| Migración de base de datos | ✅ | |
| Refactor de código | ✅ | |
| Security fixes | ✅ | |
| Actualización de documentación | ✅ | |
| Cambio de interfaz compartida | ✅ | |
| Refactor de módulos independientes | ✅ | |
| Cambios que deben ser atómicos | ✅ | |
| Mejoras incrementales | ✅ |
La regla: si la inconsistencia puede causar bugs o pérdida de datos, usa fail-fast. Si la inconsistencia es solo de estilo o completitud, usa resilient.
Patrones de Error Handling en Prompts
Pattern 1: Explicit error reporting
Instruye a cada worker a reportar errores en un formato estructurado:
## Error Handling in System Prompt
If you encounter ANY error during execution:
1. DO NOT silently skip the problematic area
2. Report the error in your output under "### Errors Encountered"
3. Include: what you tried, what happened, and what remains undone
4. Continue with other tasks if possible
### Output Format
...
### Errors Encountered
- **[task]** — Error: [description] — Impact: [what wasn't done]
Pattern 2: Pre-flight checks
Antes de la fase paralela, ejecuta un subagent de verificación:
Antes de lanzar los 4 workers en paralelo, verifica:
1. ¿Existen los 4 directorios de módulos?
2. ¿Hay un CLAUDE.md con convenciones?
3. ¿Los tests pasan en el estado actual?
4. ¿Hay cambios uncommitted que podrían interferir?
Si alguna verificación falla, NO procedas con los workers.
Reporta qué falta y qué debe corregirse.
Pattern 3: Post-merge validation
Después del merge, ejecuta una validación automática:
Después de que el merge coordinator termine:
1. Ejecuta el linter en todos los archivos modificados
2. Ejecuta los tests del proyecto
3. Si el linter o los tests fallan, reporta los errores
4. NO intentes corregir los errores automáticamente — solo reporta
Pattern 4: Checkpoint antes de merge
Si los workers hacen cambios significativos, crea un checkpoint antes del merge:
Antes de aplicar los cambios de los 4 workers:
1. Crea un branch de backup: git checkout -b backup-before-parallel-merge
2. Commit el estado actual
3. Procede con el merge
4. Si algo sale mal, podemos volver al backup
Troubleshooting
"Un subagent paralelo no produce output"
Causa: El subagent falló silenciosamente por falta de permisos.
Diagnóstico:
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude
Re-ejecuta en foreground. Observa si Claude pide permisos que no están en el allowlist del subagent.
Solución: Agrega las herramientas faltantes al campo tools en el frontmatter.
"Un subagent tarda mucho más que los demás"
Causa: El scope de la tarea es más grande de lo esperado, o el subagent está iterando innecesariamente.
Solución:
- Aumenta
maxTurnssi la tarea es legítimamente grande - Acota el scope en el system prompt: "Process ONLY the files listed, do not search for additional files"
- Usa
model: haikupara tareas de lectura/análisis (más rápido que sonnet)
"El merge coordinator reporta inconsistencias que no son reales"
Causa: Los criterios de consistencia del coordinator son demasiado estrictos o genéricos.
Solución: Refina los criterios con ejemplos concretos:
## What counts as inconsistency:
- DIFFERENT error class constructors: AuthError(code, msg) vs ProductError(msg, code)
- DIFFERENT response schemas: {"data": ...} vs {"result": ...}
## What does NOT count as inconsistency:
- Different variable names inside different modules (each module has its own naming)
- Different number of endpoints per module
- Different test file organization
"Algunos cambios se pierden durante el merge de worktrees"
Causa: Conflicto de merge donde una versión sobrescribió a la otra.
Solución:
git log --oneline -10
git diff HEAD~1
Si se perdieron cambios, verifica si hay conflictos no resueltos. Para prevenir, asegúrate de que cada worker edite archivos únicos (sin overlap).
"No sé si usar retry o skip cuando un worker falla"
Regla de decisión:
¿El fallo es transitorio (timeout, error de red)?
→ RETRY con maxTurns más alto
¿El fallo es consistente (mismo error cada vez)?
→ ¿La tarea es crítica?
→ Sí: MANUAL INTERVENTION
→ No: SKIP y completar después
¿El fallo es por configuración (permisos, herramientas)?
→ FIX configuración y RETRY en foreground
Ejercicios
Ejercicio 1: Elegir maxTurns (Fácil)
Un subagent necesita: listar archivos en src/api/ (1 turn), leer cada uno de los 8 archivos (8 turns), buscar patrones de error handling (2 turns), y producir un reporte (1 turn). ¿Qué valor de maxTurns le pondrías?
Ver solución
Estimación: 1 + 8 + 2 + 1 = 12 turns
Con margen del 25%: 12 × 1.25 = 15
maxTurns: 15
15 turns da margen para que el subagent haga lecturas adicionales si necesita contexto (imports, parent classes) sin alcanzar el límite.
Ejercicio 2: Diagnosticar un fallo (Fácil)
Un subagent background con este frontmatter produce el reporte "No pude aplicar los cambios porque no tengo acceso a edición de archivos":
---
name: quick-fixer
tools: Read, Grep, Glob
background: true
---
¿Cuál es el problema y cómo lo corriges?
Ver solución
Problema: El system prompt le pide que aplique cambios (edite archivos), pero tools solo incluye Read, Grep, Glob. No tiene Write ni Edit. En foreground, Claude pediría permiso adicional. En background, la acción falla silenciosamente.
Corrección:
---
name: quick-fixer
tools: Read, Write, Edit, Grep, Glob
background: true
---
Agregar Write y Edit a la allowlist. En background, estas herramientas están pre-aprobadas.
Ejercicio 3: Diseñar fallback strategy (Medio)
Tienes 4 workers paralelos refactorizando módulos. El worker de "payments" falla porque el módulo tiene dependencias circulares que el refactor no puede resolver automáticamente. Diseña la fallback strategy completa: qué pasa con los otros 3 workers, cómo se reporta el fallo, y qué se hace después.
Ver solución
Strategy: Resilient con manual intervention para el módulo fallido
1. Workers auth, products, orders → completan normalmente
2. Worker payments → falla, reporta: "Dependencias circulares entre
payments/processor.py y payments/validator.py impiden refactor automático"
3. Merge coordinator:
- Mergea los cambios de auth, products, orders (los 3 exitosos)
- Lista payments como PENDIENTE con la razón del fallo
- Verifica consistencia de los 3 módulos mergeados
4. Reporte al usuario:
"3 de 4 módulos refactorizados exitosamente.
PENDIENTE: payments — requiere resolución manual de dependencia circular.
Recomendación: resolver la dependencia circular primero, luego re-ejecutar
el worker de payments."
5. Acción manual:
- Resolver la dependencia circular en payments
- Re-ejecutar solo el worker de payments (no los otros 3)
- Verificar consistencia con los módulos ya mergeados
Ejercicio 4: Implementar pre-flight checks (Medio)
Escribe el prompt completo para un subagent de pre-flight check que verifique 5 condiciones antes de lanzar un refactor paralelo de 4 módulos. Si alguna falla, el refactor no debe proceder.
Ver solución
Antes de lanzar los 4 workers de refactoring, ejecuta estas verificaciones:
1. DIRECTORIOS: Verifica que existen src/auth/, src/products/,
src/orders/, src/notifications/
2. GIT STATUS: Verifica que no hay cambios uncommitted
(git status --porcelain debe estar vacío)
3. TESTS: Ejecuta la suite de tests y verifica que todos pasan
(no queremos refactorizar sobre código con tests rotos)
4. CLAUDE.MD: Verifica que existe CLAUDE.md con al menos una
sección de convenciones de código
5. DEPENDENCIAS: Para cada módulo, verifica que no importa
directamente desde otro módulo que se va a refactorizar
(grep "from src.auth" en products, orders, notifications)
Para cada verificación, reporta PASS o FAIL con detalle.
Si CUALQUIER verificación es FAIL, NO procedas con los workers.
Reporta qué debe corregirse primero.
Solo si las 5 verificaciones son PASS, procede con los 4 workers
en paralelo.
Ejercicio 5: Elegir fail-fast vs resilient (Difícil)
Para cada escenario, decide si usarías fail-fast o resilient, y justifica:
- Migrar la autenticación de sessions a JWT en 4 microservicios
- Agregar logging a 6 módulos independientes
- Actualizar imports después de un rename de paquete en 8 archivos
- Refactorizar el schema de la base de datos en 3 tablas relacionadas
Ver solución
1. Auth migration → FAIL-FAST Los 4 microservicios deben usar el mismo mecanismo de auth. Si uno falla y se queda con sessions mientras los otros migran a JWT, hay inconsistencia que rompe la comunicación entre servicios.
2. Logging → RESILIENT Agregar logging es aditivo y no afecta la funcionalidad. Si 4 de 6 módulos quedan con logging y 2 no, el sistema funciona perfectamente — solo tienes menos observabilidad en 2 módulos.
3. Import rename → FAIL-FAST Si 6 de 8 archivos actualizan el import y 2 no, esos 2 archivos producen ImportError al ejecutarse. El sistema está roto. Debe ser todo o nada.
4. DB schema → FAIL-FAST Las 3 tablas están relacionadas (foreign keys). Si una tabla se refactoriza y las otras no, las constraints de FK pueden romperse. Cambios de schema deben ser atómicos.
Patrón: Si la inconsistencia rompe funcionalidad → fail-fast. Si la inconsistencia es solo cosmética o de completitud → resilient.
Ejercicio 6: Diseñar un flujo resiliente completo (Difícil)
Diseña un flujo de "code quality improvement" para un proyecto con 5 módulos. Cada módulo necesita: agregar type hints, mejorar docstrings, y standardizar error handling. Diseña el flujo completo con fallback strategy, pre-flight checks, post-merge validation, y manual intervention triggers.
Ver solución
PHASE 0 — PRE-FLIGHT (secuencial)
pre-flight-checker:
- [ ] 5 módulos existen
- [ ] Tests pasan (baseline)
- [ ] Git limpio (no uncommitted changes)
- [ ] CLAUDE.md tiene convenciones de type hints y docstrings
→ Si FAIL: reportar y STOP
PHASE 1 — PARALLEL WORKERS (5 workers con worktree)
Para cada módulo: type-hints + docstrings + error-handling
Fallback por worker:
- maxTurns: 25 (con margen)
- Si timeout: marcar como PARTIAL, continuar con demás
- Si error de permisos: marcar como FAILED, continuar
Estrategia global: RESILIENT
- Mínimo aceptable: 3 de 5 workers exitosos
- Si < 3 exitosos: FAIL-FAST el flujo completo
PHASE 2 — MERGE COORDINATOR (secuencial)
Verificar:
- Mismo type hint style (Optional[X] vs X | None)
- Mismo docstring format (Google vs NumPy)
- Mismo exception pattern
Si inconsistencias: reportar y recomendar fix
Si consistente: proceder
PHASE 3 — POST-MERGE VALIDATION (secuencial)
- Ejecutar mypy (verificar type hints)
- Ejecutar tests (no regresiones)
- Ejecutar linter
Si mypy falla: reportar errores de tipos
Si tests fallan: ROLLBACK (git reset, reportar)
Si linter falla: reportar warnings (no bloquear)
PHASE 4 — REPORT
- Módulos completados: [list]
- Módulos parciales: [list con razón]
- Módulos fallidos: [list con razón]
- Validación: [mypy, tests, linter results]
- Manual TODO: [tareas pendientes para completar]
MANUAL INTERVENTION TRIGGERS:
1. Pre-flight: módulo no existe → verificar estructura del proyecto
2. Worker: dependencia circular → resolver manualmente
3. Merge: inconsistencia de patterns → decidir cuál adoptar
4. Validation: tests fallan → analizar si es regresión o test flaky
Resumen
maxTurnses el timeout de los subagents — estima los turns necesarios y agrega 25% de margen- Los subagents background tienen permisos pre-aprobados del allowlist de
tools— si falta una herramienta, la acción falla silenciosamente - Cuatro estrategias de fallback: retry (transitorio), skip (no crítico), manual intervention (decisión humana), graceful degradation (resultado parcial funcional)
- Fail-fast para tareas donde la inconsistencia rompe funcionalidad; resilient para tareas donde la completitud parcial es aceptable
- Pre-flight checks previenen fallos predecibles; post-merge validation detecta problemas introducidos
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1para debugging — fuerza ejecución secuencial en foreground- Diagnostica fallos verificando: ¿produjo output? ¿formato correcto? ¿completo? Si la respuesta es "no", re-ejecuta en foreground
- Diseña subagents idempotentes cuando sea posible — que puedan re-ejecutarse sin efectos secundarios
Recursos Adicionales
- Create Custom Subagents (Anthropic Docs) — Documentación oficial con
maxTurns,background, y permisos - Claude Code Sub-agents — Background Execution — Detalles de permisos pre-aprobados y resume en foreground
- Claude Code CLI Reference — Variable
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSy otros flags de debugging - Claude Code Best Practices — Patrones de error handling y delegación robusta
- Claude Code Tips and Tricks — Tips para monitoreo y debugging
- Prompt Engineering: Be Clear and Direct — Instrucciones claras para error reporting en system prompts
- Git Reset Documentation — Referencia para rollback de cambios cuando la validación falla
- Claude Models Documentation — Context windows y limitaciones por modelo
Siguiente cápsula: En la cápsula 05 construirás el proyecto completo — un refactor paralelo de 4 módulos con workers aislados en worktrees, un merge coordinator que verifica consistencia, pre-flight checks, error handling, y post-merge validation. Todo lo que aprendiste en las cápsulas 02, 03, y 04 se integra en un flujo funcional end-to-end.