Tres roles, no doce: el sistema de agentes que me quedó

Delegarle una tarea a un agente es fácil. Delegarle trabajo a varios, sobre el mismo repositorio, y que lo que vuelve sirva sin tener que rehacerlo, es otro problema. Vengo armando y desarmando sistemas para eso desde hace bastante: hubo una versión con organigrama de empresa —jefes de área, especialistas, un agente dedicado a crear agentes— y hubo otras mucho más chicas. Lo que quedó en pie es bastante más chico que lo que empecé construyendo, y funciona mejor.

Un sistema de agentes no mejora por tener más agentes, sino por dejar claro quién decide, quién ejecuta y qué ve cada uno.

Una aclaración antes de arrancar: esto no va en orden. Trabajé varios proyectos en paralelo y no me acuerdo de la secuencia real, así que lo que sigue son etapas conceptuales, no un diario. Y el foco está en el sistema de hoy; las versiones anteriores aparecen porque explican por qué el de hoy tiene la forma que tiene.

El problema real de delegar

Casi nunca falló porque el agente no supiera hacer la tarea. Falló porque no sabía hasta dónde llegaba su autoridad.

Quién define el alcance. Quién decide que algo está terminado. Quién puede mergear y quién no. Quién tiene que enterarse de lo que pasó. Un agente muy capaz al que le delegás mal no te devuelve un error: te devuelve trabajo que parece terminado y no lo está, que es bastante peor, porque el error visible lo descartás en un minuto y el trabajo plausible te lo llevás puesto hasta que lo tocás.

Por eso mi problema dejó de ser cómo escribir mejores instrucciones y pasó a ser cómo repartir responsabilidad. No es lo mismo. La instrucción explica la tarea; el reparto explica qué pasa cuando la tarea sale distinta a lo que esperabas.

El organigrama que no escaló

La versión más ambiciosa que armé fue, literalmente, una empresa. Había un orquestador con el que yo charlaba, y debajo suyo una cadena: un agente dueño del contrato de la API, un jefe de área de frontend, un jefe de área de backend y, colgando de ellos, especialistas por tipo de trabajo: diseño de esquema, construcción de componentes, de rutas, de páginas, de mocks de API. El orquestador trabajaba por fases y siempre empezaba por el contrato de la API, porque ambos jefes dependían de él para poder arrancar en paralelo sin pisarse.

Arriba de todo eso había un meta-agente, el único autorizado a tocar los archivos de los demás agentes. Lo que no podía tocar era al orquestador: solo el orquestador se modifica a sí mismo. También clasificaba a los agentes en permanentes y temporales, y validaba que un agente nuevo no se superpusiera con uno que ya existía. Ese detalle dice bastante: ya en la versión más grande el problema que había que vigilar era la duplicación de roles.

El principio que compartían todos está anotado tal cual en mi memoria de trabajo de ese proyecto: “define QUÉ, no CÓMO”. No era mal principio. Y hubo una versión todavía más pesada, en otro e-commerce, donde el sistema declaraba paquetes de contexto, una pila de skills y workflows, y ya no solo roles técnicos: estratega de SEO, cumplimiento legal, crítico de diseño, auditor entre tracks, renderizador de wireframes.

Murió por una razón sola, y no es que estuviera mal hecho: servía a proyectos grandes con estructura pesada. Aplicado a un proyecto chico, preparar costaba más que ejecutar. Armar el organigrama, mantenerlo coherente y alimentarlo con contexto era más trabajo que hacer la tarea a mano. Hubo también una etapa anterior a todo esto, organizada alrededor de qué modelo hacía qué; de esa no queda rastro en disco y no la voy a reconstruir de memoria.

Tres roles y por qué tres

Lo que sobrevivió tiene tres roles: el que coordina, el que investiga y el que implementa.

El que coordina es el orquestador, y es con el que hablo yo. Su definición la tengo anotada desde la versión en la que el sistema empezó a estabilizarse, en la voz del propio orquestador, y la cito porque el final de la frase es el que importa: “actúo como ORQUESTADOR: escribo prompts, despacho agentes, y VERIFICO sus entregables de forma independiente (no confío en la palabra del agente, corro los gates yo)”. Un agente que te dice que terminó no es evidencia de que terminó.

Y acá está el detalle que hace que tres alcancen, que es el que casi nunca se cuenta cuando alguien muestra su sistema de agentes: cada rol tiene un gate distinto. Un gate es la condición bajo la cual el trabajo se acepta, no la tarea que hace el agente.

• Investigación responde por sus fuentes. Tiene contrato de fuentes: prohibido inventar URLs, hay que marcar qué está vigente y qué es legacy, y una decisión grande no se apoya en una sola fuente. Su entregable es un documento.
• Implementación responde por el repo. Su gate es git más una definición de terminado que se verifica corriendo algo: no “lo probé”, sino un comando que sale bien o sale mal. Su entregable es un PR.
• El orquestador no tiene gate propio: es el gate. No entrega código; entrega la verificación de lo que entregaron los otros.

Cuando lo pienso así, la pregunta “¿cuántos agentes necesito?” cambia de forma. Dos agentes que responden al mismo gate no son roles distintos: son el mismo rol con dos nombres. El organigrama tenía doce nombres para lo que, al nivel de a quién le pedís cuentas, era un puñado de respuestas. Los especialistas de componentes, de rutas y de páginas tenían tareas distintas y el mismo criterio de aceptación. Eso no es organización: es la misma responsabilidad repartida en más archivos que hay que mantener sincronizados.

Los prompts salen todos de una guía maestra con un núcleo común y variantes según el tipo de trabajo: investigación, feature, arreglo, documentación. El núcleo es lo que no cambia nunca; el track es lo poco que cambia. Que la diferencia entre un prompt y otro sea chica y explícita es justamente lo que evita que aparezca un rol nuevo cada vez que aparece una tarea nueva.

Hay una aclaración sobre el reparto que es tan importante como los roles: el investigador no siempre se usa. Si la respuesta ya está en el repo, mandar una ronda de investigación es un viaje de ida y vuelta que no agrega nada más que contexto. El sistema no obliga a usar todos sus roles; tener tres disponibles no significa despachar tres.

Un último detalle del reparto que me parece más importante de lo que aparenta: los entregables se versionan, los prompts no. Los documentos de investigación viven en el repo; los prompts que los produjeron están excluidos por .gitignore, salvo la guía base. El prompt es el andamio y el entregable es lo que quedó construido. Guardar el andamio de cada tarea terminada no ayuda a nadie a leer el proyecto meses después.

El que coordina no dispara

Hay una regla que a primera vista parece una limitación tonta y es de las que más me evitó problemas: el orquestador deja el prompt cerrado, pero no lo lanza.

Escribe el prompt entero, lo deja listo, y lo abro yo en otra terminal. Tengo esa decisión anotada tal cual en su momento —el prompt de implementación quedaba listo y anotado como no despachado, porque lo lanzaba yo—, y hoy sigue siendo así. Lo que compra esa fricción es una persona parada entre “el plan está escrito” y “el trabajo empezó”. Es el único punto del sistema donde alguien puede leer el encargo completo antes de que se convierta en commits, y leerlo cuesta menos que revertirlo.

La otra mitad de la asimetría es la que de verdad importa: el orquestador puede lanzar agentes especializados; un agente delegado nunca lanza a otro. Si un agente delegado cree que hay que delegar, pide autorización y frena.

Esa regla tiene un origen concreto, anotado el día que la escribí: pasó que un agente delegado lanzó subagentes con su mismo prompt, recursivamente. No tengo registrado qué se rompió exactamente, así que no lo voy a adornar; alcanza con el mecanismo. Un prompt que contiene la instrucción de delegar y que se delega a sí mismo no tiene ninguna razón interna para detenerse. La regla no está para que el sistema sea más prolijo: está para que tenga fondo.

Qué ve y qué no ve el que coordina

Este es el cambio que más rindió de todos, y es el menos vistoso, porque no agrega ninguna pieza: solo cambia quién ve qué.

Lo que ve un agente delegado es su prompt, y nada más. La carpeta donde vive el sistema está gitignoreada, así que los agentes literalmente no la ven. Eso suena a defecto y es una restricción útil: obliga a que todo lo necesario viaje adentro del prompt. Un prompt que dice “como hablamos antes” está roto, porque el agente no estuvo en esa conversación. Cuando el prompt tiene que bastarse solo, los huecos del encargo aparecen mientras lo escribís, no a mitad de la tarea.

Lo que ve el orquestador es el resumen, no la transcripción. Antes releía todo lo que había hecho cada agente para saber en qué estado estaba el trabajo, que es exactamente la forma de comerse de un lado lo que ahorrás del otro. Hoy todo prompt termina con un cierre obligatorio: el agente guarda un resumen en memoria antes de abrir el PR, y su último mensaje dice qué commits hizo, qué número de PR abrió y que no mergeó nada. El orquestador lee eso y los archivos entregados —que verifica él, no de palabra— y con eso alcanza.

Y los agentes no se ven entre sí: el canal es la memoria. El ejemplo más claro de este proyecto es la página del catálogo de componentes. Los agentes de implementación no la escriben: dejan una ficha del componente en memoria, con un formato fijo, y siguen con lo suyo. Después un único agente lee todas esas fichas y escribe la página. Eso resuelve dos cosas a la vez: el criterio con el que se documenta pasa a ser uno solo en vez de uno por agente, y un archivo que iba camino a ser un imán de conflictos de merge deja de ser tocado por más de una rama a la vez.

Ahí es donde la memoria deja de ser una comodidad y pasa a ser una pieza estructural. No está para que el sistema sea más cómodo de usar; está para que dos agentes que nunca se hablan puedan trabajar sobre lo mismo, y para que el que coordina pueda saber en qué estado está todo sin releer nada.

Así se ve el sistema en este proyecto, que es la forma más corta de mostrar el reparto:

_continuar.md      # el estado: dónde quedó todo entre una sesión y la siguiente
cicatrices.md      # los errores ya cometidos, para no volver a cometerlos
_prompts-guia.md   # la plantilla: cómo se arma un encargo delegable
prompts/           # encargos de una tarea, los lanzo yo en otra terminal
agents/            # agentes reutilizables, los lanza el orquestador

El costo de todo esto lo pago en un solo lugar y conviene decirlo acá: el orquestador sigue siendo, de lejos, el agente que más contexto consume, incluso después de haberlo reducido bastante. Es el único que tiene que sostener el estado completo. Repartir el trabajo no reparte esa carga: la concentra.

Las reglas salieron de errores

Ninguna de las reglas duras del sistema salió de una buena idea. Todas salieron de algo que pasó.

El registro con el que arrancó la versión actual no está titulado por lo que construye, sino por lo que evita: es el sistema de orquestación creado “para que no se repitan los problemas”, y los problemas están enumerados ahí mismo —un agente que termina sin dejar resumen, scope creep, recursión de subagentes—. Es una lista de errores, no una arquitectura. Lo que fijó ese día sigue vigente casi sin cambios: la rama estable no la mergea nadie —solo llega ahí un PR desde integración, y ese merge lo autoriza una persona, caso por caso—; la rama de integración la mergean únicamente orquestadores, siempre vía PR; los agentes normales abren PR desde su rama y guardan su resumen antes de abrirlo; y los commits van sin autorreferencia de IA.

Lo que vinieron a resolver esas reglas fue bien concreto: agentes que no aplicaban buenas prácticas de commit, agentes que hacían el trabajo y no abrían el PR, y más de un implementador mergeando cuando no le correspondía. De ahí también salió el archivo de cicatrices, que es lo que su nombre dice: los gotchas de construcción de este proyecto, las cosas que ya rompimos una vez. Es distinto de las reglas de comportamiento —no dice cómo trabajar, dice dónde te vas a golpear— y por eso vive en su propio archivo.

Funcionó, y tiene un costo que no quiero disimular porque es un problema abierto y sin resolver: los agentes arrancan cargados antes de leer una línea de código. La continuidad y las cicatrices pesan más que las reglas del proyecto, y a eso hay que sumarle los documentos de diseño que el prompt manda leer primero. Cada error que evitás deja un párrafo, y los párrafos se acumulan más rápido que las soluciones. Hoy lo doy por bien pagado —prefiero un agente cargado a un agente que repite un error que ya cometimos—, pero está lejos de estar resuelto, y es lo próximo que tengo que atacar.

Las tres piezas irreductibles

Si tuviera que llevarme el sistema a una máquina limpia y solo pudiera llevar tres cosas, sé exactamente cuáles son.

El orquestador. Siempre tiene que estar. Es el rol que no se puede repartir: en el momento en que hay más de un agente decidiendo, no tenés un sistema distribuido, tenés criterios compitiendo sobre el mismo repo. Y no es solo quién decide, es quién verifica: un sistema de agentes sin nadie que corra los gates es un sistema donde el trabajo se acepta por declaración del que lo hizo.

La plantilla de delegación. Un archivo con la estructura del encargo, para no rearmar el contrato cada vez. No es un ahorro de tipeo: es lo que hace que el encargo salga completo aunque lo escribas apurado. La plantilla obliga a decir, siempre, quién es el agente y en qué proyecto está, qué tiene que leer antes de tocar nada, cuál es la tarea y cuándo está terminada, qué está prohibido, cómo se verifica el resultado y cómo se cierra. Sin ella, lo primero que se cae —siempre— es el criterio de terminado, que es justamente lo que separa un agente que entregó de un agente que se quedó sin turno.

La memoria. El archivo de continuidad del orquestador, o directamente un sistema de memoria persistente. Y va tercera a propósito, no por importancia sino por orden de dependencia. Sin orquestador no hay nadie que delegue. Sin plantilla, cada delegación se rearma desde cero y el sistema no sobrevive al apuro. Sin memoria, el sistema funciona igual de bien… durante una sesión. La memoria no es lo que hace que el sistema exista: es lo que hace que dure más de una sesión, y esa es la parte que se subestima siempre. El orquestador se llena de contexto, y cuando se llena o perdés el estado, o lo tenías escrito en algún lado.

Es un orden que solo se ve cuando algo falla. Con memoria pero sin plantilla, tenés un montón de contexto guardado sobre encargos mal formulados. Con plantilla pero sin orquestador, tenés encargos impecables que nadie verifica.

Y sé que son estas tres, y no otras, porque son las que reaparecen. En otra de las versiones del sistema —una que no tenía nada que ver con esta, con otro reparto y otros nombres— el agente central tenía escrito que no escribía código salvo cambios muy chicos y quirúrgicos. Lo que hacía era mantener el contexto global del proyecto, escribir los prompts de los subagentes, verificar con git y con los archivos que de verdad hubieran terminado, y recuperar de la memoria el estado de las cosas al empezar cada sesión. Coordinar, delegar con un contrato escrito, recordar: las mismas tres piezas, en un sistema que después tiré. Lo que fui descartando en cada reescritura fue todo lo demás.

Qué mejora de verdad

Esto es una valoración mía, no una medición, y el costo va junto al beneficio: el sistema se paga en tiempo de preparación y se cobra en estructura.

Lo que noto es que el trabajo vuelve con la forma de un trabajo de equipo y no con la forma de la salida de un prompt. Hay ramas por tarea, commits atómicos que se leen, PRs que explican qué se hizo, issues que enmarcan por qué se hizo, y una revisión que ocurre antes de que nada toque la rama estable. Nada de eso lo hace un agente porque sea más inteligente: lo hace porque el encargo se lo pide y porque hay alguien verificando que lo haya hecho. La calidad final que gané no vino de mejores respuestas, vino de que las respuestas llegan encuadradas.

Y hay un efecto lateral que valoro más de lo que esperaba: si el sistema no me sirve, lo cambio en el momento. El orquestador es el rol que puede modificar el sistema sobre la marcha, y como todo vive en archivos de texto plano, no hay nada que redesplegar. Una regla que resultó molesta se reescribe en la misma sesión en la que molestó. Eso hace que el sistema no envejezca por acumulación de reglas que ya no sirven pero que nadie se anima a tocar.

Lo que no voy a decir es que sea gratis. Preparar cuesta, y cuesta antes de que empiece a rendir. La diferencia con las versiones anteriores no es que esta no cueste: es que esta cuesta poco y rinde en proyectos chicos también, que es exactamente donde el organigrama se caía.

Lo que todavía es a mano

Acá está la parte incómoda, y prefiero terminar con ella.

No hay automatización real. Cuando arranco un proyecto nuevo, lo que hago es pedirle a un agente que copie el sistema del proyecto anterior y lo adapte. Funciona, y es exactamente el tipo de cosa que un sistema sobre delegación debería resolver primero en su propia casa.

Hice una skill de inicialización para eso, y quiero ser preciso con cómo la presento, porque no es ni un fracaso ni una solución. Instala el esqueleto del sistema delegando la instalación en un agente propio, con plantillas versionadas, y su política me parece la parte más lograda: sincroniza lo gestionado pero preserva siempre el estado local. La continuidad, las cicatrices y los prompts que ya existen no se pisan; valida el estado de Git y del remoto antes de escribir nada; y si un archivo gestionado difiere de lo que tiene registrado, pide aprobación antes de reemplazarlo. Está hecha durante este mismo proyecto y todavía no la apliqué a un proyecto nuevo. Ahorra el tiempo de inicializar, pero no arregla lo que faltaba —y esa distinción es justamente lo que me llevó a lo siguiente.

Lo siguiente es un sistema aparte, que está diseñado y sin construir. No voy a describir features que no existen; sí puedo decir cuál es la idea que lo motiva, porque es la que más me convence: registrar, al crear cada rama, una relación padre-hija inmutable, y usar eso como fuente de autorización para abrir PRs. Hoy esa autorización vive en reglas escritas que un agente puede leer mal. Ahí viviría en el estado del repositorio, que no se puede leer mal.

Sin fechas y sin promesas. El cierre honesto es este: armé un sistema que hace fácil delegar y que todavía es difícil de instalar. Ninguna de esas mitades me sorprende: una la trabajé durante meses y la otra no la trabajé nunca. Es el mismo error que le critico al organigrama —preparar mucho, empezar tarde—, cometido un nivel más arriba.