Módulo 8: Proyecto — Sistema Multi-Agente Completo
3. Ejecución — Task Board, Delegación Paralela, Quality Gates
3. Ejecución — Task Board, Delegación Paralela, Quality Gates
Descripción
La configuración está lista. 5 agent files en .claude/agents/, hooks en scripts/hooks/, settings.json conectando todo, CLAUDE.md como constitución, y un plugin empaquetado. Ahora toca ejecutar.
En esta cápsula diseñas un task board de 10 tareas con dependencias reales, lanzas al equipo con claude --agent team-lead, observas cómo frontend y backend trabajan en paralelo, cómo testing valida los entregables, cómo docs/review analiza la calidad, y cómo los hooks bloquean, reportan, y registran cada acción. Es el momento donde todo lo que configuraste se pone a prueba.
Al terminar esta cápsula habrás visto un ciclo completo de ejecución multi-agente: desde el task board hasta el reporte final. Sabrás qué observar, qué puede fallar, y cómo intervenir cuando algo no funciona.
⚠️ FEATURE EXPERIMENTAL
Agent Teams es una feature experimental de Claude Code. La ejecución funciona igual usando el team lead como subagent coordinador (
claude --agent team-lead).Última verificación: Marzo 2026
Diseñando el Task Board
La feature a implementar
Vamos a usar como ejemplo una feature de gestión de tareas (todo list) con estas capacidades:
- Endpoint para crear, listar, actualizar, y eliminar tareas
- Pydantic schemas para request/response
- Tipos compartidos para frontend
- Página con lista de tareas y formulario de creación
- Componente de tarea individual con estado (pendiente/completada)
- Tests para endpoints y componentes
- Documentación API
Adapta esta feature a tu proyecto. Lo importante es que tenga operaciones backend, componentes frontend, y un flujo de datos que pase por tipos compartidos.
El task board: 10 tareas
📋 Task Board: Todo List Feature
| ID | Task | Agent | Depends On | Priority | Status |
|-----|-----------------------------------|------------------|------------|----------|---------|
| T1 | Task Pydantic schemas | backend-agent | none | HIGH | PENDING |
| T2 | Publish shared types | backend-agent | T1 | HIGH | PENDING |
| T3 | CRUD endpoints (/api/tasks) | backend-agent | T1 | HIGH | PENDING |
| T4 | Error handling middleware | backend-agent | T3 | MEDIUM | PENDING |
| T5 | TaskList page layout/skeleton | frontend-agent | none | MEDIUM | PENDING |
| T6 | TaskCard component | frontend-agent | T2 | HIGH | PENDING |
| T7 | CreateTaskForm component | frontend-agent | T2, T3 | HIGH | PENDING |
| T8 | Test backend endpoints | testing-agent | T3, T4 | HIGH | PENDING |
| T9 | Test frontend components | testing-agent | T6, T7 | HIGH | PENDING |
| T10 | Quality review + API docs | docs-review-agent| T8, T9 | MEDIUM | PENDING |
Dependency graph
T1 (schemas) ──→ T2 (types) ──→ T6 (TaskCard)
│ │ │
│ └──→ T7 (CreateTaskForm) ──→ T9 (test frontend)
│ │
└──→ T3 (endpoints) ──→ T4 (error handling) ──→ T8 (test backend)
│
T5 (skeleton) ─────────────────────────────────────────────│
│
T10 (review + docs)
Fases de ejecución
Fase 1 — Foundations (paralelo):
Backend: T1 (schemas)
Frontend: T5 (skeleton — no depende del backend)
Fase 2 — Core Implementation (parcialmente paralelo):
Backend: T2 (types), T3 (endpoints) — secuencial
Frontend: espera T2 para T6
Fase 3 — Advanced Implementation:
Backend: T4 (error handling) — después de T3
Frontend: T6 (TaskCard) + T7 (CreateTaskForm) — después de T2, T3
Fase 4 — Testing (secuencial por agente):
Testing: T8 (test backend) — después de T3, T4
Testing: T9 (test frontend) — después de T6, T7
Fase 5 — Review:
Docs/Review: T10 (quality review + API docs) — después de T8, T9
Lanzando el Equipo
Preparación
Antes de lanzar, verifica que todo está listo:
ls .claude/agents/*.md | wc -l
# Debería ser 5
cat .claude/settings.json | jq '.hooks | keys'
# Debería mostrar PreToolUse, PostToolUse, SubagentStop
cat CLAUDE.md | head -3
# Debería mostrar el título del CLAUDE.md
chmod +x scripts/hooks/*.sh
El prompt de ejecución
Arranca el team lead:
claude --agent team-lead
Una vez dentro, envía el prompt de la feature:
Implementa una feature de gestión de tareas (todo list) con las
siguientes capacidades:
1. Pydantic schemas para Task: id, title, description, status
(pending/completed), created_at, updated_at
2. CRUD endpoints: POST /api/tasks, GET /api/tasks, GET /api/tasks/{id},
PUT /api/tasks/{id}, DELETE /api/tasks/{id}
3. Tipos compartidos publicados en src/types/
4. Error handling middleware con formato estándar
5. Página TaskList que muestra todas las tareas
6. Componente TaskCard que muestra una tarea individual con toggle
de estado
7. Formulario CreateTaskForm para crear nuevas tareas
8. Tests para todos los endpoints (happy path + error cases)
9. Tests para componentes frontend (render + interactions)
10. Quality review del código + documentación API
Genera el task board con 10 tareas, muéstramelo, y cuando yo confirme,
ejecuta el equipo completo.
Observando la Ejecución
Fase 1: Task Board y Aprobación
El team lead debería:
- Leer el codebase (Glob, Read en archivos clave)
- Leer CLAUDE.md para entender convenciones
- Generar un task board similar al diseñado arriba
- Mostrar el dependency graph
- Esperar tu confirmación
Qué revisar antes de aprobar:
- ¿Las dependencias son lógicas? (schemas antes de endpoints, types antes de componentes)
- ¿Cada tarea está asignada al agente correcto?
- ¿Testing tiene dependencias de implementation tasks?
- ¿Docs/review es la última en ejecutar?
- ¿Hay tareas frontend que pueden arrancar en paralelo con backend?
Si todo se ve bien, confirma con "Proceed" o "Ejecuta".
Fase 2: Ejecución Paralela
Observa el flujo:
[Team Lead] Asignando T1 a backend-agent y T5 a frontend-agent (paralelo)
│
├── [Backend Agent] T1: Creando Pydantic schemas...
│ └── Archivos: src/schemas/task.py → TaskCreate, TaskUpdate, TaskResponse
│
└── [Frontend Agent] T5: Creando layout de TaskList...
└── Archivos: src/components/TaskList/index.tsx → skeleton con loading state
Lo que deberías ver:
- Backend y frontend arrancan simultáneamente (T1 + T5)
- El team lead no espera a que termine T5 para asignar T2 (T2 solo depende de T1)
- Cuando T1 termina, T2 y T3 se desbloquean
- El team lead forwardea los schemas de T1 como contexto para T6 y T7
Fase 3: Context Forwarding en Acción
Cuando el backend-agent completa T1 y T2, el team lead debería forwardear contexto al frontend:
[Team Lead → Frontend Agent]
"Task T6: Implement TaskCard component.
Context from backend:
- Types published at: src/types/task.ts
- TaskResponse: { id: string, title: string, description: string,
status: 'pending' | 'completed', created_at: string, updated_at: string }
- GET /api/tasks → returns TaskResponse[]
- PUT /api/tasks/{id} → accepts TaskUpdate { title?: string,
description?: string, status?: string }
Read src/types/task.ts and import types from there.
Do NOT define types inline."
Lo que deberías verificar:
- ¿El team lead incluyó los tipos exactos?
- ¿Incluyó los endpoints relevantes?
- ¿Instruyó al frontend-agent a usar tipos de src/types/?
- ¿El frontend-agent efectivamente lee src/types/ antes de implementar?
Fase 4: Quality Gates en Acción
Mientras los agentes trabajan, los hooks se disparan automáticamente:
PreToolUse — Validación:
[Hook] PreToolUse → Bash command: "python -m pytest" → ALLOWED (exit 0)
[Hook] PreToolUse → Write file: "src/api/routes/tasks.py" → ALLOWED (exit 0)
[Hook] PreToolUse → Bash command: "rm -rf /" → BLOCKED (exit 2)
PostToolUse — Auto-lint:
[Hook] PostToolUse → Write "src/schemas/task.py"
→ Running ruff check... PASS (exit 0)
[Hook] PostToolUse → Edit "src/api/routes/tasks.py"
→ Running ruff check... FAIL (exit 1)
→ "Line 23: unused import 'Optional'"
→ Claude receives error, fixes it
SubagentStop — Logging:
[Hook] SubagentStop → backend-agent completed (12340ms)
→ Logged to logs/agents/agent-activity.log
Fase 5: Testing
Cuando las tareas de implementación terminan, el testing-agent se activa:
[Team Lead] All implementation tasks DONE. Assigning T8 to testing-agent.
[Testing Agent] T8: Testing backend endpoints...
Reading: src/api/routes/tasks.py
Reading: src/schemas/task.py
Creating: tests/test_tasks_api.py
Running: python -m pytest tests/test_tasks_api.py -v
Results:
- test_create_task_success ✅
- test_create_task_missing_title ✅
- test_list_tasks_empty ✅
- test_list_tasks_with_data ✅
- test_get_task_not_found ✅
- test_update_task_success ✅
- test_delete_task_success ✅
Total: 7 passed, 0 failed
Si un test falla:
[Testing Agent] Bug found: PUT /api/tasks/{id} returns 200 instead
of 404 when task doesn't exist.
File: src/api/routes/tasks.py, line 45
Status: PARTIAL — 6/7 tests pass
[Team Lead] Bug detected in T3 (endpoints). Reassigning fix to
backend-agent with context from testing-agent.
[Backend Agent] Fixing: Added existence check before update.
Modified: src/api/routes/tasks.py (line 45)
[Team Lead] Fix applied. Re-running T8.
[Testing Agent] All 7 tests pass.
Fase 6: Review
Finalmente, el docs/review agent analiza todo:
[Team Lead] All tests pass. Assigning T10 to docs-review-agent.
[Docs/Review Agent] Reviewing all files produced by team...
Quality Review:
- src/schemas/task.py — Grade: A (clean Pydantic models, good naming)
- src/api/routes/tasks.py — Grade: B (missing docstring on delete handler)
- src/components/TaskCard/index.tsx — Grade: A (proper types, good states)
- src/components/CreateTaskForm/index.tsx — Grade: B+ (missing aria-label
on submit button)
Issues:
- WARNING: src/api/routes/tasks.py:52 — No docstring on delete_task handler
- SUGGESTION: src/components/CreateTaskForm — Add aria-label="Create task"
Documentation created:
- docs/api/tasks.md — Full API reference for /api/tasks endpoints
Manejando Fallos y Reassignment
Escenario 1: Agente no puede completar la tarea
[Frontend Agent] Task T7: BLOCKED
Reason: "Cannot determine the API endpoint URL. Types are published
but no endpoint URL was provided."
[Team Lead] T7 blocked. Missing context.
Reading T3 output to find endpoint URLs...
Reassigning T7 with additional context:
"POST /api/tasks — Request body: TaskCreate { title, description }
Response: TaskResponse { id, title, ... }"
Lección: Si un agente se bloquea por falta de contexto, el team lead debe forwardear la información faltante. Si sigue fallando después de un retry, escala al usuario.
Escenario 2: Conflicto de tipos
[Testing Agent] Bug: Frontend component expects 'status' as boolean,
but backend publishes 'status' as string enum ('pending' | 'completed').
[Team Lead] Type conflict detected.
Resolution: Backend is source of truth (per CLAUDE.md).
Frontend-agent must update TaskCard to use string enum, not boolean.
Reassigning fix to frontend-agent.
Lección: CLAUDE.md establece que el backend es source of truth para API contracts. El team lead aplica esta regla sin ambigüedad.
Escenario 3: Hook bloquea una operación legítima
[Hook] PreToolUse → BLOCKED: Bash command "rm tests/test_old.py"
Reason: "Destructive command detected"
[Team Lead] Hook blocked a legitimate operation.
User intervention needed: approve removal of obsolete test file.
Lección: Los hooks pueden ser demasiado estrictos. Si un bloqueo es legítimo pero incorrecto, ajusta el hook o aprueba manualmente.
Escenario 4: Agente se queda sin turns
[Backend Agent] Task T3: PARTIAL — Created 3/5 endpoints.
maxTurns (25) reached.
[Team Lead] T3 partially completed. Creating follow-up task:
T3b: "Complete remaining endpoints: PUT and DELETE for /api/tasks"
Agent: backend-agent
Context: T3 output (3 endpoints already created)
Lección: Si un agente se queda sin turns, el team lead crea una tarea de follow-up con el contexto de lo que ya se completó.
El Prompt de Ejecución: Versión Avanzada
Si quieres más control sobre la ejecución, usa un prompt más detallado:
Implementa una feature de gestión de tareas. Aquí está mi task board:
| ID | Task | Agent | Depends On |
|-----|-----------------------------------|------------------|------------|
| T1 | Task Pydantic schemas (TaskCreate, TaskUpdate, TaskResponse) | backend-agent | none |
| T2 | Publish types to src/types/task.ts | backend-agent | T1 |
| T3 | CRUD endpoints POST/GET/PUT/DELETE /api/tasks | backend-agent | T1 |
| T4 | Error handling middleware | backend-agent | T3 |
| T5 | TaskList page skeleton with loading state | frontend-agent | none |
| T6 | TaskCard component (display + status toggle) | frontend-agent | T2 |
| T7 | CreateTaskForm (title + description inputs) | frontend-agent | T2, T3 |
| T8 | Test all 5 endpoints | testing-agent | T3, T4 |
| T9 | Test TaskCard and CreateTaskForm | testing-agent | T6, T7 |
| T10 | Quality review + API docs | docs-review-agent| T8, T9 |
Execution rules:
1. Start T1 + T5 in parallel (no dependencies)
2. When T1 done → start T2, T3 sequentially for backend
3. When T2 done → start T6 for frontend
4. When T2 + T3 done → start T7 for frontend
5. When T3 + T4 done → start T8 for testing
6. When T6 + T7 done → start T9 for testing
7. When T8 + T9 done → start T10 for docs/review
8. Forward ALL type definitions and endpoint URLs between agents
9. If any test fails → report the bug and reassign fix
Execute this task board now.
Esta versión te da control total: defines las tareas, el orden, las dependencias, y las reglas de ejecución. El team lead ejecuta tu plan en lugar de generar el suyo.
Observando en Tiempo Real
Logs de agentes
Mientras el equipo ejecuta, los hooks generan logs en logs/agents/agent-activity.log:
[2026-03-13T14:22:01Z] Agent: backend-agent | Duration: 18230ms | Status: completed
[2026-03-13T14:22:15Z] Agent: frontend-agent | Duration: 8450ms | Status: completed
[2026-03-13T14:23:42Z] Agent: backend-agent | Duration: 22100ms | Status: completed
[2026-03-13T14:24:18Z] Agent: frontend-agent | Duration: 15670ms | Status: completed
[2026-03-13T14:25:33Z] Agent: frontend-agent | Duration: 12340ms | Status: completed
[2026-03-13T14:26:45Z] Agent: testing-agent | Duration: 25890ms | Status: completed
[2026-03-13T14:27:12Z] Agent: testing-agent | Duration: 19450ms | Status: completed
[2026-03-13T14:28:30Z] Agent: docs-review-agent | Duration: 16780ms | Status: completed
Para monitorear en tiempo real en otra terminal:
tail -f logs/agents/agent-activity.log
Verificar archivos creados
Después de la ejecución, verifica qué se creó:
echo "=== Backend ==="
find src/api src/models src/services src/schemas src/types -type f 2>/dev/null
echo "=== Frontend ==="
find src/components src/pages src/hooks -type f 2>/dev/null
echo "=== Tests ==="
find tests -type f -name "*.py" 2>/dev/null
echo "=== Docs ==="
find docs -type f 2>/dev/null
Checklist de Éxito de la Ejecución
✅ Task board generado con 8-10 tareas y dependencias correctas
✅ Dependencias respetadas: backend antes de frontend donde aplica
✅ Al menos una ronda de ejecución paralela (T1 + T5)
✅ Context forwarding: frontend recibió tipos del backend
✅ Tipos de src/types/ usados por frontend (no definidos inline)
✅ Hooks PostToolUse se dispararon (lint después de ediciones)
✅ Hooks PreToolUse bloquearon al menos un comando (o validaron sin bloquear)
✅ SubagentStop logs registrados en agent-activity.log
✅ Testing-agent ejecutó tests y reportó resultados
✅ Docs/review-agent produjo quality review
✅ Team lead no escribió código directamente
✅ Reporte final con todos los resultados consolidados
✅ Si hubo fallos, el team lead los gestionó (retry o escalada)
Ejercicios
Ejercicio 1: Ejecutar con tu propia feature (Medio)
Repite la ejecución completa pero con una feature diferente de tu proyecto real. Diseña el task board de 8-10 tareas, ejecuta con el team lead, y compara los resultados con la ejecución de ejemplo.
Ejercicio 2: Forzar un conflicto (Medio)
Modifica temporalmente el backend-agent para que publique un tipo con un campo llamado is_done (boolean), y el frontend-agent para que espere status (string enum). Ejecuta y observa cómo el team lead (o tú) resuelve el conflicto de tipos.
Ejercicio 3: Pre-defined task board vs auto-generated (Medio)
Ejecuta la misma feature dos veces: una dejando que el team lead genere el task board automáticamente, y otra pasándole el task board predefinido (como en "Versión Avanzada"). Compara: ¿cuál fue más eficiente? ¿Cuál produjo mejor resultado?
Ejercicio 4: Agregar quality gate estricto (Difícil)
Crea un hook PostToolUse adicional que ejecute python -m pytest tests/ -x --tb=short después de cada edición en src/. Si algún test falla, el hook reporta el error (exit 1). Esto significa que cada cambio de código se testea automáticamente. Ejecuta el equipo con este hook y observa el impacto en la ejecución.
Ejercicio 5: Ejecución sin team lead (Difícil)
Ejecuta las 10 tareas manualmente: arranca cada agente por separado (claude --agent backend-agent), pásale una tarea, recoge el output, y forwardéalo al siguiente agente. Compara el esfuerzo con la ejecución vía team lead. ¿Cuánto tiempo ahorró el team lead?
Ejercicio 6: Escalar a 12 tareas (Difícil)
Agrega 2 tareas más al task board: una de caching (backend-agent agrega cache con Redis para GET /api/tasks) y una de performance testing (testing-agent mide tiempos de respuesta). Ajusta las dependencias y ejecuta. ¿El team lead maneja bien la complejidad adicional?
Troubleshooting
"El team lead no genera un task board — empieza a ejecutar directamente"
Causa: El system prompt no es enfático sobre generar y esperar aprobación.
Solución: Refuerza en el team lead:
MANDATORY: ALWAYS generate the task board FIRST and present it.
WAIT for the user to say "Proceed" or "Execute" before delegating.
NEVER start execution without explicit approval.
"Frontend arranca antes de tener los tipos del backend"
Causa: El team lead no verificó dependencias antes de asignar.
Solución: Agrega verificación explícita:
Before assigning ANY task:
1. Read its "Depends On" field
2. For EACH dependency, verify status is DONE
3. If ANY dependency is not DONE → DO NOT assign
4. Log: "T[x] waiting on T[y] (status: [status])"
"Los tests del testing-agent fallan porque el código no existe aún"
Causa: El testing-agent recibió una tarea antes de que la implementación termine.
Solución: Las dependencias del testing-agent deben incluir TODAS las tareas de implementación que testea. En el task board, T8 depende de T3 AND T4, no solo T3.
"El reporte final está incompleto"
Causa: El team lead perdió contexto de las primeras tareas por saturación del context window.
Solución: El team lead debe mantener un running summary (definido en su system prompt):
T1 [DONE] — Schemas created (src/schemas/task.py)
T2 [DONE] — Types published (src/types/task.ts)
...
"La ejecución tarda demasiado (>30 minutos)"
Causa: Demasiadas tareas, agentes con maxTurns altos, o hooks lentos.
Solución:
- Reduce a 6-8 tareas combinando las similares
- Baja maxTurns de agentes de implementación a 20
- Verifica que los hooks terminan en <2 segundos
- Si un agente tarda más de 5 minutos en una tarea, revisa si el prompt es demasiado vago
Anatomy of a Successful Execution
Los 5 momentos clave
Cada ejecución multi-agente tiene 5 momentos que determinan si el resultado será exitoso:
Momento 1: Calidad del task board
El task board define el éxito. Si las dependencias son incorrectas, los agentes se bloquean. Si las tareas son demasiado grandes, los agentes se quedan sin turns. Si son demasiado pequeñas, el overhead de coordinación supera el trabajo real.
Regla: 8-10 tareas para una feature mediana. Cada tarea produce 1-3 archivos. Las dependencias siguen el flujo de datos (schemas → types → endpoints → components → tests → review).
Momento 2: Primera ronda paralela
La primera ronda determina la velocidad del sistema. Si solo un agente puede arrancar (todo depende de algo), el sistema es serial disfrazado de paralelo. Busca siempre tareas frontend que no dependan del backend: layout, skeleton, componentes reutilizables, hooks genéricos.
Regla: al menos 2 agentes deberían estar activos en la primera ronda.
Momento 3: Context forwarding
Cuando el backend termina y el frontend arranca, la calidad del context forwarding determina si el frontend produce algo útil o se bloquea. Los tipos exactos, los endpoint URLs, el formato de error — todo debe forwardearse explícitamente.
Regla: el team lead incluye endpoint URLs, response schemas con todos los campos, y el path exacto de los tipos publicados.
Momento 4: Primer test failure
El testing-agent va a encontrar bugs. Cómo el team lead maneja ese primer fallo — reasignar al agente correcto, forwardear el contexto del bug, re-ejecutar los tests — define la madurez del sistema.
Regla: el team lead identifica al agente responsable (backend o frontend), le pasa el error exacto del test, y le pide un fix específico. Después re-ejecuta los tests.
Momento 5: Reporte final
El reporte final es la evidencia del valor del sistema. Si es completo (archivos, endpoints, componentes, tests, quality score), el sistema demostró su valor. Si es incompleto, el team lead perdió contexto por saturación del context window.
Regla: el team lead mantiene un running summary actualizado después de cada tarea, y lo usa para el reporte final.
Comparación: Ejecución Manual vs Team Lead vs Task Board Predefinido
| Aspecto | Manual (cada agente por separado) | Team Lead auto-genera | Task Board predefinido |
|---|---|---|---|
| Control | Total (tú decides todo) | Bajo (team lead decide) | Alto (tú defines tareas) |
| Esfuerzo | Alto (forward manual) | Bajo (automático) | Medio (diseñas el board) |
| Paralelismo | Manual | Automático | Automático |
| Context forwarding | Tú copias/pegas | Team lead forwardea | Team lead forwardea |
| Error handling | Tú reasignas | Team lead reasigna | Team lead reasigna |
| Mejor para | Debugging, aprendizaje | Ejecuciones rutinarias | Features bien definidas |
Resumen
- El task board tiene 10 tareas con dependencias reales que siguen el flujo: schemas → types → endpoints → components → tests → review
- La ejecución paralela arranca en Fase 1: backend (T1) y frontend (T5) trabajan simultáneamente
- El context forwarding es crítico: el team lead debe forwardear tipos, endpoints, y schemas exactos entre agentes
- Los quality gates (hooks) se disparan automáticamente: PreToolUse valida, PostToolUse lintea, SubagentStop registra
- Si un test falla, el team lead detecta el bug, identifica al agente responsable, y reasigna el fix
- Los logs de agentes (
agent-activity.log) registran la actividad en tiempo real - El team lead puede auto-generar el task board o recibir uno predefinido — ambos funcionan
- La ejecución completa produce: endpoints funcionales, componentes UI, tests pasando, quality review, y documentación API
- Los fallos comunes son: contexto insuficiente, dependencias no respetadas, y hooks demasiado estrictos
Recursos Adicionales
- Create Custom Subagents (Anthropic Docs) — Coordinación entre agentes, task delegation
- Claude Code Hooks — Exit codes, matchers, y eventos de hooks
- Claude Code CLI Reference — Flag
--agent, ejecución de agentes - Claude Code Best Practices — Delegación y coordinación efectiva
- Multi-Agent Orchestration — Patrones de paralelismo y dependency management
- Prompt Engineering: System Prompts — Prompts para coordinación entre agentes
Siguiente cápsula: En la cápsula 04 construirás el script SDK que monitorea el progreso del equipo en tiempo real, configurarás remote control para aprobar operaciones críticas, y generarás un dashboard de ejecución con métricas por agente. La ejecución ya funciona — ahora le agregas observabilidad.