Módulo 8: Proyecto — Sistema Multi-Agente Completo
1. Introducción y Arquitectura — Sistema Multi-Agente Completo
1. Introducción y Arquitectura — Sistema Multi-Agente Completo
Descripción
Este es el módulo final. No es un módulo más — es la integración de todo lo que construiste en los 7 módulos anteriores. Custom subagents, memory scopes, delegación paralela, Agent Teams, plugins, hooks, SDK headless, remote control, CLAUDE.md. Cada pieza que aprendiste existe para llegar a este punto: un sistema multi-agente funcional donde 5 agentes trabajan coordinados en un proyecto real.
No vas a aprender conceptos nuevos. Vas a combinar conceptos que ya dominas en un sistema que es mayor que la suma de sus partes. El team lead coordina. El frontend-agent y el backend-agent implementan en paralelo. El testing-agent valida cada entrega. El docs-agent revisa calidad y documenta. Los hooks actúan como quality gates automáticos. El SDK monitorea el progreso. Remote control aprueba operaciones críticas. CLAUDE.md establece las reglas del juego. Y todo funciona sin que estés pegado a la terminal.
Este módulo tiene un objetivo claro: que termines con un sistema que puedas adaptar a tus proyectos reales. No es un ejercicio académico — es una plantilla profesional de orquestación multi-agente.
¿Dónde Estamos en la Guía?
Contexto en la Guía
Esta guía tiene 8 módulos organizados en 3 phases:
Phase 1: Subagents Avanzados (Módulos 1-3) ← COMPLETADA
├── Módulo 1: Custom Subagents ✅
├── Módulo 2: Agent Memory y Scopes ✅
└── Módulo 3: Parallel Sub-Agent Delegation ✅
Phase 2: Agent Teams y Plugins (Módulos 4-6) ← COMPLETADA
├── Módulo 4: Agent Teams ✅
├── Módulo 5: Plugins: Crear y Distribuir ✅
└── Módulo 6: Hooks Avanzados y SDK Headless ✅
Phase 3: Orquestación (Módulos 7-8)
├── Módulo 7: Remote Control y CLAUDE.md para Equipos ✅
└── Módulo 8: Proyecto: Sistema Multi-Agente Completo ← ESTÁS AQUÍ
Duración total estimada: 8-10 horas (self-paced).
El cierre del arco
Cada módulo te dio una pieza. Ahora ves el rompecabezas completo:
| Módulo | Pieza | Rol en el Sistema Final |
|---|---|---|
| M1: Custom Subagents | Identidad de cada agente | Cada agente tiene rol, restricciones, herramientas específicas |
| M2: Agent Memory | Conocimiento compartido | Los agentes comparten contexto del proyecto via memory scopes |
| M3: Parallel Delegation | Trabajo simultáneo | Frontend y backend trabajan en paralelo |
| M4: Agent Teams | Coordinación formal | Team lead gestiona task board, dependencias, conflictos |
| M5: Plugins | Empaquetado | La configuración de los 5 agentes se empaqueta como plugin |
| M6: Hooks + SDK | Automatización | Hooks validan cada entrega, SDK monitorea progreso |
| M7: Remote Control + CLAUDE.md | Gobernanza | CLAUDE.md como constitución, remote control para aprobaciones |
La Arquitectura del Sistema
Vista general
┌─────────────────────────────────────────────────────────────┐
│ CLAUDE.md (M7) │
│ Constitución del equipo │
│ Convenciones · Boundaries · Quality standards │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TEAM LEAD (M4) │ │
│ │ Coordina · Asigna · Resuelve · Reporta │ │
│ │ Tools: Agent(frontend), Agent(backend), │ │
│ │ Agent(testing), Agent(docs-review) │ │
│ └───────┬──────────┬──────────┬──────────┬─────────────┘ │
│ │ │ │ │ │
│ ┌─────▼────┐ ┌───▼────┐ ┌──▼───┐ ┌───▼──────┐ │
│ │ FRONTEND │ │BACKEND │ │TESTS │ │DOCS/ │ │
│ │ AGENT │ │ AGENT │ │AGENT │ │REVIEW │ │
│ │ (M1) │ │ (M1) │ │(M1) │ │AGENT(M1) │ │
│ │ │ │ │ │ │ │ │ │
│ │ UI/UX │ │API/DB │ │pytest│ │Quality │ │
│ │ React │ │FastAPI │ │Cover.│ │Docs │ │
│ └──────────┘ └────────┘ └──────┘ └──────────┘ │
│ │ │ │ │ │
│ ┌─────▼──────────▼──────────▼──────────▼─────────────┐ │
│ │ MEMORY SCOPES (M2) │ │
│ │ Project memory: shared context, decisions, types │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PARALLEL DELEGATION (M3) │ │
│ │ Frontend + Backend simultáneo │ │
│ │ Testing espera a ambos │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌───────────────┐ │
│ │ HOOKS (M6) │ │ SDK (M6) │ │ REMOTE (M7) │ │
│ │ Quality gates │ │ Monitoring │ │ Approvals │ │
│ │ PreToolUse │ │ Python script │ │ Mobile ops │ │
│ │ PostToolUse │ │ Status polling │ │ Critical ops │ │
│ │ SubagentStop │ │ Reports │ │ │ │
│ └────────────────┘ └────────────────┘ └───────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ PLUGIN (M5) │
│ Todo empaquetado: agents + hooks + CLAUDE.md + skills │
└─────────────────────────────────────────────────────────────┘
Los 5 agentes
1. Team Lead — El coordinador
- No escribe código. Nunca.
- Analiza el codebase, genera el task board, asigna tareas
- Gestiona dependencias: quién espera a quién
- Forwardea contexto entre teammates
- Resuelve conflictos cuando dos agentes producen resultados contradictorios
- Produce el reporte final consolidado
2. Frontend Agent — El especialista UI
- Implementa componentes React, páginas, hooks, estilos
- Territorio:
src/components/,src/pages/,src/hooks/,src/styles/ - Consume tipos publicados por el backend en
src/types/ - Produce componentes con loading, error, y empty states
3. Backend Agent — El especialista API
- Implementa endpoints FastAPI, Pydantic schemas, business logic
- Territorio:
src/api/,src/models/,src/services/ - Publica tipos compartidos en
src/types/para que el frontend los consuma - Produce endpoints con validación, error handling, y schemas documentados
4. Testing Agent — El validador
- Escribe y ejecuta tests para el código producido por frontend y backend
- Territorio:
tests/ - Lee código fuente pero nunca lo modifica
- Reporta coverage, tests fallidos, y regresiones
- Se activa después de que frontend y backend completan
5. Docs/Review Agent — El guardián de calidad
- Revisa el código de todos los agentes (read-only)
- Actualiza documentación del proyecto
- Territorio para escritura:
docs/ - Lee todo, modifica solo documentación
- Produce reportes de calidad: naming, patterns, consistency
Flujo de ejecución
1. INICIO
Team lead recibe feature request
Lee codebase (Glob, Read, Grep)
Genera task board con 8-10 tareas
Presenta para aprobación
2. EJECUCIÓN PARALELA (Round 1)
Backend agent → schemas, tipos compartidos
Frontend agent → layout, skeleton components (no dependen del backend)
3. EJECUCIÓN PARALELA (Round 2)
Backend agent → endpoints API
Frontend agent → componentes con datos (dependen de tipos del backend)
4. TESTING
Testing agent espera a que frontend + backend completen
Ejecuta tests
Reporta coverage y fallos
Si hay fallos → team lead reasigna fix al agente correspondiente
5. REVIEW
Docs/Review agent revisa todo el código producido
Genera reporte de calidad
Actualiza documentación
6. QUALITY GATES (hooks automáticos)
PostToolUse → lint automático después de cada edición
SubagentStop → log de cada agente que termina
PreToolUse → bloqueo de operaciones peligrosas
7. MONITORING (SDK)
Script Python monitorea el progreso
Genera reporte de ejecución
8. REPORTE FINAL
Team lead consolida resultados de todos los agentes
Produce reporte con archivos, endpoints, componentes, tests, quality score
Qué Vas a Construir en Este Módulo
Cápsula por cápsula
| # | Cápsula | Qué construyes |
|---|---|---|
| 01 | Introducción y Arquitectura (esta) | Modelo mental, arquitectura, plan de ejecución |
| 02 | Configuración del Team | 5 agent files, plugin, hooks, CLAUDE.md |
| 03 | Ejecución y Task Board | Task board, ejecución paralela, quality gates |
| 04 | Monitoring y Remote Control | SDK monitor, remote approvals, dashboarding |
| 05 | Retrospectiva y Optimización | Análisis, optimización, resumen de la guía |
Entregables finales
Al terminar las 5 cápsulas tendrás:
your-project/
├── .claude/
│ ├── agents/
│ │ ├── team-lead.md ← Coordinador (M4)
│ │ ├── frontend-agent.md ← Especialista UI (M1)
│ │ ├── backend-agent.md ← Especialista API (M1)
│ │ ├── testing-agent.md ← Validador (M1)
│ │ └── docs-review-agent.md ← Guardián de calidad (M1)
│ └── settings.json ← Hooks configurados (M6)
├── scripts/
│ ├── hooks/
│ │ ├── post-edit-lint.sh ← Auto-lint hook (M6)
│ │ ├── pre-tool-validate.sh ← Validation hook (M6)
│ │ └── subagent-stop-log.sh ← Logging hook (M6)
│ └── monitor/
│ └── team-monitor.py ← SDK monitoring (M6)
├── multi-agent-plugin/
│ ├── package.json ← Plugin manifest (M5)
│ ├── agents/ ← Agent files empaquetados
│ └── skills/ ← Skills del equipo
├── CLAUDE.md ← Constitución del equipo (M7)
├── docs/
│ └── execution-report.md ← Reporte generado por docs-agent
└── src/
├── components/ ← Frontend territory
├── api/ ← Backend territory
├── types/ ← Shared (published by backend)
└── tests/ ← Testing territory
Por Qué Este Sistema No Es un Ejercicio Académico
Patrones reales de producción
El sistema que construyes aquí implementa patrones que existen en equipos de desarrollo reales:
1. Separación de responsabilidades Cada agente tiene un territorio definido. No hay solapamiento. Es el mismo principio que los microservicios, pero aplicado a agentes.
2. Coordinación por task board El team lead no ejecuta — coordina. Es el patrón de un tech lead real: distribuye trabajo, gestiona dependencias, resuelve bloqueadores.
3. Quality gates automáticos Los hooks son el equivalente a CI checks: cada cambio se valida automáticamente antes de aceptarse.
4. Observabilidad El SDK monitor es el equivalente a Datadog o Grafana para tu sistema de agentes: sabes qué está pasando, cuánto tarda, y dónde hay problemas.
5. Gobernanza CLAUDE.md es el equivalente a un coding standards document + architecture decisions record. Remote control es el equivalente a approval gates en un pipeline de producción.
Adaptación a tu proyecto
Cuando termines este módulo, podrás:
- Cambiar los agentes — Reemplaza frontend/backend por data-engineer/ml-engineer, o por mobile/web, o por cualquier especialización que tu proyecto necesite
- Escalar el equipo — Agrega un 6to agente (security-agent, performance-agent, i18n-agent) sin cambiar la arquitectura
- Cambiar el stack — Los agent files son agnósticos al framework. Cambia React por Vue, FastAPI por Django, pytest por jest — la estructura es la misma
- Empaquetar y distribuir — El plugin que creas aquí se puede publicar en npm para que tu equipo use la misma configuración
Prerequisitos
Lo que necesitas tener listo
- ✅ Módulos 1-7 completados — Todo el contenido de esta guía
- ✅ Un proyecto con frontend + backend — React + FastAPI ideal, pero cualquier combo sirve
- ✅ Claude Code actualizado — Versión reciente con soporte de subagents
- ✅ Python 3.10+ — Para el script de monitoring
- ✅ Node.js 18+ — Para el plugin
- ✅ Git inicializado — El proyecto debe estar bajo control de versiones
Verificación rápida
claude --version
python3 --version
node --version
git status
ls src/No necesitas
- ❌ Experiencia con sistemas multi-agente — Este módulo te guía paso a paso
- ❌ Un proyecto grande — Con 5-10 archivos de código es suficiente
- ❌ Infraestructura de producción — Todo corre local
Nota sobre Features Experimentales
⚠️ FEATURE EXPERIMENTAL
Agent Teams es una feature experimental de Claude Code. Si no está disponible en tu versión, cada cápsula incluye una alternativa manual usando un subagent coordinador. Los teammates funcionan como subagents estándar en ambos casos. Los hooks y el SDK headless son features estables.
Última verificación: Marzo 2026
Modelo Mental: De Piezas Aisladas a Sistema Integrado
Antes de este módulo
Tienes 7 herramientas que sabes usar individualmente:
Subagent ──→ Lo usas cuando necesitas delegar una tarea
Memory ────→ Lo usas cuando necesitas recordar algo entre sesiones
Parallel ──→ Lo usas cuando quieres que dos cosas pasen a la vez
Teams ─────→ Lo usas cuando quieres coordinación formal
Plugin ────→ Lo usas cuando quieres empaquetar configuraciones
Hooks ─────→ Lo usas cuando quieres automatizar validaciones
SDK ───────→ Lo usas cuando quieres ejecutar Claude desde scripts
Remote ────→ Lo usas cuando quieres aprobar cosas desde el celular
CLAUDE.md ─→ Lo usas cuando quieres establecer estándares
Después de este módulo
Tienes un sistema donde todas las piezas trabajan juntas:
CLAUDE.md establece las reglas
→ Que el plugin empaqueta
→ Que los subagents siguen
→ Coordinados por el team lead
→ Que delega en paralelo
→ Y hooks validan cada paso
→ Mientras el SDK monitorea
→ Y remote control aprueba lo crítico
→ Todo conectado por memory scopes
La diferencia entre "sé usar 7 herramientas" y "tengo un sistema de 7 herramientas integradas" es la diferencia entre un músico que sabe tocar notas y uno que sabe tocar una canción.
Flujo de Aprendizaje del Módulo
Progresión
-
Configuración (Cápsula 02) — Creas los 5 agent files, el plugin que los empaqueta, los hooks que validan, y el CLAUDE.md que gobierna. Al terminar, todo está configurado pero sin ejecutar.
-
Ejecución (Cápsula 03) — Diseñas el task board, lanzas al equipo, observas la ejecución paralela, y ves los quality gates en acción. Al terminar, el equipo ha producido código funcional.
-
Monitoring (Cápsula 04) — Construyes el script SDK que monitorea el progreso, configuras remote control para aprobaciones, y generas un dashboard de ejecución. Al terminar, tienes observabilidad del sistema.
-
Retrospectiva (Cápsula 05) — Analizas qué funcionó, qué no, dónde hubo conflictos, y cómo optimizar. Incluye el resumen completo de la guía y la conexión con las guías #10 y #11.
La progresión es: configurar → ejecutar → observar → analizar.
Duración estimada del módulo: 1.5-2 horas.
Conexión con el Path
En la guía
Este es el último módulo de la Guía #9 (Advanced Claude Code Workflows). Cierra el arco que empezó con "cómo creo un subagent personalizado" y termina con "tengo un sistema multi-agente completo."
En el path
La Guía #9 es parte del Claude Code Agentic Development Path:
Guía #8: Intermediate Workflows (prerequisito)
Guía #9: Advanced Claude Code Workflows ← ESTA GUÍA
Guía #10: Claude Code in CI/CD Pipelines (siguiente)
Guía #11: Security Deep Dive
Lo que construyes aquí se conecta directamente con:
- Guía #10 (CI/CD) — El SDK monitor se integra en GitHub Actions. Los hooks se convierten en CI checks. El plugin se publica en npm real
- Guía #11 (Security) — Los PreToolUse hooks se extienden con validaciones de seguridad. CLAUDE.md incluye políticas de seguridad. Los boundaries de agentes se auditan
Resumen
- Este módulo integra todos los conceptos de los Módulos 1-7 en un sistema multi-agente funcional
- La arquitectura tiene 5 agentes: team lead (coordinador), frontend-agent, backend-agent, testing-agent, y docs/review-agent
- Cada módulo previo aporta una pieza: subagents (M1) como base, memory (M2) para contexto compartido, parallel (M3) para trabajo simultáneo, teams (M4) para coordinación, plugins (M5) para empaquetado, hooks+SDK (M6) para automatización y monitoring, remote+CLAUDE.md (M7) para gobernanza
- El flujo de ejecución es: task board → ejecución paralela → testing → review → quality gates → monitoring → reporte
- No es un ejercicio académico — es una plantilla profesional adaptable a proyectos reales
- El módulo progresa: configurar → ejecutar → observar → analizar
- El sistema implementa patrones de producción: separación de responsabilidades, coordinación por task board, quality gates automáticos, observabilidad, y gobernanza
- Duración estimada: 1.5-2 horas
- Conecta con la Guía #10 (CI/CD Pipelines) y la Guía #11 (Security Deep Dive)
Recursos Adicionales
- Create Custom Subagents (Anthropic Docs) — Documentación oficial de agent files y frontmatter
- Claude Code Hooks — Hooks SessionStart, PreToolUse, PostToolUse, SubagentStop
- Claude Code CLI Reference — Flag
-p,--output-format,--agent - Claude Code Settings — Configuración de hooks en settings.json
- Claude Code Best Practices — Buenas prácticas de delegación y automatización
- Multi-Agent Orchestration (Anthropic) — Patrones de orquestación multi-agente
- Claude Code Overview — Contexto general de Claude Code como plataforma
- Prompt Engineering: System Prompts — Técnicas de system prompts para agentes especializados
Siguiente cápsula: En la cápsula 02 crearás los 5 agent files completos con sus system prompts especializados, el plugin que los empaqueta, los hooks de quality gates, y el CLAUDE.md que gobierna al equipo. Al terminar, tendrás todo configurado y listo para ejecutar.