6 patrones que uso para diseñar sistemas multi-agente con IA
Llevo meses trabajando con equipos de agentes IA para desarrollar este portfolio y otros proyectos. No hablo de chatbots encadenados ni de demos con LangChain — hablo de sistemas donde 10, 15 o 30 agentes especializados colaboran para implementar una feature completa: desde el diseño hasta el deploy, pasando por revisión arquitectónica, tests E2E y documentación.
El punto de partida fue TLOTP (The Lord of the Prompt), un super-prompt interactivo que llevo construyendo desde hace meses. TLOTP no es un framework ni una librería — es un prompt maestro que se carga en Claude Code y gestiona configuraciones, CI/CD, skills, MCPs y equipos de agentes. La épica Aragorn, en particular, es la que orquesta Agent Teams para trabajo paralelo.
De toda esa experiencia he destilado 6 patrones que considero fundamentales para que un sistema multi-agente funcione de verdad en un entorno de desarrollo real.
1. SDD antes de implementar: ningún código sin diseño aprobado
El primer patrón es el más importante y el más contraintuitivo en la era del vibe coding: no se escribe ni una línea de código sin un SDD (Spec-Driven Development) aprobado.
Un SDD consta de tres documentos:
- requirements.md — Requisitos en formato EARS (Event-driven, Unwanted, Option, Ubiquitous) con prioridades MUST/SHOULD/COULD
- design.md — Arquitectura con diagramas Mermaid, ADRs (Architecture Decision Records), riesgos técnicos y consideraciones de seguridad
- tasks.md — Desglose ejecutable con tamaños, agentes responsables, dependencias y acceptance criteria concretos
El SDD es el contrato entre planificación e implementación. Si un agente siente el impulso de saltárselo porque "es una tarea pequeña" o "ya aprobaron el plan", eso es precisamente la señal de que el SDD es necesario. El plan no es el SDD. La aprobación del enfoque no es la aprobación del diseño.
En la práctica, esto significa que el orquestador tiene una regla de oro grabada a fuego: ninguna implementación ocurre sin SDD aprobado. Jamás. Sin excepción.
2. Patrón reviewer: code-reviewer y architect-reviewer como última línea de defensa
Cada pieza de código que produce un agente pasa por dos revisores obligatorios:
- architect-reviewer — Valida que la solución respeta la arquitectura del proyecto (en mi caso, Hexagonal / Ports & Adapters con Symfony 6.4)
- code-reviewer — Revisión de calidad, seguridad, buenas prácticas y consistencia
Estos dos agentes están siempre presentes. No importa si la tarea es crear un nuevo servicio de dominio o actualizar un fichero JSON — la revisión es obligatoria. Es la última línea de defensa antes de que el código llegue a un commit.
El architect-reviewer participa además en la exploración inicial (validando las opciones propuestas) y en la revisión del design.md del SDD. No es un agente que solo aparece al final — está presente durante todo el ciclo.
3. Debate de pares: dos agentes especialistas discuten desde ángulos distintos
Cuando una decisión técnica tiene múltiples enfoques válidos, el sistema activa un debate de pares. Dos (o tres) agentes especialistas trabajan en paralelo sobre el mismo problema, cada uno desde su especialidad.
El mecanismo funciona en rondas:
- Ronda 1 — Trabajo independiente: cada agente propone su solución sin ver la del otro
- Ronda 2 — Intercambio: cada agente recibe la propuesta del otro y puede corregir, complementar o defender la suya
Los pares se definen por dominio:
- Arquitectura Hexagonal → symfony-specialist vs architect-reviewer
- Implementación backend → symfony-specialist vs php-pro
- Frontend/UI → frontend-developer vs typescript-pro
- Tests E2E → test-automator vs typescript-pro
- CI/CD → devops-engineer vs deployment-engineer
La clave es que el debate genera soluciones mejores que las que cualquier agente individual produciría. La fricción controlada entre perspectivas distintas es un feature, no un bug.
4. Resolución de conflictos con scrum-master: facilita sin decidir
Cuando un debate de pares no alcanza consenso después de dos rondas, entra el scrum-master. Pero su rol es crucial: nunca decide. Solo facilita.
El scrum-master formula preguntas que obligan a los agentes en conflicto a examinar sus propias asunciones. No arbitra, no vota, no elige — crea las condiciones para que los especialistas lleguen al acuerdo por sí mismos.
Esto es importante porque en un sistema multi-agente es tentador tener un "agente jefe" que corte por lo sano cuando hay desacuerdo. Pero eso destruye la diversidad de perspectivas que hace valioso al equipo. El scrum-master preserva esa diversidad mientras guía hacia una resolución.
En la práctica, el protocolo permite un máximo de 2 rondas de facilitación. Si después de eso no hay consenso, la decisión escala al usuario humano — que siempre tiene la última palabra.
5. Transmisión de contexto entre agentes: el orquestador porta y propaga WORKFLOW_CONTEXT
Un error común en sistemas multi-agente es asumir que cada agente tiene contexto completo del proyecto. No lo tiene. Cada agente se lanza con un scope limitado y necesita que le transmitan exactamente lo que necesita saber.
El orquestador mantiene un objeto WORKFLOW_CONTEXT que contiene:
- Configuración de ramas (features desde develop, hotfixes desde master)
- Checks obligatorios del CI (PHPUnit, PHPStan level 9, CS Fixer, ESLint)
- Método de deploy (SSH + git pull en VPS de producción)
- Arquitectura del proyecto (Hexagonal, Symfony 6.4, Doctrine, Playwright POM estricto)
- Entorno Docker (make up, docker compose exec)
Cada vez que el orquestador lanza un subagente, le pasa este contexto completo junto con la tarea específica del SDD, los acceptance criteria y las instrucciones explícitas de qué ficheros tocar y cuáles no.
Esto evita el problema de "el agente de frontend cambió una configuración de Symfony porque no sabía que no debía tocarla" o "el agente de tests usó selectores directos porque no sabía que el proyecto usa POM estricto".
6. Documentación de sesión: dashboard HTML generado en tiempo real
El último patrón es el más infravalorado: un agente documentador que corre en background durante toda la sesión y genera un dashboard HTML con todo lo que ocurrió.
El documentador se lanza al inicio de cada sesión y recibe eventos estructurados cada vez que:
- Se invoca un subagente (quién, para qué, en qué modo)
- Un agente propone algo (qué propuso, qué ficheros tocó)
- Se produce un debate (rondas, discrepancias, resolución)
- El scrum-master facilita (preguntas formuladas, resultado)
- El usuario toma una decisión (qué decidió y por qué)
- Se ejecuta QA (resultado, métricas)
- Se crea un commit o una PR
Al final de la sesión, el documentador genera un HTML con 4 pestañas: Planificación, SDD, Implementación y Resumen. El dashboard incluye la timeline completa de agentes, las comunicaciones entre ellos, los debates con sus rondas, las discrepancias y cómo se resolvieron.
Esto no es solo para auditoría — es esencial para entender qué pasó cuando algo sale mal. Si un bug aparece en producción, puedo abrir el dashboard de la sesión donde se implementó la feature y ver exactamente qué agentes participaron, qué propusieron, qué se debatió y por qué se tomó cada decisión.
Cierre: el sistema que se diseña a sí mismo
Estos 6 patrones no salieron de un paper ni de un tutorial — emergieron de sesiones reales de desarrollo, iteración a iteración. El propio sistema de orquestación que describe este artículo fue diseñado autoasistiéndose con TLOTP.
La épica Aragorn gestiona todo el arsenal de agentes: desde listar y buscar agentes hasta armar Agent Teams para trabajo paralelo. Si quieres ver cómo funciona en la práctica, todo está ahí.
No todos los que deambulan están perdidos — algunos están orquestando agentes.