ADSM: directorios de nivel superior

Fecha de publicación: 2025-11-22

La naturaleza lingüística de los agentes

Los agentes más populares utilizados hoy para crear aplicaciones de software se basan en Grandes Modelos de Lenguaje (LLM). Lo principal que hace a un agente "inteligente" es preparar una solicitud para el LLM (un prompt) y luego analizar el resultado de esa solicitud y registrarlo como un nuevo archivo de texto (por ejemplo, con código fuente) o como cambios a uno existente.

Por el momento puedo formular cuatro afirmaciones que llamo las "4 axiomas de ADSM":

1. Por su naturaleza, un modelo de lenguaje puede servir como una herramienta para transformar conocimiento en código sin necesidad de comprenderlo.
2. Toda la interacción con el modelo ocurre únicamente a través de texto.
3. El modelo solo trabaja con textos que son estadísticamente significativos para él.
4. El modelo realiza la inferencia dentro de un contexto finito donde la densidad de las conexiones estadísticas disminuye a medida que crece el volumen.

Mi enfoque para estructurar los archivos del proyecto está impulsado precisamente por estos axiomas. Ya he señalado que una persona y un agente interactúan de manera iterativa a través de un conjunto jerárquicamente estructurado de textos. En esta publicación describiré la estructura de directorios de nivel superior que utilizo actualmente en mis proyectos con agentes LLM.

Código y documentos

Inicialmente, dividí todos los archivos en dos repositorios de GitHub:

• documentos del proyecto: el contexto cognitivo en el que trabajan juntos una persona y un agente LLM.
• código de la aplicación (fuentes): el resultado final de su interacción.

Para permitir que el agente actuara en ambos espacios, dos repositorios separados se unieron en una sola estructura de archivos al configurar la versión en la nube del agente Codex. Al iniciar el agente Codex, monté el repositorio con los documentos en el directorio ./ctx del repositorio base (con el código fuente), y para el agente era una única estructura de archivos, aunque en realidad estuviera repartida en diferentes repositorios. Al mismo tiempo, el agente podía hacer commits solo en el repositorio base. Los documentos del proyecto se usaban en modo de solo lectura.

En esta experiencia entendí que la documentación de un mismo producto puede montarse en diferentes bases de código en distintos lenguajes de programación. El mismo producto puede publicarse como varias aplicaciones escritas para distintas plataformas.

Está claro que el lenguaje de programación elegido para la implementación impone sus propios requisitos a la estructura de archivos del repositorio con el código fuente. Un proyecto en Python será diferente de un proyecto en Node.js, pero en ambos casos se puede montar un directorio ./ctx/ en el repositorio con el código fuente y colocar allí los documentos del contexto cognitivo. O incluso se puede prescindir del montaje y crear directamente el directorio ./ctx/ en el repositorio de código fuente si el proyecto no es demasiado grande. En ese caso aparece un bono: el agente también puede modificar la documentación si es necesario.

Producto y aplicación

De esta comprensión surgió la idea de que toda la documentación del directorio ./ctx/ puede dividirse en dos partes desiguales:

• descripción de negocio del producto: un pequeño corpus de documentos que describen la idea del producto.
• reglas para crear la aplicación correspondiente: un corpus más amplio de documentos que regulan las normas para crear el producto en el lenguaje o grupo de lenguajes elegido.

./ctx/
    product/
    rules/
    

Los documentos del directorio product/ establecen el esqueleto de la futura aplicación. Regulan qué debe hacer la aplicación, pero no dicen cómo. En esencia, estos documentos forman el campo de acción para el agente y dirigen su atención a los puntos críticos para el negocio. Es una exposición de proposiciones estadísticamente únicas. Por regla general, cada idea de negocio busca diferenciarse de las competidoras, y estos documentos contienen proposiciones que probablemente no formaban parte del conjunto de entrenamiento del modelo en el que se basa el agente.

Los documentos del directorio rules/ son la parte más importante para que el agente genere o modifique código. Regulan las acciones del agente al nivel necesario para escribir código fuente. Debido a la naturaleza estadística de los LLM, cuanto más "promedio" estén formulados estos documentos, cuanto más se acerquen al "promedio" del conjunto de entrenamiento, menos texto necesita el agente para generar código fuente funcional siguiendo estas reglas.

En mi proyecto de demostración construí una aplicación web usando mi propio contenedor de objetos con inyección de dependencias en el constructor, lo que requirió varios documentos separados en ./rules/ que regulaban la creación de nuevos módulos ES6 que pudieran ser utilizados por mi contenedor.

Comunicación humana con el agente

./ctx/
    agent/
    

En términos generales, este directorio almacena información operativa que se vuelve de inmediato archivística. A través de este directorio el agente informa a su supervisor (una persona) sobre las acciones que ha realizado durante la iteración actual de trabajo sobre el código (ejecución de la tarea). Por regla general, la persona que asigna la tarea al agente está en el contexto de la tarea en el momento de definirla, pero ese contexto se disuelve y se olvida rápidamente (aproximadamente en dos semanas, según mi experiencia).

Si una persona trabaja en el proyecto en solitario, como en mi caso, la necesidad de estos informes no es evidente: los agentes trabajan lo suficientemente rápido como para que yo no pierda el contexto de la tarea (menos de una hora). Pero para el desarrollo en equipo o proyectos más largos, esos informes son útiles porque ayudan a cualquier miembro del equipo "de carne y hueso" a restaurar el contexto de desarrollo cuando se pierde. Estos informes también resultan bastante útiles cuando el agente ejecuta comandos de forma incorrecta: analizarlos ayuda a descubrir por qué el agente entendió mal la tarea.

Inicialmente, cuando separé los documentos del contexto y el código fuente en diferentes repositorios, este directorio no formaba parte del contexto cognitivo porque debía estar en el repositorio base para poder hacer commits en la versión en la nube del agente Codex. En caso de ejecutar la versión CLI del agente o si tanto las fuentes como el contexto cognitivo se encuentran en el mismo repositorio, el directorio ./agent/ puede mantenerse dentro del contexto cognitivo (./ctx).

Resumen

Dado que la esencia de cualquier agente —no solo de Codex— es preparar un prompt para un LLM y transformar el resultado de la inferencia, los archivos de un proyecto deben estructurarse de modo que tengan en cuenta la naturaleza de los LLM. En mi caso, esto da lugar a la siguiente estructura de directorios de nivel superior:

./ctx/
    agent/
    product/
    rules/
    

Esta estructura no es ningún tipo de estándar: simplemente refleja mi experiencia con el agente Codex. En líneas generales, he reflexionado y plasmado mi práctica en esta publicación. La estructura de los subdirectorios en niveles inferiores ya se está perfilando, pero todavía no estoy listo para fijarla. Puedes consultar la estructura que describo en mi proyecto de demostración.