Reglas, flujo de trabajo y subagentes: Dividir un plugin de agente de IA para dbt
Por qué falló un archivo grande de instrucciones, y cómo AGENTS.md, una habilidad basada en especificaciones, los subagentes aislados, los hooks y Jira MCP asumieron cada uno una tarea en un flujo de trabajo de dbt.
Fuentes: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
Un único archivo de instrucciones no puede contener un manual de reglas, un proceso y el trabajo diario sin descuidar alguno de los tres aspectos. Así se comportaba la primera versión de un flujo de trabajo de dbt agent, y las razones para dividirlo revelan mucho sobre cómo organizar las instrucciones de los agentes de IA.
Un poco de contexto. Un agente de IA al que se le pide que escriba modelos dbt puede entregar código que se compila, pasa todas las pruebas y, aun así, genera números incorrectos. En lugar de confiar en la memoria del agente, el proceso se transformó en siete controles estrictos almacenados dentro del propio repositorio, y esos controles han detectado desde entonces defectos reales que las pruebas por sí solas habrían pasado por alto. Aquí el foco está en la maquinaria que mantiene activos esos controles: reglas, flujo de trabajo, subagentes, ganchos e integración con Jira. El plugin cuenta con tres capas: reglas siempre activas, un flujo de trabajo que el usuario inicia y subagentes aislados para los pasos más complejos, además de ganchos que mantienen consistente la sesión y MCP para acceder desde fuera del repositorio. Ninguna parte duplica la función de otra.
Primero el vocabulario
- Agente. Un sistema de IA que puede abrir archivos, ejecutar comandos y realizar varios pasos de forma independiente, por lo que hace más que responder preguntas.
- Archivo de reglas (
AGENTS.md). Reglas permanentes que el agente carga automáticamente al iniciar una sesión. Es un estándar abierto que funciona en distintas herramientas, sin estar vinculado a un proveedor en particular. Piénselo como un manual de empleados que todos deben conocer ya. - Habilidad (flujo de trabajo). Instrucciones que se cargan únicamente cuando aparece ese tipo específico de tarea, al igual que una receta que se utiliza cuando se pide un plato concreto.
- Subagente. Una copia separada del agente iniciada para una tarea específica en su propio contexto privado, la cual devuelve un resumen al finalizar.
Qué salió mal al principio
El flujo de trabajo más temprano, basado en especificaciones, carecía de la mayoría de estos elementos. Se trataba de un único archivo en formato markdown en la raíz del repositorio que contenía las reglas y el proceso, e intentaba guiar al agente paso a paso. No había subagentes, hooks ni controles estrictos, solo una secuencia sugerida.
Por un tiempo eso funcionó. Sin embargo, cuando una sesión se alargaba, las reglas ubicadas al principio del archivo dejaban de estar en el contexto activo aproximadamente en la tercera etapa de implementación, y el agente comenzaba a improvisar sin decirlo. El descubrimiento, la especificación y la implementación compartían la misma ventana, por lo que las instrucciones más antiguas eran las primeras en ser afectadas.
Los equipos de otros almacenes se encuentran con el mismo problema. Un patrón observado en la práctica, por parte de un equipo más avanzado, consistía en separar las reglas, el flujo de trabajo y la ejecución, y utilizar ganchos de sesión para que la compresión del contexto no eliminara silenciosamente instrucciones a mitad de tarea. La lección aprendida fue dejar de tratar “las instrucciones del agente” como algo único. Existen tres tipos, cada uno con una duración de vida y una función diferentes.
Tres capas, un responsable cada una
- Capa uno: las reglas permanentes:
AGENTS.md, siempre presente - Capa dos, el proceso: la habilidad
spec-driven, iniciada por el usuario - Capa tres, pasos complejos: subagentes, creados cuando es necesario
Reglas
El archivo de reglas contiene las reglas de ingeniería obligatorias que impiden ciertas acciones, junto con un Perfil de Proyecto que registra la configuración de cada equipo: convenciones de nomenclatura, métodos de materialización, la rama base, el sistema CI, etc. Un complemento carga este archivo al inicio de cada sesión, lo que elimina cualquier dependencia de que el agente recuerde buscarlo. Está disponible en el contexto antes del primer mensaje. Dado que el perfil es independiente, otros equipos pueden adoptar el complemento sin necesidad de crear una copia modificada.
Flujo de trabajo
El proceso está codificado como una habilidad que el agente invoca a petición del usuario. Se activa con frases como “arreglar error X” o “crear función Y”, o de forma explícita mediante la orden /dbt-spec-driven:spec-driven en Cortex Code. Dirige la acción según la intención (función, error, refactorización, revisión independiente o documentación independiente) y organiza las fases correspondientes.
Una decisión de diseño es de suma importancia: la habilidad nunca vuelve a exponer las reglas. En su lugar, hace referencia a AGENTS.md. Esa elección resolvió la mayor parte del problema de contexto original, ya que no existen copias duplicadas de las reglas que puedan desincronizarse en dos lugares diferentes.
Subagentes
Cinco tareas consumen tanto contexto que ejecutarlas en el hilo principal impediría realizar el trabajo real: discovery, test-author, output-validator, peer-reviewer y ci-interpreter. Cada una comienza en su propio contexto, realiza una sola tarea y devuelve un informe estructurado con solo lo esencial.
La idea subyacente es que el contexto es un presupuesto limitado y no una superficie ilimitada para trabajar. Tomemos como ejemplo la fase de descubrimiento: puede implicar leer una docena de archivos de modelo y rastrear su origen. Si se realiza en el hilo principal, eso significa que la mitad del presupuesto se gasta antes incluso de comenzar la implementación, en archivos que para entonces nadie necesita. La fase de descubrimiento también es adecuada para modelos pequeños y económicos, ya que leer y resumirlos requiere menos capacidad de razonamiento.
Gancho
El archivo hooks/hooks.json activa tres ganchos sin requerir cooperación de ningún agente. Uno carga AGENTS.md al inicio de la sesión. Otro emite una advertencia antes de la compresión del contexto, para que nada importante desaparezca en silencio, lo cual era exactamente el fallo de la primera versión. El tercero agrega una nota de la sesión al finalizarla.
Cada gancho se proporciona en variantes tanto para bash como para PowerShell. Cortex ejecuta la versión que corresponda al sistema operativo, mientras que la otra falla en silencio. Un equipo que utiliza sistemas operativos diferentes no necesita configuración por usuario.
Conexión de MCP con Jira
Todo esto deja de funcionar si “publicar la especificación en el ticket” implica que alguien copie manualmente texto entre una terminal y Jira. Dos servidores MCP conectan el flujo de trabajo.
El Atlassian MCP es indispensable. El subagente discovery lo utiliza para leer el ticket al iniciarse una sesión, y la fase de especificación lo emplea para publicar los requisitos numerados en dicho ticket. Por lo tanto, la especificación queda junto al trabajo, y no en un historial de chat que desaparece.
El Notion MCP desempeña un papel más limitado por el momento. Se utiliza cuando algo merece ser documentado en un lugar más duradero que la descripción de una PR o el repositorio, como por ejemplo un flujo de trabajo completo. En general, MCP es lo que permite que las reglas, los flujos de trabajo y los subagentes interactúen con cualquier elemento fuera del repositorio. Hoy eso puede ser un ticket, y mañana podría ser una plataforma de BI o un canal de Teams.
La imagen general
El usuario pregunta, las rutas de habilidades y los trabajadores se desvían hacia un lado. Cada trabajador devuelve un informe y no descarga sus archivos en el hilo principal. Los ganchos y MCP envuelven la imagen sin quedar dentro de ella: cargan las reglas, emiten una advertencia antes de la compactación y llegan a Jira.
Qué mejoró
- El hilo principal se mantiene enfocado en las decisiones y no se ve sobrecargado por la salida de descubrimiento de una docena de archivos.
- Las reglas dejan de desviarse, ya que existe exactamente una copia.
- La compactación durante la sesión no puede perder nada sin una advertencia previa.
La lección general trasciende ampliamente a dbt. Cualquiera que ejecute un agente de IA contra un repositorio real probablemente tenga una versión de “un solo archivo que hace todo”, y tiende a fallar de la misma manera: cuanto más larga sea la sesión, más se van desplazando las instrucciones iniciales.