Todos probamos asistentes de código con AI. Al principio impresionan: escribes un comentario y te generan un endpoint completo. Te sentís como Tony Stark. Luego aparece la realidad. A las cinco interacciones, el agente pierde el contexto.
Te importa una librería que no existe. Mezcla la lógica de autenticación con la de base de datos.
Te manda un PR que no compila. Y mientras tanto, quemás tokens como si fueran infinitos. El problema no es la AI.
El problema es que la tratamos como un oráculo, no como un equipo. Le pedimos que haga todo a la vez: entender el requerimiento, diseñar la arquitectura, escribir el código, revisar su propio trabajo y hacer el commit. Eso no es cómo funciona la ingeniería de software. Y tampoco es cómo debería funcionar cuando la AI está en el medio.
La solución un orquestador
En vez de un solo agente que intenta hacer todo, construí un sistema con 8 agentes especializados.
La arquitectura es simple:
1 Orchestrator: el coordinador. No escribe código. No hace reviews. Solo recibe tu pedido, entiende qué se necesita, delega al subagente correcto y trackea el progreso.
7 Subagents: cada uno con un rol acotado y bien definido.
[DIAGRAM: Diagrama mostrando Orchestrator en el centro conectado a los 7 subagentes con etiquetas de sus responsabilidades Los subagentes tienen responsabilidades que no se solapan:
Cada agente sabe exactamente qué le toca y, más importante, qué NO le toca. Esto no es "poner un montón de prompts en un archivo". Es aplicar el mismo principio que usamos en backend: separación de responsabilidades.
No todos los agentes usan el mismo modelo de AI. Y eso es intencional.
Tareas simples: Escribir specs, revisar código, gestionar archivos —usan modelos baratos y rápidos. No necesitás un modelo de 200B de parámetros para revisar si un middleware valida un token.
Tareas complejas implementación de features, resolución de bugs difíciles usan modelos más capaces y más caros. Ahí sí vale la pena invertir. Cada agente tiene permisos granulares definidos en su configuración:
- El developer puede escribir archivos y ejecutar comandos bash.
- El reviewer solo puede leer y comentar. No toca nada.
- El orchestrator solo puede delegar tareas a otros agentes.
Esto es el principio de mínimos privilegios aplicado a agentes de AI. Si un agente no necesita escribir archivos, no debería poder hacerlo. Punto.
El resultado: menos superficie de error, menos alucinaciones, y costos predecibles.
El truco — /grill-me y /caveman (Skills)
Acá es donde la cosa se pone interesante.
/grill-me: la entrevista antes del código Antes de escribir cualquier spec o línea de código, el sistema te entrevista.
No es un "¿qué querés hacer?" y ya. Es una conversación estructurada que recorre cada rama del árbol de decisiones:
> *"¿Qué pasa si el endpoint recibe datos malformados?"*
> *"¿Cómo manejamos autenticación vs autorización?"*
> *"¿Cuál es el alcance exacto de este cambio?"*
> *"¿Hay edge cases que no estamos viendo?"*
El usuario debe confirmar entendimiento compartido antes de que la AI toque un solo archivo. Esto eliminó el problema #1 de los asistentes de código: hacer rápido lo incorrecto.
Porque el mayor desperdicio no es que la AI sea lenta. Es que sea rápida en la dirección equivocada.
/caveman: comunicación comprimida Los tokens cuestan plata. Y el tiempo del dev también. /caveman es un protocolo de comunicación que reduce el uso de tokens ~75%. Elimina artículos, filler y cortesías innecesarias:
> *"Sure, I'd be happy to help you with that! Let me take a look at the authentication middleware and see what might be causing the issue..."*
Se convierte en:
> *"Fix auth middleware. Token expiry uses `<` not `<=`."*
No es ser grosero. Es ser preciso.
Además, hay una regla de las 20 palabras: si un agente necesita más de 20 palabras para explicar un concepto recurrente, ese concepto se comprime en un glosario central (CONTEXT.md). La próxima vez, el agente solo referencia el término. El efecto compuesto es exponencial:
CONTEXT injection → todos los agentes comparten el mismo vocabulario
Regla de 20 palabras → los conceptos repetidos se comprimen
Caveman mode → la comunicación va directo al grano Menos tokens = menos costo = más interacciones útiles antes de que el contexto se sature.
Ambas skill pertenecen a Matt Pocock y aqui su repositorio → GitHub
Tambien pueden encontrar estas skill en Skills.sh
Spec-Driven Development
Meses atrás, cuando el vibe coding estaba en auge, vi bastante claro hacia dónde iba el problema: desarrollar software sin ningún tipo de control, proceso o sistema estaba destinado a fallar tarde o temprano.
Esa idea terminó de confirmarse cuando un cliente me contactó para ayudarle a arreglar el desastre que había generado utilizando este enfoque. Lo más curioso es que, hasta cierto punto, el sistema “funcionaba”, pero era completamente insostenible.
La aplicación no escalaba, no existían medidas reales de seguridad, no había separación de responsabilidades ni estándares mínimos de calidad. Todo el código estaba altamente acoplado, lleno de lógica duplicada y sin buenas prácticas de desarrollo. Honestamente, me sorprendió que la aplicación siguiera funcionando; parecía hacerlo por pura inercia.
Leer, entender y limpiar ese codebase fue un auténtico infierno.
Y ahí es donde entra Spec Driven Development (SDD).
No voy a profundizar demasiado en el tema porque no es el objetivo principal de esta entrada, pero sí considero importante mencionarlo: SDD es un enfoque de desarrollo que busca aportar coherencia, estructura y control al desarrollo de aplicaciones asistidas por AI.
La idea no es únicamente generar código más rápido, sino construir sistemas mantenibles, escalables y entendibles, donde exista trazabilidad entre requerimientos, decisiones técnicas, arquitectura e implementación.
Para más información, recomiendo revisar la documentación oficial de OpenSpec → Aqui
También recomiendo este artículo, que considero especialmente valioso de Hari Krishnan → Spec-Driven Development with OpenSpec - Source of Truth Specification
Ahora mi modificación:
La fase 0 (/grill-me) asegura que el plan es correcto antes de invertir tiempo en escribirlo. Esto no es más burocracia. Es la misma disciplina que usamos en ingeniería de software escribir tests antes del código, diseñar la API antes de implementarla pero aplicada a cómo hablamos con la AI.
La diferencia es que antes esa disciplina vivía en la cabeza del senior. Ahora vive en el sistema., esto se combina con la fase de exploracion de OpenSpec para generar Artefactos mas solidos
MCPs: los plugins del sistema
MCP (Model Context Protocol) es el protocolo que conecta los agentes con servicios externos. Piensalo como los plugins del ecosistema: sin ellos, los agentes operan en el vacío.
Dos MCPs están configurados en este sistema:
Composio: Conecta con Trello para project management. El project-manager puede crear cards, moverlas entre listas y actualizar estados sin salir del terminal. El progreso del sprint queda trackeado automáticamente.
Context7: Documentación técnica actualizada al instante. Cuando el developer implementa un endpoint con Express o define un schema con Prisma, consulta la API más reciente en lugar de confiar en su training data. Esto elimina las alucinaciones de imports y APIs deprecadas.
Esto cierra el loop completo: specs escritas en archivos versionados, implementación con documentación fresca, y tracking automático en Trello. Nada queda en el aire.
Algo importante a tener en cuenta al utilizar el protocolo MCP dentro de arquitecturas basadas en agentes es que las tools registradas por cada MCP se cargan directamente en el contexto del modelo. Esto puede generar conflictos o ejecuciones no deseadas de comandos entre agentes, especialmente en arquitecturas con múltiples responsabilidades y acceso compartido a herramientas.
Para evitar este tipo de problemas, es recomendable restringir qué agentes pueden acceder a determinados MCPs. Esto puede controlarse desde la configuración de opencode.json o directamente desde el system prompt de cada agente, definiendo explícitamente sus capacidades, límites y herramientas disponibles.
Comparto tanto la configuración de la arquitectura en OpenCode como los system prompts de cada uno de los agentes. Toda esta información está en inglés, ya que los modelos suelen ofrecer mejores resultados cuando trabajan en el idioma principal con el que fueron entrenados.
No adjunto archivos como CONTEXT.md ni AGENTS.md / CLAUDE.md. El primero funciona principalmente como un diccionario compartido para estandarizar el lenguaje entre agentes y ayudar a reducir el consumo de tokens ligado a /caveman. El segundo corresponde a archivos de configuración y contexto operativo del sistema.
Configuración de opencode → Aqui
System Prompts de cada unos de los agentes → Aqui
La arquitectura implementa un enfoque híbrido combinando Intent Driven Development y Command Driven Development.
La fase inicial comienza con /grill-me, considerada como la fase 0 del flujo. En esta etapa, el orquestador es responsable de realizar la entrevista, validar requerimientos y consolidar el contexto funcional y técnico del problema esto es Intent Driven.
Una vez los requerimientos son suficientemente sólidos y consistentes, el subagente spec-manager entra en acción para encargarse de la creación de los artefactos de OpenSpec y estructurar formalmente las especificaciones del proyecto y aqui empezamos a hacer Command Driven.
Otros apartados que no mencioné anteriormente, pero que también forman parte importante de esta arquitectura, son los procesos de automatización alrededor del ciclo de integración y gestión operativa del proyecto.
Uno de ellos fue la automatización completa del flujo de integración de código en GitHub mediante slash commands. Todo el ciclo puede ejecutarse desde la terminal: generación de commits, estandarización de mensajes, validaciones y procesos de push, reduciendo fricción operativa y manteniendo consistencia dentro del flujo de trabajo.
Otro enfoque que también terminó formando parte de la arquitectura fue la automatización de gestión en Trello bajo un modelo Command Driven. Esto permitió administrar tarjetas, estados y operaciones del tablero directamente desde la TUI (Terminal User Interface) utilizando slash commands.
La idea detrás de este enfoque no era únicamente automatizar tareas repetitivas, sino convertir la terminal en un centro operativo unificado donde los agentes, comandos y flujos de trabajo convivieran dentro de un mismo ecosistema.
Nota final
Este enfoque aún se encuentra en una etapa de maduración, pero ya cuenta con una base sólida y funcional. A futuro, la idea es incorporar memoria persistente mediante herramientas como Engram, además de continuar refinando la arquitectura hasta convertirla en una solución mucho más robusta y profesional.
Actualmente, gran parte del trabajo está centrado en laboratorios y pruebas experimentales alrededor de skills, MCPs, técnicas de orquestación y distintos enfoques de desarrollo con agentes.
Toda esta base también está respaldada por experiencia práctica acumulada durante aproximadamente 7 años trabajando en desarrollo de software, arquitectura y resolución de problemas reales.
Top comments (0)