Los agentes no necesitan personajes, necesitan una organización

Durante los últimos meses he visto aparecer toda clase de harnesses para agentes. Casi todos intentan resolver el mismo conjunto de problemas: dar contexto, dividir una tarea, ejecutar varios agentes en paralelo y conservar algún tipo de memoria.

Lo curioso es que muchas veces, después de construir toda esa infraestructura, llega el momento de organizar a los agentes y les asignamos roles como researcher, planner, coder o reviewer.

No están mal. Describen actividades que un agente puede realizar. Pero también se sienten como roles inventados desde las capacidades de la herramienta: uno busca, otro planea, otro escribe código y otro revisa lo anterior.

Me empecé a preguntar si estábamos diseñando organizaciones para agentes desde cero cuando llevamos décadas —o siglos, dependiendo de qué tan lejos queramos llevar la analogía— aprendiendo a coordinar organizaciones humanas.

Un equipo de software ya sabe qué hace un Product Owner, qué decisiones corresponden a un arquitecto, qué autoridad tiene un especialista de dominio y por qué quien implementó una tarea no debería ser la única persona que certifique que quedó bien. Esos roles no son únicamente nombres. Traen límites, responsabilidades, formas de comunicación y mecanismos de gobernanza que se han refinado con años de práctica, documentación y fracasos bastante caros.

Además, los modelos probablemente ya conocen mucho más sobre esas profesiones que sobre el rol de “agente planificador nivel tres” que acabamos de inventar en un archivo Markdown.

Esa pregunta terminó convirtiéndose en un sistema interno de herramientas y configuraciones de Codex que estoy construyendo para trabajar en un proyecto modular bastante más grande que una sola sesión.

Aunque “colección de configuraciones” se quedó corto bastante rápido.

El problema no era escribir mejores prompts

El proyecto que originó este experimento está pensado como un sistema grande y modular. Incluso antes de que exista toda su implementación, ya hay decisiones de producto, límites arquitectónicos, contratos compartidos, paquetes con responsabilidades distintas y trabajo que puede avanzar en paralelo.

Una sesión de un agente puede reconstruir buena parte de ese contexto y hacer una tarea. El problema aparece cuando llegan la segunda, la tercera y la décima sesión.

Cada una comienza sin memoria real de las anteriores. Puede leer el repositorio y GitHub, pero necesita saber qué información es normativa, qué decisión sigue abierta, qué trabajo ya está ocupado, qué cambió y quién tiene autoridad para aceptar el resultado. Si todo eso vive en el historial de una conversación, la organización desaparece cuando termina la sesión.

Mi primera intuición fue crear mejores instrucciones. Después aparecieron perfiles especializados. Luego skills para repetir procedimientos. Pero cuanto más avanzaba, más evidente se volvía que el problema no era únicamente de contexto.

Era de organización.

Un contrato de proyecto, no otro prompt global

El primer artefacto puede ser tan pequeño como un archivo versionado que conecte fuentes de conocimiento, perfiles y políticas:

{
  "knowledge": {
    "layers": [
      {
        "id": "product",
        "paths": ["docs/product/north-star.md"],
        "required": true
      },
      {
        "id": "runtime",
        "paths": ["docs/architecture/runtime.md"],
        "profiles": ["runtime-engineer"]
      }
    ]
  },
  "profiles": {
    "runtime-engineer": {
      "authority": ["Implementar dentro del contrato aceptado"],
      "exclusions": ["Cambiar alcance de producto", "Romper contratos compartidos"],
      "knowledge": ["runtime"],
      "acceptance": ["unit", "integration"]
    }
  },
  "policy": {
    "requireIndependentAcceptance": true
  }
}

El archivo no contiene toda la arquitectura ni intenta comprimir el producto en JSON. Señala dónde está la información autoritativa y quién puede actuar sobre ella.

La configuración ejecutable del perfil puede permanecer breve porque no necesita repetir todo el conocimiento:

name = "runtime-engineer"
description = "Implementa responsabilidades acotadas del runtime."

developer_instructions = """
Reconstruye los contratos e invariantes del área antes de editar.
Trabaja únicamente dentro de la responsabilidad reclamada.
Registra cambios, checks, decisiones y trabajo descubierto.
Entrega cambios de contratos compartidos al arquitecto.
"""

La especialización aparece al combinar esa instrucción con las fuentes y la autoridad declaradas por el proyecto, no al escribir una personalidad de tres páginas.

Un rol no es una personalidad

El sistema define perfiles como Product Owner, arquitecto, ingeniero de compiladores, ingeniero de runtime, ingeniero de proyecciones, curador de conocimiento e ingeniero de calidad.

No elegí esos nombres para hacer una representación corporativa dentro de Codex. Cada perfil existe porque el proyecto ya tiene esas responsabilidades.

El Product Owner puede definir resultados, alcance, prioridad y criterios de aceptación, pero no debería decidir unilateralmente la arquitectura de implementación ni terminar escribiendo el producto. El arquitecto puede revisar límites, contratos e invariantes, pero no ampliar el alcance del producto por conveniencia técnica. Los especialistas implementan dentro de su área. El ingeniero de calidad reconstruye los criterios y verifica la evidencia de forma independiente.

La parte importante no está en el nombre del perfil, sino en lo que el nombre arrastra:

• una autoridad explícita;
• responsabilidades positivas;
• exclusiones;
• conocimiento que necesita cargar;
• decisiones que puede tomar;
• condiciones bajo las que debe entregar el trabajo a otro perfil;
• evidencia que tiene que producir.

Decirle a un agente “eres arquitecto” aporta una perspectiva. Declarar qué contratos puede modificar, cuáles decisiones necesitan un ADR y qué cambios requieren coordinación introduce gobernanza.

Esa diferencia evita que los roles se conviertan en disfraces intercambiables para el mismo agente todopoderoso.

Las herramientas también deben pertenecer al proyecto

Otra tendencia común consiste en construir un harness genérico con herramientas genéricas y esperar que sus agentes se adapten a cualquier repositorio. Es útil hasta cierto punto: leer archivos, ejecutar comandos, consultar GitHub y abrir un pull request son capacidades universales.

Sin embargo, el trabajo importante casi siempre depende de operaciones específicas del proyecto.

En este sistema, context no significa “lee muchos archivos”. Reconstruye un paquete de contexto trazable para un perfil y una responsabilidad: el resultado esperado, sus criterios, las dependencias, las áreas afectadas, los contratos, los invariantes y la evidencia requerida.

next no significa “elige algo que parezca útil”. Busca trabajo elegible para la autoridad declarada.

Y antes de editar, una sesión solicita un lease. No basta con poner una etiqueta, asignarse el Issue y asumir que ningún otro agente hizo lo mismo unos milisegundos antes. El otorgamiento se serializa, tiene expiración y utiliza una generación de fencing para evitar que una sesión antigua continúe escribiendo después de perder su turno.

Sus skills tampoco almacenan la verdad del producto. Exponen procedimientos como tomar trabajo, delegar, dejar un handoff o verificar aceptación. Los hechos del producto permanecen en el repositorio que consume la capa de coordinación.

La diferencia parece pequeña, pero cambia el diseño: el harness deja de intentar saberlo todo y se convierte en una interfaz segura hacia la organización del proyecto.

La sesión no puede ser la memoria institucional

Esta fue la decisión que terminó ordenando todo lo demás.

En este modelo hay cuatro lugares con responsabilidades distintas:

Una conversación puede contener un hallazgo valioso. Un subagente puede descubrir un conflicto. El arquitecto puede detectar que una tarea requiere cambiar un contrato compartido. Pero nada de eso cuenta como memoria hasta que llega a un destino persistente.

Una decisión normativa debe vivir en un ADR o documento versionado. Un bloqueo debe registrarse con su evidencia y la acción necesaria. El trabajo descubierto fuera del alcance debe convertirse en otra responsabilidad. Un handoff tiene que indicar quién entrega, quién recibe, qué impacto existe y qué condición permite continuar.

El resumen final de un agente sirve para la persona que está mirando la sesión. No sirve como infraestructura organizacional para un agente que comenzará mañana sin acceso a ella.

Por eso GitHub funciona como plano de control del trabajo, no como fuente de verdad arquitectónica. Los Issues, PRs, checks y estados conectan sesiones independientes; los documentos versionados conservan las decisiones que no deberían reducirse a una etiqueta.

Gobernanza sin convocar una junta de robots

Hablar de roles organizacionales puede sonar como si quisiera recrear toda la burocracia de una empresa con agentes. Sería una manera muy eficiente de automatizar precisamente la parte que nadie disfruta.

La intención es la contraria: conservar únicamente las restricciones que evitan errores caros.

Un agente no puede ampliar la autoridad que recibió al delegar en un subagente. Dos ejecuciones paralelas no deberían escribir sobre el mismo conjunto de archivos. Una tarea no comienza hasta obtener un lease. Un descubrimiento no se convierte silenciosamente en más alcance. Y cuando la política exige aceptación independiente, una revisión realizada por un subagente dentro de la misma sesión no cuenta: el padre conserva la responsabilidad y comparte el mismo contexto e incentivos.

El objetivo no es imitar una jerarquía humana por nostalgia. Es reutilizar separaciones de responsabilidad que ya sabemos que producen controles útiles.

Incluso la escalación humana queda acotada. El sistema no debería preguntarme por cada detalle que pueda reconstruir del repositorio. Debe detenerse cuando hace falta dirección de producto, existe una decisión irreversible o costosa, chocan invariantes, hay un riesgo material o la información solo la conoce el propietario.

La gobernanza útil no agrega ceremonias. Reduce ambigüedad.

Una organización externa a sus integrantes

Lo que más me interesa de este experimento no es conseguir que siete agentes trabajen al mismo tiempo. El paralelismo es relativamente fácil; la coordinación duradera no.

Una organización humana no deja de existir cuando una persona se va a dormir. Sus acuerdos, responsabilidades, procesos y trabajo pendiente permanecen en sistemas externos a cualquier individuo. Si queremos que sesiones independientes colaboren de verdad, necesitan la misma propiedad.

Eso implica que un agente sea reemplazable. Otra sesión con el mismo perfil debe poder reconstruir el contexto, encontrar el trabajo, entender la evidencia existente y continuar sin depender de una memoria privada. El perfil aporta autoridad y método; el repositorio y GitHub aportan continuidad.

En ese sentido, el sistema no intenta construir un agente más inteligente. Intenta que varios agentes parcialmente informados puedan trabajar dentro de un sistema que limita lo que cada uno necesita saber y evita que su coordinación dependa de recordar una conversación.

Cómo diseñaría un sistema así para otro proyecto

La consecuencia práctica es que El sistema no debería instalar una “organización agéntica universal”. Puede aportar el kernel de coordinación, los esquemas y las operaciones seguras, pero los perfiles, el conocimiento y buena parte de las tools tienen que nacer del proyecto que lo consume.

No comenzaría preguntando cuántos agentes quiero. Comenzaría dibujando el trabajo que ya existe.

1. Encuentra las fuentes de verdad antes de crear roles

Primero hay que localizar dónde vive cada clase de decisión: visión del producto, arquitectura aceptada, contratos, estado de entrega, criterios de calidad y conocimiento operativo. Si dos documentos se contradicen, agregar agentes solo permite producir inconsistencias en paralelo.

El resultado no debería ser un prompt gigantesco, sino un mapa de fuentes autoritativas y sus alcances. Cada perfil carga únicamente las capas necesarias para su responsabilidad. El especialista de compiladores no necesita todo el roadmap comercial para corregir el sistema de tipos; el Product Owner no necesita recorrer cada archivo del runtime para definir un resultado.

2. Deriva los roles de las decisiones reales

Los roles aparecen al preguntar:

• ¿qué resultados distintos produce este proyecto?;
• ¿qué decisiones requieren conocimiento especializado?;
• ¿qué contratos atraviesan varias áreas?;
• ¿qué trabajo necesita una verificación independiente?;
• ¿dónde ocurren hoy los handoffs, incluso si los hace una sola persona?

Si no puedes escribir la autoridad y las exclusiones de un rol, probablemente todavía sea solo una etiqueta. “Backend agent” dice dónde trabaja. “Responsable del contrato de identidad, sin autoridad para cambiar políticas de producto” dice qué puede decidir.

3. Diseña tools desde los verbos del dominio

Después conviene listar qué operaciones repite cada rol para obtener información o cambiar el estado del proyecto. No solo comandos técnicos, sino verbos organizacionales.

Un Product Owner quizá necesita crear capacidad, dividir en tareas y registrar alcance descubierto. Un arquitecto necesita resolver consumidores de contrato, crear ADR y solicitar coordinación. Un especialista necesita tomar trabajo, obtener contexto del área, ejecutar checks del dominio y entregar un bloqueo. Calidad necesita reconstruir criterios, verificar evidencia y aceptar o rechazar.

Una buena tool reduce una decisión ambigua a una operación verificable. También valida autoridad, produce un resultado estructurado y deja trazabilidad. Si únicamente envuelve Git o una llamada a GitHub sin semántica del proyecto, sigue siendo infraestructura genérica.

Hay una prueba sencilla: si la tool podría instalarse sin cambios en cualquier repositorio, probablemente pertenezca al harness base. Si necesita conocer los contratos, estados, invariantes o evidencia de este producto, pertenece a la configuración del proyecto.

Una tool específica podría exponer una operación segura en lugar de permitir que cada sesión improvise varias mutaciones:

const result = await work.claim({
  workItem: issue.number,
  profile: "runtime-engineer",
  sessionId,
  idempotencyKey,
});

if (!result.granted) {
  throw new Error(`Trabajo no disponible: ${result.reason}`);
}

return {
  lease: result.lease,
  context: await context.resolve({
    profile: "runtime-engineer",
    responsibility: issue.number,
  }),
  requiredEvidence: ["tests", "integration", "decision-links"],
};

La parte interesante no es el wrapper de TypeScript. La operación verifica que el perfil sea elegible, concede el trabajo de manera atómica y devuelve exactamente el contexto y la evidencia que esa responsabilidad necesita. Una llamada genérica a “asignar Issue” no contiene ninguna de esas garantías.

4. Define el contrato mínimo de cada perfil

Para cada rol escribiría al menos:

Las instrucciones de personalidad son opcionales. Este contrato no.

5. Diseña primero el camino de una sola tarea

Antes de lanzar siete sesiones en paralelo, haría que una responsabilidad complete todo su ciclo: intención, descomposición, claim, contexto, implementación, evidencia, handoff y aceptación. En cada transición preguntaría qué dato necesitaría una sesión nueva que no vio ninguna conversación anterior.

Ese ejercicio descubre los huecos reales. Si la segunda sesión necesita que una persona le explique qué pasó, todavía falta persistir algo. Si dos perfiles creen poder tomar la misma decisión, falta gobernanza. Si nadie puede demostrar por qué el trabajo está terminado, falta un contrato de evidencia.

Solo después agregaría paralelismo, leases y reconciliación. Coordinar más agentes no arregla un flujo incompleto; solo hace que falle con más entusiasmo.

6. Conserva un humano donde exista dirección, no por defecto

El sistema debe resolver de forma autónoma lo que pueda reconstruir y verificar. La intervención humana sigue siendo necesaria para dirección de producto, decisiones irreversibles o costosas, conflictos entre invariantes, riesgos materiales e información que no está documentada.

La meta no es retirar al humano de cada decisión. Es evitar usarlo como memoria USB entre sesiones.

Todavía es un experimento

El sistema sigue en desarrollo y nació alrededor de las necesidades concretas de un proyecto privado. Actualmente tiene siete perfiles, skills para trabajo, delegación, handoffs y aceptación, además de un CLI que instala el contrato del proyecto y reconstruye contexto. El protocolo de leases y reconciliación todavía es una parte especialmente delicada: coordinar escrituras concurrentes mediante GitHub exige más que encadenar varias llamadas que “normalmente” ocurren en orden.

Tampoco creo que copiar los roles de una empresa sea automáticamente correcto. Una mala organización humana no se vuelve buena por ejecutarse más rápido, y hay procesos que existen por restricciones humanas que quizá no tengan sentido para agentes. La separación entre autoridad, ejecución y aceptación sí parece sobrevivir al cambio de integrantes; las ceremonias, probablemente no todas.

Por ahora, la hipótesis que quiero probar es más modesta:

Los agentes no necesitan que inventemos una nueva organización desde cero solo porque ellos son nuevos.

Podemos empezar con los oficios, límites y mecanismos de coordinación que ya entendemos; convertirlos en contratos verificables; darles herramientas específicas del proyecto; y sacar la memoria de las sesiones.

Quizá el siguiente salto en sistemas agénticos no venga de crear personajes más convincentes.

Quizá venga de construir instituciones pequeñas que puedan sobrevivirlos.