Módulo 3: Parallel Sub-Agent Delegation

5. Proyecto — Refactor Paralelo de 4 Módulos

Descripción del Proyecto

Has aprendido a lanzar subagents en paralelo con background: true, a aislarlos con isolation: worktree para que no conflictúen al editar archivos, a diseñar dependency graphs para identificar tareas independientes, a coordinar resultados con un merge coordinator, y a manejar errores con fallback strategies. Ahora vas a integrar todo en un sistema funcional.

En este proyecto construyes un flujo de refactoring paralelo donde 4 subagents workers refactorizan módulos independientes simultáneamente — cada uno en su propio git worktree — y un merge coordinator verifica la consistencia de los cambios y produce un reporte unificado. El flujo incluye pre-flight checks antes de lanzar workers, error handling resiliente que permite continuar si un worker falla, y post-merge validation que verifica que los tests siguen pasando.

El escenario es concreto: tienes un proyecto con 4 módulos (auth, products, orders, notifications) que necesitan el mismo refactoring — standardizar el error handling a un patrón uniforme de custom exceptions. Los 4 módulos son independientes entre sí para este refactoring, lo que los hace candidatos perfectos para ejecución paralela.

Este es el proyecto culminante del Módulo 3 y de toda la Phase 1. Si los 4 workers ejecutan en paralelo, el coordinator verifica consistencia, y el resultado es un refactoring coherente — has dominado subagents avanzados.

Objetivo del Proyecto

Construir un flujo de refactoring paralelo con 4 workers aislados en worktrees, un merge coordinator, pre-flight checks, y post-merge validation.

Al completar este proyecto:

✅ Tendrás 4 subagent files de workers con background: true e isolation: worktree
✅ Tendrás 1 subagent file de merge coordinator con checklist de consistencia
✅ Los 4 workers se ejecutarán en paralelo, cada uno en su propio worktree
✅ El merge coordinator verificará que los cambios son consistentes
✅ Pre-flight checks validarán el estado del proyecto antes del refactoring
✅ Post-merge validation ejecutará tests para confirmar que no hay regresiones
✅ El flujo será resiliente — si un worker falla, los demás continúan
✅ Habrás ejecutado el flujo completo al menos una vez con resultados verificables

Duración estimada: 1.5-2 horas (setup: 20 min + subagents: 30 min + primera ejecución: 20 min + verificación: 15 min + iteración: 15 min + validación final: 15 min).

Especificaciones Técnicas

Stack Tecnológico

Herramienta: Claude Code v2.1.63+
Subagent files: Markdown con frontmatter YAML
Ubicación: .claude/agents/ (scope proyecto)
Modelos: haiku (pre-flight, coordinator), sonnet (workers)
Isolation: git worktrees para cada worker
Proyecto base: Cualquier proyecto con 4+ módulos en src/, tests, y git

Requisitos del Proyecto Base

Requisito	Mínimo	Ideal
Módulos en `src/`	4 directorios	4 directorios con 3+ archivos cada uno
Tests existentes	5+	15+ con cobertura de los 4 módulos
Commits en git	3+	10+
CLAUDE.md	Básico	Con convenciones de estilo y error handling
Error handling actual	HTTPException o similar	Mixto (lo que vamos a standardizar)

Si tu proyecto no tiene exactamente 4 módulos, adapta el número de workers. Lo importante es que haya al menos 2 módulos independientes para que la paralelización tenga sentido.

Estructura Final del Proyecto

Al terminar, tu proyecto tendrá esta estructura adicional:

your-project/
├── .claude/
│   └── agents/
│       ├── pre-flight-checker.md     ← Verifica antes de lanzar workers
│       ├── error-handling-worker.md   ← Worker para refactoring (×4)
│       ├── merge-coordinator.md       ← Verifica consistencia post-merge
│       ├── code-reviewer.md           ← (del Módulo 1, opcional)
│       ├── code-implementer.md        ← (del Módulo 1, opcional)
│       └── code-tester.md             ← (del Módulo 1, opcional)
├── src/
│   ├── auth/                          ← Worker 1 refactoriza
│   ├── products/                      ← Worker 2 refactoriza
│   ├── orders/                        ← Worker 3 refactoriza
│   └── notifications/                 ← Worker 4 refactoriza
├── tests/
├── CLAUDE.md
└── ...

Guía Paso a Paso

Paso 1: Verificar el Estado del Proyecto

Antes de crear los subagents, verifica que tu proyecto está listo:

cd your-project

ls src/

git status

claude --version

Verifica que tienes al menos 4 directorios de módulos en src/ y que no hay cambios uncommitted. Si hay cambios pendientes, haz commit o stash antes de continuar.

git stash

Crea el directorio de agents si no existe:

mkdir -p .claude/agents

Paso 2: Crear el Pre-Flight Checker

El pre-flight checker verifica que el proyecto está listo para el refactoring paralelo. Se ejecuta antes de lanzar los workers.

Crea .claude/agents/pre-flight-checker.md:

---
name: pre-flight-checker
description: Verifies project state before parallel refactoring. Checks modules exist, git is clean, tests pass, and CLAUDE.md has conventions.
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 12
---

## Role

You are a pre-flight checker. Before parallel workers launch, you verify
that the project is ready. You NEVER modify any file. If any check fails,
the parallel refactoring MUST NOT proceed.

## Process

Run these checks in order. Stop at the first FAIL.

### Check 1: Module directories exist
Verify that the specified module directories exist in src/.

### Check 2: Git status is clean
Run `git status --porcelain`. If output is not empty, FAIL.
Uncommitted changes will conflict with worktrees.

### Check 3: Tests pass (baseline)
Run the test suite. If tests fail, FAIL.
We don't want to refactor on top of broken tests.

### Check 4: CLAUDE.md exists
Verify CLAUDE.md exists in the project root.
Workers need conventions to follow.

### Check 5: No cross-module imports for the refactored concern
For each module pair, check if one imports the error handling
utilities from another. If they share error handling code,
parallel refactoring of error handling could conflict.

## Output Format

Follow this EXACT structure:

Pre-Flight Check Report

Check Results

#	Check	Status	Detail
1	Module directories	[PASS/FAIL]	[detail]
2	Git status clean	[PASS/FAIL]	[detail]
3	Tests pass	[PASS/FAIL]	[n] passed, [n] failed
4	CLAUDE.md exists	[PASS/FAIL]	[detail]
5	No cross-module error imports	[PASS/FAIL]	[detail]

Verdict

[ALL_PASS — Ready for parallel refactoring | BLOCKED — Fix issues first]

Issues to Fix (if any)

[issue] — How to fix: [recommendation]

Paso 3: Crear el Error Handling Worker

Este es el subagent que refactoriza un módulo individual. Se reutiliza para cada módulo — Claude lo lanza 4 veces en paralelo, cada vez con un módulo diferente como target.

Crea .claude/agents/error-handling-worker.md:

---
name: error-handling-worker
description: Refactors error handling in a specific module to use custom exception classes. Runs in isolated worktree for parallel execution.
tools: Read, Write, Edit, Grep, Glob
model: sonnet
background: true
isolation: worktree
maxTurns: 25
memory: project
---

## Role

You are a module refactoring specialist. You refactor error handling in ONE
specific module to use a consistent custom exception pattern. You work in
an isolated git worktree — your changes don't affect other workers.

## Target Exception Pattern

Every module should follow this pattern:

```python
# src/{module}/exceptions.py

class ModuleBaseError(Exception):
    """Base exception for the {module} module."""
    def __init__(self, message: str, code: str = "UNKNOWN_ERROR"):
        self.message = message
        self.code = code
        super().__init__(self.message)

class NotFoundError(ModuleBaseError):
    """Resource not found."""
    def __init__(self, resource: str, identifier: str):
        super().__init__(
            message=f"{resource} with id '{identifier}' not found",
            code=f"{MODULE}_NOT_FOUND"
        )

class ValidationError(ModuleBaseError):
    """Validation failed."""
    def __init__(self, field: str, reason: str):
        super().__init__(
            message=f"Validation failed for '{field}': {reason}",
            code=f"{MODULE}_VALIDATION_ERROR"
        )

class PermissionError(ModuleBaseError):
    """Permission denied."""
    def __init__(self, action: str):
        super().__init__(
            message=f"Permission denied for action: {action}",
            code=f"{MODULE}_PERMISSION_DENIED"
        )

Constraints

ONLY modify files inside the specified module directory (src/{module}/)
NEVER modify files outside your module
NEVER modify test files
NEVER modify shared config or utils outside your module
Follow existing code style in the project
If you need a shared utility that doesn't exist, note it in your report but DO NOT create it outside your module

Process

Read your MEMORY.md for project conventions
List all files in the target module
Read each file to understand current error handling
Create src/{module}/exceptions.py with the custom exception classes
Update each file to use the new exceptions instead of raw HTTPException or generic Exception
Verify no imports break (grep for the old patterns)
Produce the refactoring report
Update your MEMORY.md with new conventions discovered

Refactoring Rules

Replace raise HTTPException(status_code=404, ...) with raise NotFoundError(...)
Replace raise HTTPException(status_code=422, ...) with raise ValidationError(...)
Replace raise HTTPException(status_code=403, ...) with raise PermissionError(...)
Keep HTTPException(status_code=500, ...) for truly unexpected errors
Add exception handler registration in the module's __init__.py if applicable

Output Format

Follow this EXACT structure:

## Refactoring Report: [module name]

**Module:** src/[module]/
**Files modified:** [list]
**Files created:** [list]
**Exceptions defined:** [list of exception classes]

### Changes Made

1. **[file]** — [what changed]
   - Before: `raise HTTPException(status_code=X, detail="...")`
   - After: `raise CustomError(...)`
   - Lines changed: [n]

2. ...

### Exception Hierarchy

ModuleBaseError ├── NotFoundError ├── ValidationError └── PermissionError


### Potential Conflicts

- [any shared file that might need updating but is outside this module]
- [any convention question that the coordinator should verify]

### Not Changed

- [files or patterns left unchanged, with reason]

### Status: [COMPLETE | PARTIAL (reason)]


### Paso 4: Crear el Merge Coordinator

El merge coordinator se ejecuta después de que los 4 workers terminan. Verifica que los cambios son consistentes entre módulos.

Crea `.claude/agents/merge-coordinator.md`:

```markdown
---
name: merge-coordinator
description: Reviews results from parallel error-handling workers. Verifies consistency across modules and produces unified report.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 20
---

## Role

You are a merge coordinator. After 4 parallel workers refactor error handling
in their respective modules, you verify that the changes are consistent across
all modules. You NEVER modify files — you only analyze and report.

## Process

1. Read the refactoring report from each worker
2. For each module, read the new exceptions.py file
3. Run the consistency checks below
4. Verify no shared files were modified by multiple workers
5. Run the test suite to check for regressions
6. Produce the coordination report

## Consistency Checks

### 1. Exception Class Structure
All modules MUST follow the same hierarchy:
- ModuleBaseError(message, code)
- NotFoundError(resource, identifier)
- ValidationError(field, reason)
- PermissionError(action)

Check: same constructor signatures, same base class pattern.

### 2. Error Code Format
All error codes MUST follow: {MODULE}_{ERROR_TYPE}
- AUTH_NOT_FOUND, PRODUCTS_VALIDATION_ERROR, etc.
- Check that MODULE prefix matches the actual module name

### 3. Exception Message Format
All messages MUST be human-readable English sentences.
- "User with id '123' not found" ✅
- "NOT_FOUND_USER_123" ❌

### 4. Import Pattern
All modules MUST import exceptions the same way:
- `from src.{module}.exceptions import NotFoundError, ValidationError`
- NOT: `from src.{module}.exceptions import *`

### 5. No Shared File Conflicts
Verify that workers only modified files inside their own module.
Run: `git diff --name-only` and verify all changes are scoped correctly.

## Output Format

Follow this EXACT structure:

Merge Coordination Report

Workers completed: [n] of 4 Modules: [list] Total files modified: [n]

Per-Module Summary

Module	Files Changed	Exceptions Defined	Status
auth	[n]	[n]	[COMPLETE/PARTIAL]
products	[n]	[n]	[COMPLETE/PARTIAL]
orders	[n]	[n]	[COMPLETE/PARTIAL]
notifications	[n]	[n]	[COMPLETE/PARTIAL]

Consistency Check Results

#	Check	Status	Detail
1	Exception class structure	[PASS/FAIL]	[detail]
2	Error code format	[PASS/FAIL]	[detail]
3	Message format	[PASS/FAIL]	[detail]
4	Import pattern	[PASS/FAIL]	[detail]
5	No shared file conflicts	[PASS/FAIL]	[detail]

Inconsistencies Found

(If any — otherwise write "None found.")

[inconsistency]
- Modules affected: [list]
- Detail: [specific difference]
- Recommendation: [how to fix]

Test Results (Post-Merge)

Tests passed: [n]
Tests failed: [n]
New failures: [list, if any]

Final Verdict

[MERGE_READY | NEEDS_FIXES]

If NEEDS_FIXES:

[fix 1]
[fix 2]

Paso 5: Verificar los 3 Subagents

Antes de ejecutar el flujo, verifica que los 3 subagent files son detectados correctamente.

/agents

Deberías ver:

Project agents (.claude/agents/):
  pre-flight-checker      — Verifies project state before parallel refactoring...
  error-handling-worker   — Refactors error handling in a specific module...
  merge-coordinator       — Reviews results from parallel error-handling workers...

Verifica la tabla de capacidades:

Herramienta	pre-flight-checker	error-handling-worker	merge-coordinator
Read	✅	✅	✅
Write	❌	✅	❌
Edit	❌	✅	❌
Grep	✅	✅	✅
Glob	✅	✅	✅
Bash	✅	❌	✅
background	❌	✅	❌
isolation	❌	worktree	❌

Cada subagent tiene exactamente las herramientas que necesita para su rol.

Paso 6: Ejecutar Pre-Flight Checks

Antes de lanzar los workers, verifica que el proyecto está listo:

Usa el pre-flight-checker para verificar que el proyecto está listo
para un refactoring paralelo de error handling en estos 4 módulos:
src/auth/, src/products/, src/orders/, src/notifications/

Qué verificar en el output:

✅ Los 4 directorios de módulos existen
✅ Git status está limpio
✅ Los tests pasan (baseline)
✅ CLAUDE.md existe
✅ No hay imports cruzados de error handling entre módulos

Si algún check falla:

Módulo no existe: Verifica los nombres de tus módulos y ajusta
Git no está limpio: git add . && git commit -m "pre-refactor state" o git stash
Tests fallan: Corrige los tests primero — no refactorices sobre tests rotos
CLAUDE.md no existe: Crea uno básico con convenciones de tu proyecto
Cross-module imports: Identifica los imports y decide si necesitas una fase secuencial previa

Paso 7: Ejecutar los 4 Workers en Paralelo

Este es el paso central del proyecto. Lanza los 4 workers simultáneamente:

Ejecuta el error-handling-worker para estos 4 módulos EN PARALELO,
cada uno en un worktree aislado:

1. src/auth/ — refactorizar error handling a custom exceptions (AuthBaseError)
2. src/products/ — refactorizar error handling a custom exceptions (ProductsBaseError)
3. src/orders/ — refactorizar error handling a custom exceptions (OrdersBaseError)
4. src/notifications/ — refactorizar error handling a custom exceptions (NotificationsBaseError)

Cada worker debe:
- Crear un archivo exceptions.py en su módulo
- Reemplazar HTTPException con custom exceptions
- Reportar todos los cambios realizados

Si algún worker falla, continúa con los demás (estrategia resiliente).
Cuando todos terminen, dame los 4 reportes individuales.

Qué observar durante la ejecución:

Claude lanza 4 instancias del error-handling-worker en background
Cada worker opera en su propio git worktree
Los workers terminan en momentos diferentes (el módulo más grande tarda más)
Claude espera a que todos terminen antes de presentar resultados

Tiempo esperado: 2-4 minutos (depende del tamaño de los módulos). Comparado con ejecución secuencial que tomaría 8-16 minutos.

Paso 8: Revisar los Reportes de los Workers

Después de que los 4 workers terminan, revisa los reportes individuales:

Para cada worker, verifica:

✅ Se creó src/{module}/exceptions.py con las clases de excepciones
✅ Los archivos del módulo fueron actualizados para usar las custom exceptions
✅ Solo se modificaron archivos dentro del módulo correspondiente
✅ El reporte lista todos los cambios y posibles conflictos
✅ El status es COMPLETE (no PARTIAL)

Si un worker reporta PARTIAL:

Revisa la razón. Si fue por maxTurns insuficiente, puedes re-ejecutar solo ese worker con más turns:

El worker de orders quedó parcial. Re-ejecuta el error-handling-worker
solo para src/orders/ con maxTurns extendido. Los otros 3 módulos
ya están completos.

Paso 9: Ejecutar el Merge Coordinator

Con los 4 workers completados, lanza el merge coordinator:

Usa el merge-coordinator para verificar la consistencia de los cambios
realizados por los 4 workers de error handling.

Verifica que los 4 módulos (auth, products, orders, notifications) usan
el mismo patrón de excepciones, el mismo formato de error codes,
y el mismo estilo de mensajes.

Ejecuta los tests después de verificar la consistencia.

Qué verificar en el output:

✅ Los 4 workers reportan COMPLETE
✅ Todos los consistency checks son PASS
✅ No hay inconsistencias encontradas (o las encontradas son menores)
✅ Los tests pasan después del merge
✅ Verdict es MERGE_READY

Si el coordinator reporta NEEDS_FIXES:

Las inconsistencias más comunes:

Constructor signatures diferentes — un módulo usa (message, code) y otro (code, message):

Corrige la inconsistencia: el módulo de products tiene el constructor
de NotFoundError con los parámetros en orden diferente al de auth.
Usa el orden (resource, identifier) para todos los módulos.

Error code format diferente — un módulo usa AUTH_NOT_FOUND y otro usa auth_not_found:

Standardiza los error codes a UPPER_CASE en todos los módulos.
Los 4 deben seguir el patrón {MODULE}_NOT_FOUND, no {module}_not_found.

Import patterns diferentes — un módulo usa from .exceptions import *:

Actualiza src/notifications/ para usar imports explícitos:
from .exceptions import NotFoundError, ValidationError
en lugar de from .exceptions import *

Paso 10: Post-Merge Validation

Después de resolver cualquier inconsistencia, ejecuta una validación final:

Ejecuta la validación post-merge:
1. Corre el linter en los archivos modificados
2. Ejecuta la suite completa de tests
3. Verifica que no hay imports rotos

Reporta el resultado final.

Verificación manual:

git diff --stat

git diff --name-only

Todos los archivos modificados deben estar dentro de los 4 módulos. Si hay archivos fuera de src/auth/, src/products/, src/orders/, o src/notifications/, un worker violó su restricción de scope.

python -m pytest -v --tb=short 2>&1

Si los tests pasan: el refactoring paralelo fue exitoso.

Paso 11: Commit del Resultado

Si todo está correcto, commitea los cambios:

git add .

git diff --cached --stat

git commit -m "Refactor error handling to custom exceptions across 4 modules

- auth: AuthBaseError, NotFoundError, ValidationError, PermissionError
- products: ProductsBaseError, NotFoundError, ValidationError, PermissionError
- orders: OrdersBaseError, NotFoundError, ValidationError, PermissionError
- notifications: NotificationsBaseError, NotFoundError, ValidationError, PermissionError

All modules follow consistent exception hierarchy, error code format,
and message pattern. Refactored in parallel with 4 isolated workers."

El Flujo Visual Completo

Tu prompt
    │
    ▼
┌─────────────────────────────────────────────┐
│           Claude (conversación main)         │
│                                              │
│  Fase 0: Pre-flight checks                  │
│  ├── pre-flight-checker                      │
│  └── Resultado: ALL_PASS ✅                  │
│                                              │
│  Fase 1: Workers paralelos                   │
│  ├── worker auth         ─── worktree 1 ──┐ │
│  ├── worker products     ─── worktree 2 ──┤ │
│  ├── worker orders       ─── worktree 3 ──┤ │
│  └── worker notifications ── worktree 4 ──┘ │
│       (4 workers ejecutando simultáneamente) │
│                                              │
│  Fase 2: Merge coordination                  │
│  ├── merge-coordinator                       │
│  ├── Consistency checks: 5/5 PASS           │
│  └── Tests: ALL_PASS ✅                     │
│                                              │
│  Fase 3: Resultado final                     │
│  └── Reporte consolidado                    │
└─────────────────────────────────────────────┘

Checklist de Validación

Archivos creados

.claude/agents/pre-flight-checker.md existe y tiene frontmatter válido
.claude/agents/error-handling-worker.md existe con background: true e isolation: worktree
.claude/agents/merge-coordinator.md existe con disallowedTools: Write, Edit

Pre-flight

Los 4 módulos existen en src/
Git status está limpio
Tests pasan antes del refactoring (baseline)
CLAUDE.md existe
No hay imports cruzados de error handling

Workers paralelos

Los 4 workers se ejecutaron en paralelo (no secuencialmente)
Cada worker creó exceptions.py en su módulo
Cada worker solo modificó archivos dentro de su módulo
Cada worker reportó COMPLETE (o PARTIAL con razón)
Los 4 workers produjeron reportes estructurados

Merge coordination

El merge coordinator verificó los 5 consistency checks
Los error codes siguen el formato {MODULE}_{ERROR_TYPE}
Los constructors tienen la misma firma en los 4 módulos
Los imports son explícitos (no import *)
No hay archivos modificados fuera de los 4 módulos

Post-merge validation

Los tests pasan después del refactoring
No hay imports rotos
El linter no reporta errores nuevos
Los cambios están commiteados

Timing

La ejecución paralela fue significativamente más rápida que secuencial
(Opcional) Registraste el tiempo: paralelo = ___ min, estimación secuencial = ___ min

Errores Comunes y Soluciones

Error 1: "Los workers no se ejecutan en paralelo"

Síntoma: Los workers se ejecutan uno después del otro.

Causas posibles:

background: true no está en el frontmatter del worker
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 está activa en el entorno
El prompt no indica claramente que deben ejecutarse en paralelo

Solución:

echo $CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

Si devuelve 1, desactívala:

unset CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

Verifica que el frontmatter del worker tiene background: true. Usa un prompt explícito:

Ejecuta estos 4 workers EN PARALELO, simultáneamente, cada uno
como subagent independiente en background.

Error 2: "Un worker modifica archivos fuera de su módulo"

Síntoma: git diff --name-only muestra archivos fuera de src/{module}/.

Causa: El system prompt dice "ONLY modify files inside src/{module}/" pero la restricción no es técnicamente enforced.

Solución: Agrega una restricción más fuerte al system prompt:

CRITICAL RULE: If the file path does not start with "src/{module}/",
you MUST NOT edit it. Not even if it seems necessary. Instead, report
it as a "Potential Conflict" in your output.

Si ya se hicieron cambios fuera del scope:

git checkout -- src/shared/
git checkout -- src/config.py

Esto revierte los archivos que no debían modificarse.

Error 3: "Los worktrees no se limpian"

Síntoma: git worktree list muestra worktrees huérfanos.

Causa: Un worker crasheó antes de completar normalmente.

Solución:

git worktree list
git worktree prune
git worktree list

prune limpia worktrees cuyos directorios ya no existen.

Error 4: "El merge coordinator encuentra inconsistencias"

Síntoma: El reporte dice NEEDS_FIXES con inconsistencias entre módulos.

Causa: Los workers no tenían suficiente contexto sobre la convención a seguir.

Solución: Corrige las inconsistencias manualmente o con un prompt dirigido:

El merge coordinator encontró que el módulo products usa error codes
en lowercase (products_not_found) mientras los otros 3 usan UPPERCASE
(AUTH_NOT_FOUND). Corrige products para usar UPPERCASE.

Para prevenir: incluye un ejemplo completo del patrón objetivo en el system prompt del worker, con formato exacto de error codes.

Error 5: "Los tests fallan después del refactoring"

Síntoma: Tests que pasaban antes del refactoring ahora fallan.

Causa: Los tests esperan HTTPException pero ahora el código lanza custom exceptions. Los tests necesitan actualizarse para capturar las nuevas excepciones, o necesitas un exception handler que convierta custom exceptions a HTTP responses.

Solución:

Los tests fallan porque esperan HTTPException pero el código ahora
lanza custom exceptions. Hay dos opciones:
1. Agregar un exception handler en FastAPI que convierta
   ModuleBaseError → JSONResponse
2. Actualizar los tests para capturar las custom exceptions

Recomienda la opción 1 (exception handler) y implementa.

La opción 1 es mejor porque mantiene la separación entre la lógica de negocio (custom exceptions) y el framework HTTP (FastAPI responses).

Error 6: "Un worker termina como PARTIAL por maxTurns"

Síntoma: Un worker reporta "PARTIAL — reached turn limit."

Causa: El módulo es más grande de lo esperado y 25 turns no fueron suficientes.

Solución: Re-ejecuta solo ese worker con más turns:

Re-ejecuta el error-handling-worker solo para src/orders/
con maxTurns 35. Los otros 3 módulos ya están completos.
Continúa desde donde quedó — no re-hagas los cambios ya aplicados.

Error 7: "No tengo 4 módulos en mi proyecto"

Síntoma: Tu proyecto tiene 2 o 3 módulos, no 4.

Solución: Adapta el proyecto a tu situación:

2 módulos: Ejecuta 2 workers en paralelo. La ganancia es menor pero el concepto se aplica.
3 módulos: Ejecuta 3 workers. Funciona perfectamente.
6+ módulos: Ejecuta los 4 más importantes en paralelo. Puedes hacer una segunda ronda para los restantes.

Error 8: "El worker y el merge coordinator no se comunican"

Síntoma: El merge coordinator no tiene los reportes de los workers.

Causa: Los subagents no comparten contexto directamente. Claude (main) actúa como intermediario.

Solución: Sé explícito en el prompt de orquestación:

Cuando los 4 workers terminen, pasa los 4 reportes COMPLETOS
al merge-coordinator como contexto. Incluye todos los detalles
de cada reporte — archivos modificados, cambios realizados,
y potential conflicts.

Variaciones del Proyecto

Variación 1: Análisis paralelo (solo lectura)

Si no quieres hacer cambios todavía, ejecuta solo análisis:

Analiza los 4 módulos en paralelo para identificar qué error handling
existe actualmente en cada uno. No modifiques nada — solo reporta.
Después, dame un plan unificado de refactoring.

Variación 2: Refactor incremental

En lugar de refactorizar los 4 módulos de una vez, hazlo en 2 rondas:

Ronda 1: Refactoriza auth y products en paralelo
Ronda 2: Refactoriza orders y notifications en paralelo

Después de cada ronda, verifica consistencia y tests.

Variación 3: Competitive refactoring

Lanza 2 workers con estrategias diferentes para el mismo módulo:

Worker A: Refactoriza auth con custom exception classes
Worker B: Refactoriza auth con un decorator pattern para error handling

Compara ambos enfoques y recomienda cuál adoptar.

Recursos del Proyecto

Create Custom Subagents (Anthropic Docs) — Documentación oficial con background, isolation: worktree, y maxTurns
Claude Code Sub-agents — Background Execution — Referencia de permisos pre-aprobados y ejecución en background
Claude Code Sub-agents — Worktree Isolation — Referencia de git worktrees para aislamiento
Git Worktrees Documentation — Referencia oficial de git worktrees
Claude Code Best Practices — Patrones de delegación y error handling
Claude Code CLI Reference — Variables de entorno como CLAUDE_CODE_DISABLE_BACKGROUND_TASKS

Conexión con el Siguiente Módulo

Has construido un sistema de refactoring paralelo con 4 workers aislados, un merge coordinator, y un flujo robusto con pre-flight checks y post-merge validation. Funciona. Pero lo coordinaste manualmente — tú escribiste el prompt que orquesta las 3 fases, tú decidiste cuándo lanzar el coordinator, tú decidiste la estrategia de fallback.

El Módulo 4: Agent Teams formaliza exactamente esta coordinación. Lo que hiciste aquí con prompts manuales, Agent Teams lo hace con un team lead que gestiona un task board, declara dependencias entre tareas, y coordina teammates automáticamente. El team lead sabe que los 4 workers son paralelos y que el coordinator espera a todos. Lo sabe porque las dependencias están declaradas, no porque tú se lo dijiste en un prompt.

La analogía: este módulo te enseñó a ser el project manager que coordina manualmente un equipo de 4 desarrolladores. Agent Teams te da un sistema de project management (Jira, Linear) donde las dependencias están explícitas y el flujo se ejecuta automáticamente.

Los subagents que creaste aquí — workers especializados con worktree isolation, merge coordinators con checklists de consistencia — son exactamente los que convertirás en teammates de un Agent Team. La transición es directa: los mismos archivos Markdown, los mismos frontmatter YAML, pero ahora orquestados por un team lead en lugar de por tus prompts.

Resumen

Construiste un flujo de refactoring paralelo completo: pre-flight → 4 workers paralelos → merge coordination → post-merge validation
Los 4 workers usan background: true e isolation: worktree para ejecución paralela sin conflictos
El merge coordinator verifica 5 aspectos de consistencia: estructura de excepciones, formato de error codes, formato de mensajes, patrón de imports, y scope de cambios
Pre-flight checks previenen fallos predecibles verificando estado del proyecto antes de lanzar workers
La estrategia de error handling resiliente permite continuar si un worker falla sin afectar a los demás
El resultado es un refactoring coherente de 4 módulos con un patrón uniforme de custom exceptions
La ejecución paralela reduce el tiempo total de ~12 minutos secuenciales a ~4 minutos
Los subagents creados aquí son los building blocks de Agent Teams (Módulo 4) — la misma funcionalidad, pero con coordinación automatizada
Este proyecto cierra Phase 1 — dominas subagents custom (M1), memoria persistente (M2), y delegación paralela (M3)

Siguiente módulo: El Módulo 4 (Agent Teams) toma todo lo que construiste en Phase 1 — subagents especializados, memoria compartida, delegación paralela — y lo formaliza con un team lead, task board, dependencias declaradas, y coordinación automática. Los subagents que creaste aquí se convierten en teammates. La coordinación manual que hiciste aquí se convierte en un sistema declarativo. Pasas de ser el project manager a configurar el sistema de project management.

← Anterior4. Timeout, Error Handling, y Fallback Strategies Siguiente →1. Introducción al Módulo — De Orquestación Manual a Agent Teams