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 tareamaxTurns recomendadoRazonamiento
Análisis de 1-2 archivos5-8Read + Grep + reportar
Revisión de un módulo10-15Listar archivos + leer cada uno + reportar
Implementación de cambios15-25Leer + editar + verificar por archivo
Refactoring de un módulo completo20-30Múltiples archivos, ediciones iterativas
Investigación amplia del codebase10-15Bú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:

  1. El subagent se detiene — no ejecuta más herramientas
  2. Reporta lo que pudo completar hasta ese momento
  3. Claude (main) recibe el resultado parcial
  4. 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ónModo recomendado
Desarrollo normal con subagents conocidosBackground (paralelo)
Desarrollando un nuevo subagentForeground (debugging)
Subagent falla silenciosamenteForeground (debugging)
Verificando permisos de un subagentForeground (debugging)
Producción / uso diarioBackground (paralelo)
Presentación o demostraciónForeground (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

EscenarioFail-fastResilient
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:

  1. Aumenta maxTurns si la tarea es legítimamente grande
  2. Acota el scope en el system prompt: "Process ONLY the files listed, do not search for additional files"
  3. Usa model: haiku para 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:

  1. Migrar la autenticación de sessions a JWT en 4 microservicios
  2. Agregar logging a 6 módulos independientes
  3. Actualizar imports después de un rename de paquete en 8 archivos
  4. 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

  • maxTurns es 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=1 para 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

  1. Create Custom Subagents (Anthropic Docs) — Documentación oficial con maxTurns, background, y permisos
  2. Claude Code Sub-agents — Background Execution — Detalles de permisos pre-aprobados y resume en foreground
  3. Claude Code CLI Reference — Variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS y otros flags de debugging
  4. Claude Code Best Practices — Patrones de error handling y delegación robusta
  5. Claude Code Tips and Tricks — Tips para monitoreo y debugging
  6. Prompt Engineering: Be Clear and Direct — Instrucciones claras para error reporting en system prompts
  7. Git Reset Documentation — Referencia para rollback de cambios cuando la validación falla
  8. 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.