ADSM: directorios de nivel superior

Fecha de publicación: 2025-11-22

Etapa 3 del AFKP (inmersión). La etapa 2 (resonancia) se describe en la entrada del blog ADSM: directorios de nivel superior.

La naturaleza lingüística de los agentes

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

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

Por su naturaleza, un modelo de lenguaje puede servir de herramienta para transformar conocimiento en código sin necesidad de comprenderlo.
Toda la interacción con el modelo ocurre únicamente mediante texto.
El modelo solo trabaja con textos que son estadísticamente significativos para él.
El modelo realiza la inferencia dentro de un contexto finito donde la densidad de conexiones estadísticas disminuye conforme aumenta el volumen.

Mi enfoque para estructurar los archivos del proyecto está impulsado por estos axiomas. Ya he señalado que una persona y un agente interactúan de forma iterativa a través de un conjunto de textos jerárquicamente estructurados. En esta publicación describo 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 donde una persona y un agente LLM trabajan juntos.
código de la aplicación (fuentes): el resultado final de esa interacción.

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

Esta experiencia me hizo comprender que la documentación de un mismo producto puede montarse sobre diferentes bases de código en diversos lenguajes de programación. El mismo producto puede publicarse como distintas aplicaciones escritas para diferentes plataformas.

Es evidente que el lenguaje 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 uno en Node.js, pero en ambos casos se puede montar un directorio ./ctx/ en el repositorio del código y colocar allí los documentos del contexto cognitivo. O incluso se puede prescindir del montaje y crear el directorio ./ctx/ directamente en el repositorio de fuentes si el proyecto no es demasiado grande. En ese caso se obtiene una ventaja: 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 comercial del producto: un pequeño corpus de documentos que describen la idea del producto.
reglas para crear la aplicación correspondiente: un corpus mayor de documentos que regulan las normas para construir el producto en el lenguaje o grupo de lenguajes elegido.

./ctx/
    product/
    rules/

Los documentos del directorio product/ definen el esqueleto de la futura aplicación. Regulan qué debe hacer la aplicación pero no explican cómo. En esencia, estos documentos conforman el campo de acción del agente y dirigen su atención hacia los puntos críticos para el negocio. Es una exposición de proposiciones estadísticamente únicas. Por norma cada idea de negocio busca diferenciarse de la competencia y estos documentos contienen afirmaciones que probablemente no figuraban en el conjunto de entrenamiento del modelo que alimenta al agente.

Los documentos del directorio rules/ constituyen 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 funcional siguiendo estas reglas.

En mi proyecto de demostración construí una aplicación web utilizando 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 pudiera utilizar mi contenedor.

Comunicación humana con el agente

./ctx/
    agent/

En términos generales, este directorio almacena información operativa que inmediatamente se convierte en archivística. A través de este catálogo, el agente informa a su supervisor (una persona) sobre las acciones que ha realizado durante la iteración actual de trabajo con el código (ejecución de la tarea). Por norma, la persona que asigna la tarea está dentro del contexto de la misma en el momento de establecerla, pero ese contexto se disipa y se olvida rápidamente (aproximadamente en dos semanas, según mi experiencia).

Si se trabaja solo en el proyecto, como en mi caso, la necesidad de estos informes no es evidente: los agentes trabajan tan rápido que no me da tiempo a perder el contexto de la tarea (menos de una hora). Pero para el trabajo en equipo o proyectos más largos, dichos informes son útiles porque ayudan a cualquier miembro del equipo "de carne y hueso" a recuperar el contexto de desarrollo cuando se pierde. También resultan muy útiles cuando el agente ejecuta mal los comandos: analizarlos permite descubrir por qué el agente entendió mal la tarea.

Inicialmente, cuando separé los documentos del contexto y el código fuente en repositorios distintos, este directorio no formaba parte del contexto cognitivo porque debía estar dentro del repositorio base para poder hacer commits en la versión en la nube del agente Codex. Al ejecutar la versión CLI del agente o cuando las fuentes y el contexto cognitivo están en el mismo repositorio, el directorio ./agent/ puede permanecer dentro del contexto cognitivo (./ctx).

Resumen

Dado que el núcleo de cualquier agente—no solo Codex—es preparar un prompt para un LLM y transformar el resultado de la inferencia, los archivos de un proyecto deben estructurarse teniendo 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 constituye un estándar reconocido: simplemente refleja mi experiencia con el agente Codex. En líneas generales, he reflexionado y documentado mi práctica en esta publicación. La estructura de los subdirectorios en niveles inferiores ya va tomando forma, pero todavía no estoy listo para fijarla. Puedes consultar la estructura que describo en mi proyecto de demostración.

Si lo deseas, la etapa 4 del AFKP (significado) se puede realizar en este canal de Telegram.