Experimentos con Agent Handoff (v1)

Documentación v1 de un método experimental propio, nacida como capa de soporte para cusp (Custom Sandbox Pipeline)

Por qué existe este artículo

Este texto no nace de una intención de crear una metodología. Nace de un problema concreto: mientras diseñaba cusp, una herramienta personal de despliegue, me di cuenta de que el verdadero cuello de botella no era el código — era la relación entre yo y el agente IA que iba a construirlo conmigo. Cada sesión nueva, el agente perdía contexto, infería decisiones que yo ya había tomado, y repetía preguntas que ya habíamos resuelto. La fricción no estaba en la infraestructura, estaba en la comunicación.

Documento el método que armé para resolver eso — con la honestidad de llamarlo lo que es: un prototipo experimental, v1, probado en un solo proyecto real, construido en conversación con un agente IA, y revisado después contra literatura publicada para separar lo que es genuinamente mío de lo que ya existía con otro nombre.

El problema real: inferencia como fuente de error

Cuando un agente retoma un proyecto y solo cuenta con el código fuente, tiene que reconstruir la arquitectura, el flujo y las decisiones de diseño a partir de la implementación. Ese proceso de reconstrucción es, estructuralmente, una adivinanza informada — y ahí es donde se cuela el error: el agente no está leyendo la verdad de lo que se decidió, está infiriendo una hipótesis a partir de síntomas.

No soy el único que identificó este problema en estos términos. Trabajo reciente sobre desarrollo de software agéntico describe el mismo fenómeno con precisión: cuando un agente autónomo, un ingeniero recién incorporado, o un desarrollador senior navegando un código desconocido se encuentra con una tarea empresarial sin contexto institucional, el resultado es siempre el mismo — conjeturas, cascadas de corrección, y un impuesto desproporcionado sobre los ingenieros senior que terminan supliendo manualmente lo que otros no pueden inferir. El mismo trabajo traza el paralelo explícito: es estructuralmente el mismo ciclo que atraviesa un ingeniero nuevo entrando a un código ajeno, solo que comprimido en turnos de ventana de contexto en vez de semanas.

El giro: no es documentación, es un protocolo de transición de estado

Durante buena parte de esta construcción pensé el sistema como "documentación optimizada para IA". Una conversación posterior, comparando notas con otro modelo sobre el diseño, me hizo ver algo que no había nombrado: no estaba documentando un proyecto, estaba diseñando el punto exacto donde el conocimiento deja de ser conversación y pasa a ser algo que un agente puede ejecutar sin haber participado de la conversación original.

Hay dos regímenes de trabajo que no deberían mezclarse. Uno humano — donde todo es ambiguo, cambia, se debate, se revierte. Y uno operativo — donde un agente necesita empezar desde un estado consistente, no desde el historial completo de cómo se llegó ahí. El sistema que armé funciona, en la práctica, como el punto de conversión entre los dos: planificación conversacional → un momento donde ese conocimiento se fija en .agent/ → una sesión nueva, sin memoria de la conversación anterior, que se incorpora directo a la fase operativa leyendo ese estado fijado.

Vale la aclaración honesta: la idea de consolidar conocimiento conversacional en un artefacto estructurado no es mía en su forma general. Investigación reciente sobre desarrollo de agentes expertos de dominio describe un ciclo de cuatro fases — inmersión conversacional, acumulación experiencial, cristalización deliberada, y aplicación fundamentada — donde la cristalización es explícitamente un proceso deliberado y periódico que consolida patrones en activos de conocimiento estructurado. Lo que yo describo es una instancia mucho más acotada de esa misma idea general: no un ciclo continuo de aprendizaje de un agente experto, sino un único punto de corte fijo entre planificación y ejecución, formalizado como archivos versionables en dos formatos distintos según su función.

El método: dos lenguajes, dos propósitos

`.md` — para que la IA piense

Un archivo de contexto narrativo (CONTEXT.md) explica filosofía, intención, decisiones de diseño y su razonamiento. Es prosa, deliberadamente. Sirve para que el agente entienda por qué existen las reglas — nunca se ejecuta directamente, solo se consulta cuando una regla explícita no cubre un caso.

`.toon` — para que la IA ejecute

TOON (Token-Oriented Object Notation) es un formato tabular pensado para consumo de modelos de lenguaje: declara campos una sola vez y transmite filas de datos sin repetir estructura, a diferencia de JSON o markdown, donde cada objeto repite sus propias claves. Los benchmarks públicos del formato reportan una reducción de tokens cercana al 40% frente a JSON, con mejor precisión de parseo — 76.4% contra 75.0% en las pruebas del propio proyecto TOON.

Ese ahorro de tokens es real, pero no es el argumento central del método. El argumento central es estructural: un archivo .toon no da espacio a prosa, y por lo tanto no da espacio a ambigüedad de interpretación. Una regla como git_push,PROHIBIDO_SIEMPRE no puede leerse de dos maneras. Una oración explicando lo mismo, sí puede.

Vale una honestidad técnica adicional: la ventaja de tokens de TOON depende del tamaño del contenido — el costo fijo de "enseñarle" al modelo la sintaxis puede anular el ahorro en outputs muy cortos, y se vuelve rentable cuando el contenido crece lo suficiente para que el ahorro acumulado lo compense. En un sistema de reglas que crece feature a feature, esa condición se cumple rápido.

No conozco, en el material que revisé, otro sistema que use esta separación de formato (no solo de archivo o de fase) según la función cognitiva del contenido — prosa para razonar, tabla atómica para ejecutar. Esa distinción específica es, hasta donde pude verificar, el aporte propio más defendible de todo el método.

FEATURE.toon: representación operativa, no documentación

Cada feature de un proyecto — no el proyecto entero, cada pieza individual — tiene su propio archivo .toon, nombrado en mayúsculas según el feature (WISHLIST.toon, PUSH.toon), viviendo dentro de la carpeta real de ese feature en el código.

Ese archivo explica al agente el ciclo de vida completo del feature en una sola lectura: dónde nace la lógica, cada transformación que atraviesa, dónde termina, qué tipos de datos usa o produce, de qué depende. Sin prosa. Sin que el agente necesite abrir el código fuente para entender la intención — el agente ya lo vio una vez, y ese conocimiento queda externalizado para que el siguiente agente no tenga que reconstruirlo leyendo código de nuevo.

Esto también conecta con un problema ya nombrado en la literatura: el cuello de botella del desarrollo de software agéntico no es la capacidad del modelo, es la arquitectura del conocimiento — cuando ese conocimiento institucional queda atrapado en formatos pensados solo para interpretación humana, cada consumidor nuevo (agente o persona) repite el mismo ciclo de adivinanza. FEATURE.toon es mi resolución puntual a ese problema, a nivel de una sola pieza de código, no a nivel de una organización entera.

Trae una regla de sincronización estricta: si el feature cambia, el .toon cambia en el mismo ciclo. Nunca puede quedar un .toon describiendo una versión del feature que ya no existe — porque eso sería peor que no tener .toon: sería una fuente de verdad que miente con autoridad.

Jerarquía de gobierno: por qué el orden importa

Las reglas que gobiernan al agente (RULES.toon) siguen una cascada fija:

Seguridad — prohibiciones duras (nunca hacer push, nunca commitear sin aprobación, nunca modificar código sin preguntar antes)
Alcance — qué es y qué no es el proyecto
Permisos — qué puede hacer el agente, en detalle
Automatización — qué se dispara sin pedir permiso (la excepción acotada)
Protocolo de ambigüedad — qué hacer cuando ninguna regla cubre el caso
Meta — información sobre el documento mismo

El orden no es estético. Cuando dos reglas entran en conflicto, gana la categoría que aparece primero — eso resuelve la prioridad sin que el agente tenga que inferir cuál pesa más. Es, en esencia, una implementación artesanal de lo que la industria está empezando a formalizar como policy-as-code para agentes: reglas de permisos, aprobación y límites traducidas a algo verificable y versionado, no reglas que solo existen en la cabeza de quien las escribió.

Un hallazgo no planeado: el bootstrap auto-propagante

Durante la construcción probé algo fuera del plan original: en vez de escribir AGENTS.md a mano de antemano, le ordené al agente leer primero RULES.toon y CONTEXT.md — y dejé que él mismo, ya gobernado por esas reglas, generara su AGENTS.md como puntero hacia ellas.

El resultado fue mejor que lo planeado: ese AGENTS.md no es una promesa mía de cómo debería comportarse el agente, es un artefacto que el agente produjo después de haber entendido el sistema — refleja comprensión real, no expectativa. De ahí en adelante, cualquier agente nuevo que entre al proyecto encuentra AGENTS.md por la convención ya estándar del ecosistema, sigue el puntero, y queda gobernado igual sin repetición manual. Este patrón puntual — generación diferida del puntero, posterior a la comprensión — no lo encontré documentado en el material que revisé.

Trabajos relacionados

Ninguna idea nace en el vacío, y prefiero nombrar explícitamente dónde este método pisa terreno ya explorado por otros, en vez de dejarlo implícito:

AGENTS.md (estándar abierto, hoy bajo la Agentic AI Foundation de la Linux Foundation) resuelve dónde vive el contexto de un agente. Este método no lo reemplaza — lo usa como entrypoint, y construye la separación de formato que el estándar no define.
Knowledge Crystallization (investigación 2026 sobre desarrollo de agentes expertos de dominio) describe la consolidación de conocimiento conversacional en activos estructurados como proceso cíclico y continuo. Este método aplica una versión mucho más acotada de la misma idea: un único punto de corte entre planificación y ejecución, no un ciclo de aprendizaje continuo.
Knowledge Activation (investigación 2026 sobre desarrollo de software agéntico empresarial) nombra el mismo problema de fondo — conocimiento institucional atrapado en formatos solo-humanos, y el paralelo estructural con onboarding humano. Este método es una implementación puntual, a escala de un solo proyecto personal, del mismo diagnóstico.
Policy-as-code para agentes — la formalización de reglas de gobierno como código verificable, en vez de documentos de prosa, es una tendencia ya en marcha en la industria (ej. especificaciones de control de agentes publicadas por proveedores de infraestructura en 2026). La jerarquía de RULES.toon es una implementación artesanal, de una sola persona, de la misma idea.

Qué NO es este método

No es Spec-Driven Development formal. SDD es una disciplina más amplia, con tooling, validación automática y garantías que este método no tiene todavía.
No está probado a escala. Corrió sobre un solo proyecto, en desarrollo activo, no en producción con múltiples colaboradores.
No es el primer trabajo en identificar estos problemas, como queda documentado arriba. Lo que aporta es una combinación puntual — separación de formato por función cognitiva, especificación de ciclo de vida por feature, jerarquía fija de reglas, y el patrón de bootstrap diferido — no el diagnóstico del problema en sí.
No elimina el riesgo de exposición, lo traslada. Publicar reglas de gobierno atómicas y textuales es, en potencia, una superficie legible para quien quiera manipular a un agente que las siga. Mi resolución fue separar gobierno real (privado) de un ejemplo curado (público, ilustrativo, no ejecutable sobre nada real) — es una mitigación, no una eliminación.
No reemplaza revisión humana. El agente propone cambios ante fixes, errores o contradicciones que detecta — nunca los ejecuta sin aprobación explícita.

Qué busco con esto, en una frase

No busco vender una metodología terminada ni un descubrimiento aislado. Busco documentar, con evidencia real de una sesión de trabajo genuina y en conversación honesta con la literatura ya publicada, una combinación puntual que redujo la inferencia — la fuente más silenciosa de error cuando un agente actúa sobre un proyecto que no escribió desde cero.

Esto es v1. La intención es seguir iterando sobre cusp como caso de prueba, y volver a escribir sobre lo que cambie, lo que se rompa, y lo que efectivamente se sostenga con el tiempo.