3. Dependency Resolution y Merge de Resultados

Descripción

Lanzar subagents en paralelo es la parte fácil. La parte difícil es coordinar los resultados. Cuando 4 subagents trabajan simultáneamente, cada uno produce su propio output, modifica sus propios archivos, y termina en su propio momento. El subagent de auth termina en 30 segundos, el de products en 2 minutos, el de orders en 45 segundos, el de notifications en 20 segundos. ¿Cómo combinas 4 conjuntos de cambios en un resultado coherente? ¿Qué pasa si dos subagents modificaron un archivo compartido como config.py? ¿Cómo verificas que los cambios de uno no contradicen los del otro?

La respuesta tiene dos partes. Primero, el dependency graph — la herramienta mental que usas antes de paralelizar para identificar qué tareas son realmente independientes y cuáles tienen dependencias ocultas. Segundo, la estrategia de merge — cómo combinas resultados, detectas conflictos, y produces un output unificado. Git worktrees resuelven la mayoría de conflictos de archivos automáticamente, pero los conflictos lógicos (dos agentes toman decisiones inconsistentes) requieren coordinación explícita.

Al terminar esta cápsula sabrás diseñar dependency graphs para cualquier conjunto de tareas, elegir la estrategia de merge correcta, y resolver conflictos que el merge automático no puede manejar.

Dependency Graph: La Herramienta Mental

Qué es un dependency graph

Un dependency graph es un modelo mental (o visual) de qué tareas dependen de cuáles. Las flechas van de la dependencia al dependiente:

Sin dependencias (todo paralelo):

[auth] [products] [orders] [notifications]
  ↓        ↓         ↓          ↓
  ──────── merge coordinator ────────

Con dependencias (hybrid):

[models]
  ↓
  ├── [routes] ── paralelo ── [docs]
  ↓
[tests]
  ↓
[deploy]

El grafo te dice inmediatamente qué puede ir en paralelo (nodos sin flechas entre sí) y qué debe esperar (nodos con flechas).

Cómo construir el dependency graph

Para cualquier conjunto de tareas, hazte estas 4 preguntas por cada par de tareas:

1. ¿Tarea B necesita el output de Tarea A como input?

Ejemplo: el tester necesita el código del implementer
→ implementer → tester (secuencial)

2. ¿Ambas tareas leen/escriben el mismo archivo?

Ejemplo: auth y products ambos importan desde src/config.py
→ Si solo leen: paralelo (sin conflicto)
→ Si ambos escriben: secuencial, o paralelo con worktree + merge cuidadoso

3. ¿El resultado de Tarea A cambia las asunciones de Tarea B?

Ejemplo: si A cambia la interfaz de User model, B que genera tests para User
está trabajando con asunciones inválidas
→ A antes que B (secuencial)

4. ¿Pueden ambas empezar ahora mismo con lo que ya existe?

Ejemplo: refactor de auth y refactor de products — ambos módulos existen,
ambos tienen código que refactorizar, ninguno necesita al otro
→ paralelo

Ejemplo: Planning de un refactor real

Tienes estas 6 tareas:

1. Actualizar models de Pydantic v1 a v2 en src/models/
2. Actualizar routes que usan esos models en src/routes/
3. Actualizar utils compartidos en src/utils/
4. Actualizar tests en tests/
5. Regenerar documentación de la API
6. Correr el linter final

Dependency graph:

[1. models] ──→ [2. routes] ──→ [4. tests]
     │                              ↓
     └──→ [3. utils]           [6. linter]
     │
     └──→ [5. docs]

Análisis:
- 1 (models) no depende de nada → empieza primero
- 2 (routes) depende de 1 → espera a models
- 3 (utils) depende de 1 (puede importar models) → espera a models
- 4 (tests) depende de 2 y 3 → espera a routes y utils
- 5 (docs) depende de 1 (documenta models) → espera a models
- 6 (linter) depende de todo → va al final

Flujo optimizado:
Fase 1: [1. models]                         ← secuencial
Fase 2: [2. routes] ║ [3. utils] ║ [5. docs] ← paralelo (3 tareas)
Fase 3: [4. tests]                           ← secuencial
Fase 4: [6. linter]                          ← secuencial

De 6 fases secuenciales a 4, con la Fase 2 ejecutando 3 tareas en paralelo. Si cada tarea toma 2 minutos: secuencial = 12 min, optimizado = 8 min.

Dependencias ocultas

Las dependencias más peligrosas son las que no son obvias:

❌ Dependencia oculta: archivo compartido
auth/ importa desde shared/validators.py
products/ importa desde shared/validators.py
→ Si ambos refactors tocan validators.py, hay conflicto

❌ Dependencia oculta: convención implícita
auth/ decide usar snake_case para response fields
products/ decide usar camelCase para response fields
→ Sin coordinación, producen APIs inconsistentes

❌ Dependencia oculta: shared state
auth/ crea una tabla users en la DB
orders/ crea una tabla orders con FK a users
→ Si orders se refactoriza sin considerar auth, puede romper la FK

Para detectarlas, antes de paralelizar pregúntate: "¿Estos módulos comparten archivos, convenciones, o estado?"

Coordinación de Resultados: Qué Pasa Cuando Terminan

El problema del timing

4 subagents paralelos rara vez terminan al mismo tiempo:

t=0s   → lanza auth, products, orders, notifications
t=20s  → notifications termina (módulo pequeño)
t=30s  → auth termina
t=45s  → orders termina
t=120s → products termina (módulo grande)

Claude maneja esto automáticamente: espera a que todos los subagents en background terminen antes de consolidar resultados. Tú no necesitas hacer polling ni verificar estado — Claude sabe cuándo todos completaron.

Tres estrategias de merge

Estrategia 1: Consolidación por Claude (default)

Claude lee los resultados de todos los subagents y produce un resumen unificado. Es la estrategia más simple y funciona para análisis y reportes.

Resultados de 3 subagents → Claude consolida → Reporte unificado

Prompt:
"Cuando los 3 análisis terminen, consolida en un solo reporte
con las top 10 observaciones ordenadas por prioridad."

Cuándo usarla: Cuando los subagents producen reportes o análisis (no editan archivos). La consolidación es simplemente combinar información.

Estrategia 2: Merge via git worktrees (para ediciones)

Cuando los subagents editan archivos en worktrees aislados, los cambios se mergean via git. Cada worktree produce un conjunto de diffs que se aplican al repositorio principal.

Worktree auth → diff de cambios en src/auth/
Worktree products → diff de cambios en src/products/
Worktree orders → diff de cambios en src/orders/

→ Merge automático si no hay conflictos
→ Conflictos presentados para resolución manual si los hay

Cuándo usarla: Cuando los subagents editan archivos y necesitas que los cambios se apliquen al repositorio.

Estrategia 3: Merge coordinator subagent

Un subagent dedicado que revisa los resultados de los workers paralelos, verifica consistencia, y produce el output final.

---
name: merge-coordinator
description: Reviews and merges results from parallel workers. Resolves inconsistencies.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 20
---

## Role
You are a merge coordinator. After parallel workers complete their tasks,
you review all changes, verify consistency, and produce a unified report.

## Process
1. Read the output of each parallel worker
2. Check for inconsistencies between workers
3. Verify shared files weren't modified inconsistently
4. Check that naming conventions are consistent across modules
5. Produce the consolidated report

## Consistency Checks
- Same naming convention across all modules
- Compatible import statements
- No conflicting changes to shared files
- Error handling patterns are consistent

Cuándo usarla: Cuando necesitas verificación activa de consistencia, no solo concatenación de resultados. Es la estrategia más robusta pero también la más costosa (un subagent adicional).

Git Worktrees en Detalle

El ciclo de vida de un worktree

1. CREAR — Claude Code crea un worktree temporal para el subagent
   git worktree add /tmp/worktree-auth-xxxxx -b temp-auth HEAD

2. TRABAJAR — El subagent opera exclusivamente en el worktree
   /tmp/worktree-auth-xxxxx/src/auth/  ← edita aquí

3. COMPLETAR — El subagent termina su trabajo
   (reporta qué archivos modificó)

4. MERGE — Los cambios se aplican al repositorio principal
   (si hay conflictos, se resuelven)

5. LIMPIAR — El worktree temporal se elimina
   git worktree remove /tmp/worktree-auth-xxxxx

Si el subagent no modificó ningún archivo, el paso 4 se salta y el worktree se limpia directamente.

Cuándo hay conflictos de merge

Los conflictos de merge entre worktrees ocurren cuando dos subagents modifican el mismo archivo. Esto es raro si diseñas bien tus dependency graphs, pero puede pasar:

Subagent A (worktree auth):
  Modifica src/config.py — agrega AUTH_SECRET_KEY

Subagent B (worktree products):
  Modifica src/config.py — agrega PRODUCTS_PAGE_SIZE

→ Conflicto de merge en src/config.py

Cuando esto sucede, Claude te presenta el conflicto con las dos versiones y te pide que elijas o combines manualmente. La solución preventiva es más efectiva que la reactiva:

Prevención de conflictos:

1. Identifica archivos compartidos antes de paralelizar
2. Aísla la edición de archivos compartidos en una fase secuencial previa
3. Restringe el scope en el system prompt: "ONLY modify files inside src/auth/"

Fase 0 (secuencial): Actualizar src/config.py con TODOS los settings necesarios
Fase 1 (paralelo): Cada subagent trabaja en su módulo sin tocar config.py

Worktree vs no-worktree: decisión rápida

Regla simple: si hay más de un subagent editando archivos en paralelo, usa worktrees.

Patrones de Coordinación

Pattern 1: Fan-out / Fan-in

El patrón más común. Un coordinador lanza N workers en paralelo, espera resultados, y produce un output consolidado.

           ┌── worker 1 ──┐
Prompt ──→ ├── worker 2 ──┤ ──→ Consolidación ──→ Resultado
           ├── worker 3 ──┤
           └── worker 4 ──┘

Prompt:
"Analiza estos 4 módulos en paralelo con subagents separados.
Cuando todos terminen, dame un reporte unificado con:
- Top issues por módulo
- Patrones comunes entre módulos
- Prioridades de refactoring"

Pattern 2: Parallel-then-sequential

Los workers paralelos producen outputs intermedios que alimentan una fase secuencial.

Fase 1:    ┌── researcher A ──┐
(paralelo) └── researcher B ──┘
                    ↓
Fase 2:       planner (secuencial)
                    ↓
Fase 3:    ┌── implementer A ──┐
(paralelo) └── implementer B ──┘
                    ↓
Fase 4:       tester (secuencial)

Prompt:
"Fase 1: Investiga auth y products en paralelo.
 Fase 2: Con los hallazgos de ambos, crea un plan de refactoring unificado.
 Fase 3: Implementa el refactoring de auth y products en paralelo según el plan.
 Fase 4: Ejecuta todos los tests."

Pattern 3: Pipeline con etapas paralelas

Un pipeline donde algunas etapas son paralelas y otras secuenciales.

[models] ──→ [routes ║ utils ║ docs] ──→ [tests] ──→ [lint ║ format]

Prompt:
"Ejecuta este flujo en orden:
1. Actualiza los models (secuencial — es la base de todo)
2. Cuando models termine, actualiza routes, utils, y docs EN PARALELO
3. Cuando los 3 de la fase 2 terminen, ejecuta los tests
4. Cuando los tests pasen, ejecuta lint y format en paralelo"

Pattern 4: Competitive (elige el mejor resultado)

Dos subagents abordan la misma tarea con estrategias diferentes. Tú eliges el mejor resultado.

           ┌── approach A (e.g., refactor incremental) ──┐
Problema ──┤                                               ├──→ Elegir mejor
           └── approach B (e.g., rewrite completo)       ──┘

Prompt:
"Propón dos enfoques para refactorizar el módulo de auth:
- Subagent A: refactor incremental manteniendo la estructura actual
- Subagent B: rewrite completo con una nueva arquitectura

Ambos en paralelo. Cuando terminen, compara y recomienda cuál usar
basándote en riesgo, tiempo, y mantenibilidad."

Resolución de Conflictos

Conflictos de archivos

Cuando dos worktrees modifican el mismo archivo, git detecta el conflicto durante el merge:

<<<<<<< HEAD (worktree auth)
AUTH_SECRET_KEY = "change-me"
AUTH_TOKEN_EXPIRY = 3600
=======
PRODUCTS_PAGE_SIZE = 20
PRODUCTS_CACHE_TTL = 300
>>>>>>> worktree-products

Resolución: En este caso, ambos cambios son compatibles — ambos agregan settings diferentes. La resolución correcta es mantener ambos:

AUTH_SECRET_KEY = "change-me"
AUTH_TOKEN_EXPIRY = 3600
PRODUCTS_PAGE_SIZE = 20
PRODUCTS_CACHE_TTL = 300

Claude puede hacer este merge automáticamente si el conflicto es simple (adiciones en zonas diferentes). Para conflictos complejos (modificaciones de la misma línea), te lo presenta para resolución manual.

Conflictos lógicos

Los conflictos más difíciles no son de archivos — son de lógica. Dos subagents toman decisiones inconsistentes:

Subagent auth: decide usar HTTPException(status_code=401, detail="...")
Subagent products: decide usar custom AuthError(message="...")

No hay conflicto de archivos — cada uno editó su propio módulo.
Pero hay inconsistencia lógica: dos patrones de error para auth.

Resolución: Un merge coordinator subagent que verifica consistencia:

## Consistency Checks
After all workers complete, verify:
- Same error handling pattern across all modules
- Same response format (snake_case vs camelCase)
- Same auth verification approach
- Compatible import paths

Conflictos de convención

Subagents paralelos sin memoria compartida pueden divergir en convenciones:

Subagent auth: funciones con docstrings Google-style
Subagent products: funciones con docstrings NumPy-style

Prevención (mejor que resolución):

1. Usa subagents con memory: project (Módulo 2) — las convenciones están en la memoria compartida
2. En el system prompt de cada worker, referencia CLAUDE.md explícitamente
3. El merge coordinator verifica convenciones como parte de su checklist

Manual Merge vs Worktree Isolation

Cuándo usar cada enfoque

La recomendación práctica

• Solo lectura paralela: Sin worktree, sin merge. Consolida reportes.
• Edición paralela de módulos independientes: Worktree para cada worker. Merge automático sin conflictos.
• Edición paralela con archivos compartidos: Worktree + fase previa secuencial para archivos compartidos + merge coordinator.

Ejemplo Completo: Merge Coordinado de 3 Workers

Setup

3 workers paralelos refactorizan módulos independientes. Un merge coordinator verifica la consistencia al final.

Worker subagent file (.claude/agents/module-worker.md):

---
name: module-worker
description: Refactors a specific module following project conventions. Runs in isolated worktree.
tools: Read, Write, Edit, Grep, Glob
model: sonnet
background: true
isolation: worktree
maxTurns: 20
memory: project
---

## Role
You refactor one specific module. Work ONLY in the module specified.

## Constraints
- ONLY modify files in the specified module directory
- Follow conventions from CLAUDE.md and your memory
- Use the same error handling pattern as existing modules
- Maintain existing public API — only change internals

## Output Format
### Refactor Report: [module]
**Files modified:** [list]
**Changes:** [description of each change]
**Conventions applied:** [from memory/CLAUDE.md]
**Potential conflicts:** [any shared file touched, any convention questions]

Merge coordinator (.claude/agents/merge-coordinator.md):

---
name: merge-coordinator
description: Reviews parallel worker results for consistency and produces unified report.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
---

## Role
You are a merge coordinator. After parallel workers complete, you verify
consistency across all changes and produce a unified report.

## Process
1. Read the report from each worker
2. Run consistency checks (see below)
3. If inconsistencies found, list them with specific fix recommendations
4. Produce the unified report

## Consistency Checks
- [ ] Same naming convention (snake_case vs camelCase) across all modules
- [ ] Same error handling pattern (custom exceptions vs HTTPException)
- [ ] Same response model pattern (Pydantic, dataclass, dict)
- [ ] No conflicting changes to shared files (config, utils, __init__)
- [ ] Import paths are consistent and valid
- [ ] No circular dependencies introduced

## Output Format
### Merge Coordination Report

**Workers completed:** [n] of [n]
**Consistency status:** [CONSISTENT | INCONSISTENCIES_FOUND]

#### Per-Worker Summary
- **[module]:** [n] files changed, [summary]

#### Consistency Check Results
- [ ] Naming: [PASS/FAIL — detail]
- [ ] Error handling: [PASS/FAIL — detail]
- [ ] Response models: [PASS/FAIL — detail]
- [ ] Shared files: [PASS/FAIL — detail]
- [ ] Imports: [PASS/FAIL — detail]
- [ ] Circular deps: [PASS/FAIL — detail]

#### Inconsistencies Found
(If any)
- **[inconsistency]** — Found in [modules] — Recommendation: [fix]

#### Final Verdict
[MERGE_READY | NEEDS_FIXES]

El prompt de ejecución

Ejecuta este flujo:

Fase 1 (paralelo): Usa el module-worker para refactorizar estos 3 módulos
simultáneamente, cada uno en un worktree aislado:
1. src/auth/ — actualizar error handling a custom exceptions
2. src/products/ — actualizar error handling a custom exceptions
3. src/orders/ — actualizar error handling a custom exceptions

Fase 2 (secuencial): Cuando los 3 workers terminen, usa el merge-coordinator
para verificar que los cambios son consistentes entre sí.

Si el merge-coordinator reporta inconsistencias, corrígelas antes de finalizar.

Output esperado del merge coordinator

### Merge Coordination Report

**Workers completed:** 3 of 3
**Consistency status:** INCONSISTENCIES_FOUND

#### Per-Worker Summary
- **auth:** 4 files changed, migrated to AuthError custom exception
- **products:** 3 files changed, migrated to ProductError custom exception
- **orders:** 5 files changed, migrated to OrderError custom exception

#### Consistency Check Results
- [✅] Naming: PASS — all use snake_case
- [⚠️] Error handling: INCONSISTENCY — auth uses AuthError(code, message),
       products uses ProductError(message, status_code) — different field order
- [✅] Response models: PASS — all use Pydantic v2
- [✅] Shared files: PASS — no shared files modified
- [✅] Imports: PASS
- [✅] Circular deps: PASS

#### Inconsistencies Found
- **Custom exception constructor** — auth: (code, message), products:
  (message, status_code) — Recommendation: standardize to (message, code)
  matching Python convention of message-first

#### Final Verdict
NEEDS_FIXES — 1 inconsistency to resolve before merge

Troubleshooting

"Los resultados consolidados pierden detalle"

Causa: Claude resume demasiado al consolidar reportes de múltiples subagents.

Solución: Sé explícito sobre qué preservar:

Al consolidar, incluye TODOS los hallazgos de cada subagent.
No resumas ni omitas. Cada issue individual debe aparecer en el
reporte final con su archivo, línea, y descripción original.

"El merge coordinator no detecta inconsistencias"

Causa: El merge coordinator no tiene criterios suficientemente específicos.

Solución: Agrega criterios concretos con ejemplos de qué verificar:

Check that ALL modules use the same pattern for:
- Exception class: ClassName(message: str, code: int)
- HTTP responses: JSONResponse with {"detail": ..., "code": ...}
- Logging: logger.error(f"[MODULE] {message}")

If any module deviates, report the specific deviation.

"El worktree merge tiene conflictos inesperados"

Causa: Los subagents modificaron un archivo que no debían (fuera de su módulo).

Solución: Refuerza la restricción de scope en cada worker:

CRITICAL: You MUST only modify files inside [module_path].
If you need to modify a file outside this path, STOP and report it
as a "Potential conflict" in your output instead of modifying it.

"No sé si los subagents terminaron en orden correcto"

Causa: Con ejecución paralela, el orden de completación no está garantizado.

Solución: No necesitas controlar el orden. Claude espera a que todos terminen antes de pasar a la siguiente fase. Si necesitas que un subagent específico termine primero, hazlo secuencial.

"Dos subagents toman decisiones contradictorias sobre convenciones"

Causa: No tienen acceso a convenciones compartidas.

Solución: Usa subagents con memory: project (Módulo 2). Las convenciones registradas en la memoria compartida via git garantizan que todos siguen las mismas reglas. Adicionalmente, referencia CLAUDE.md en cada system prompt.

Ejercicios

Ejercicio 1: Dibujar un dependency graph (Fácil)

Dado este conjunto de tareas, dibuja el dependency graph y determina qué puede ir en paralelo:

1. Crear modelos SQLAlchemy
2. Crear schemas Pydantic basados en los modelos
3. Crear endpoints CRUD
4. Crear tests para los endpoints
5. Agregar documentación OpenAPI
6. Configurar CI pipeline

Dependency graph:

[1. Models]
    ↓
[2. Schemas] ──→ [5. Docs OpenAPI]
    ↓
[3. Endpoints] ──→ [4. Tests]
                        ↓
                   [6. CI pipeline]

Flujo optimizado:

Fase 1: [1. Models]                    ← secuencial
Fase 2: [2. Schemas]                   ← secuencial (depende de models)
Fase 3: [3. Endpoints] ║ [5. Docs]    ← paralelo
Fase 4: [4. Tests]                     ← secuencial (depende de endpoints)
Fase 5: [6. CI pipeline]              ← secuencial (depende de tests)

Ejercicio 2: Identificar dependencias ocultas (Fácil)

Estos 3 refactors parecen independientes. Identifica la dependencia oculta:

1. Refactorizar src/auth/ para usar JWT en lugar de sessions
2. Refactorizar src/orders/ para agregar soft delete
3. Refactorizar src/middleware/ para agregar rate limiting

auth ──→ middleware (middleware depende de la interfaz de auth)
orders (independiente de ambos)

Flujo correcto:
Fase 1: [auth] ║ [orders]     ← paralelo (independientes entre sí)
Fase 2: [middleware]            ← secuencial (espera a auth)

Ejercicio 3: Diseñar un merge coordinator (Medio)

Diseña el system prompt para un merge coordinator que verifica la consistencia de un refactor paralelo de 4 microservicios. Cada microservicio debe usar el mismo patrón de health check, el mismo formato de logging, y el mismo schema de error response.

## Role
You verify that 4 microservices refactored in parallel follow identical patterns.

## Consistency Checks

### Health Check Pattern
Every service MUST have:
- GET /health endpoint
- Response: {"status": "healthy", "service": "[name]", "version": "[semver]"}
- No authentication required

### Logging Format
Every log statement MUST follow:
- logger.[level]("[SERVICE_NAME] [action] [detail]")
- Structured fields: service, action, user_id (if applicable), duration_ms

### Error Response Schema
Every error response MUST use:
- {"error": {"code": "[SERVICE]_[ERROR]", "message": "...", "details": {}}}
- HTTP status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 500 (internal)

## Process
1. For each microservice, grep for health check endpoint
2. For each microservice, grep for logger.* calls
3. For each microservice, grep for error response patterns
4. Compare against the patterns above
5. Report deviations

## Output: per-check PASS/FAIL with specific file:line for failures

Ejercicio 4: Resolver un conflicto lógico (Medio)

Dos subagents completaron en paralelo. Sus reportes dicen:

• Worker auth: "Migré a bcrypt para password hashing. Hash format: $2b$12$..."
• Worker admin: "Implementé password reset. Uso sha256 para generar tokens temporales de reset."

¿Hay un conflicto lógico? Si sí, ¿cuál es y cómo lo resolverías?

Ejercicio 5: Planificar un merge complejo (Difícil)

Tienes 4 workers paralelos que completaron sus tareas. Cada uno modificó archivos en su módulo, pero todos también modificaron src/__init__.py para agregar sus exports. Diseña la estrategia de merge que evite conflictos en __init__.py.

Fase 0 (antes de workers):
  Identificar que src/__init__.py es un archivo compartido
  
Fase 1 (paralelo con worktrees):
  Workers 1-4 refactorizan sus módulos
  RESTRICCIÓN: "Do NOT modify src/__init__.py"
  Cada worker REPORTA qué exports necesita agregar

Fase 2 (secuencial — merge coordinator):
  1. Lee los reportes de los 4 workers
  2. Recopila todos los exports necesarios
  3. Modifica src/__init__.py UNA VEZ con todos los exports
  4. Verifica que los imports son válidos

Ejercicio 6: Diseñar flujo hybrid completo (Difícil)

Diseña el flujo completo para: "Migrar una API de REST a GraphQL. La API tiene 4 recursos: users, products, orders, payments. Cada recurso tiene su propio router y modelo."

Define todas las fases, qué es paralelo vs secuencial, qué subagents necesitas, y dónde podrían surgir conflictos.

Análisis de dependencias:
- GraphQL schema setup (base) → debe existir antes de resolvers
- Los 4 resources son independientes entre sí para resolvers
- Pero todos comparten: schema types, context, middleware
- Tests necesitan todo el código terminado

Flujo:

Fase 0 — SECUENCIAL (setup compartido):
  graphql-architect (sonnet)
  → Instalar dependencias (strawberry/ariadne)
  → Crear schema base, context, middleware
  → Definir type patterns que todos los resolvers seguirán

Fase 1 — PARALELO (4 workers con worktree):
  ├── resource-migrator → users (types + queries + mutations)
  ├── resource-migrator → products
  ├── resource-migrator → orders
  └── resource-migrator → payments

Fase 2 — SECUENCIAL (merge):
  merge-coordinator
  → Verificar que los 4 resources usan los mismos patterns
  → Verificar que los types no conflictúan
  → Unificar el schema registry
  → Verificar imports

Fase 3 — PARALELO (tests):
  ├── test-generator → tests para users + products
  └── test-generator → tests para orders + payments

Fase 4 — SECUENCIAL:
  code-tester → ejecutar suite completa

Conflictos posibles:
1. schema.py — todos los types se registran ahí
   → Solución: cada worker reporta sus types, merge-coordinator los registra
2. context.py — cada resource puede necesitar dataloaders
   → Solución: fase 0 define el pattern, workers lo siguen
3. Naming: UserType vs UserGraphQLType
   → Solución: fase 0 define la convención

Resumen

• El dependency graph es la herramienta mental esencial — antes de paralelizar, dibuja (mentalmente) qué depende de qué
• Las dependencias ocultas (archivos compartidos, convenciones implícitas, shared state) son las más peligrosas — preguntar "¿comparten algo?" las detecta
• Tres estrategias de merge: consolidación por Claude (reportes), git worktrees (ediciones), merge coordinator (consistencia verificada)
• Los conflictos de archivos se detectan con git; los conflictos lógicos requieren un merge coordinator con criterios específicos
• Prevenir conflictos es mejor que resolverlos: identifica archivos compartidos y edítalos secuencialmente antes de la fase paralela
• El merge coordinator es un subagent que verifica consistencia — naming, error handling, response format — con un checklist explícito
• El patrón parallel-then-sequential (fan-out/fan-in) es el más común: workers en paralelo, coordinación secuencial al final
• Los subagents con memory: project (Módulo 2) reducen conflictos de convención porque comparten contexto via git

Recursos Adicionales

1. Create Custom Subagents (Anthropic Docs) — Documentación oficial con isolation: worktree y background
2. Claude Code Sub-agents — Worktree Isolation — Referencia de aislamiento via worktrees
3. Git Worktrees Documentation — Referencia oficial de git worktrees
4. Git Merge Documentation — Resolución de conflictos de merge
5. Claude Code Best Practices — Patrones de delegación y coordinación
6. Prompt Engineering: Give Claude a Role — Diseño de roles para merge coordinators
7. Claude Code Tips and Tricks — Tips para coordinación de subagents
8. Claude Models Documentation — Referencia de modelos para elegir el correcto para coordinators vs workers

Siguiente cápsula: En la cápsula 04 aprenderás qué hacer cuando las cosas salen mal — timeout con maxTurns, errores de permisos en background, fallback strategies, y debugging de subagents paralelos. Porque un sistema paralelo que funciona en el happy path pero colapsa ante el primer error no es un sistema — es una demo.