---
title: "ADSM: directorios de nivel superior"
date: 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](/es/blog/2025/20251122-01-adsm-top-level-directories.html).*

## 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*":

1.  Por su naturaleza, un modelo de lenguaje puede servir de herramienta
    para transformar conocimiento en código *sin necesidad de
    comprenderlo*.
2.  Toda la interacción con el modelo ocurre únicamente mediante 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 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](https://habr.com/ru/articles/948282/)
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](https://github.com/flancer64/pwa-home-call/tree/milestone/20251122-adsm-top-level-dirs).

*Si lo deseas, la etapa 4 del AFKP (significado) se puede realizar en
este [canal de Telegram](https://t.me/alexgusev_lab_es).*