AGENTS.md en ADSM: experiencia personal, conclusiones y líneas de desarrollo

Fecha de publicación: 2025-12-14

Introducción

Esta publicación describe el uso de archivos AGENTS.md en mis proyectos tomando como ejemplo el proyecto Svyazist.

El proyecto Svyazist lo desarrollo junto con el agente Codex dentro de mi propio enfoque ADSM. Este enfoque surgió como resultado de la práctica de programación contextual con agentes y está orientado a trabajar de forma sistemática con el contexto, las reglas y las restricciones arquitectónicas.

La publicación analiza el lugar que ocupa AGENTS.md dentro de la estructura del proyecto, las funciones que cumple en el proceso de trabajo y cómo se utiliza en la interacción con el agente. La descripción se basa en la configuración real del proyecto y refleja la práctica consolidada.

La publicación registra el estado actual de esta práctica y sirve como base para su desarrollo futuro dentro del enfoque ADSM.

Destino típico de AGENTS.md

El archivo AGENTS.md se utiliza como el lugar estándar para las instrucciones destinadas a las herramientas agent. Complementa el README.md al trasladar a un documento separado la información que necesita el agente para trabajar con el proyecto.

El AGENTS.md típico contiene la descripción de la estructura del proyecto, los comandos de compilación y prueba, las convenciones de estilo de código, las reglas del repositorio y otras instrucciones que el agente emplea al ejecutar tareas.

El formato del archivo permanece flexible y no impone requisitos estrictos de estructura.

Para proyectos con una estructura desarrollada se aplica una jerarquía de archivos AGENTS.md. El agente considera todos los archivos AGENTS.md a lo largo de la ruta desde la raíz del repositorio hasta el directorio de trabajo actual, y las instrucciones más cercanas al lugar de trabajo tienen prioridad.

En el agente Codex este mecanismo está implementado directamente: el agente descubre automáticamente los AGENTS.md, construye la cadena de instrucciones activas y las aplica durante el trabajo.

Tipos de AGENTS.md

En el enfoque ADSM, los archivos AGENTS.md conforman un sistema jerárquico de instrucciones donde cada nivel cumple funciones distintas.

En el nivel superior del proyecto se encuentra el AGENTS.md raíz. Define los límites generales de la actividad del agente, establece los roles básicos, los principios para trabajar con el contexto y los invariantes que se mantienen en todos los proyectos.

Más abajo en la estructura se hallan los AGENTS.md locales. Su propósito depende de su posición en la estructura de archivos y de significado. Estos archivos aclaran las reglas que rigen dentro de un espacio específico y sólo aplican dentro de su nivel.

Así se forma un sistema multinivel de instrucciones, donde el archivo raíz define la arquitectura general de la interacción y los archivos locales detallan el comportamiento del agente en secciones concretas del proyecto.

AGENTS.md locales

Los archivos AGENTS.md locales se emplean para fijar reglas y describir la estructura del trabajo en un nivel concreto del proyecto. Ese nivel puede corresponder a una parte del contexto cognitivo o a un segmento del código fuente. 

# <Nombre del nivel de documentación o código>

Path: `path/to/AGENTS.md`

## Propósito

<breve descripción del propósito de los documentos/código de este nivel>

## Mapa de nivel

- `dir/` — propósito del directorio en este nivel.
- `AGENTS.md` — el documento actual.
- `file.ext` — propósito del archivo en este nivel.

## <Las secciones siguientes dependen del nivel>

Esta estructura se usa para fijar los límites del nivel y las reglas de funcionamiento en su interior. El mapa de nivel describe de forma declarativa el contenido del directorio y sirve como modelo compacto de la estructura sin necesidad de abrir los archivos.

El título indica a qué nivel pertenece el archivo. La ruta fija su posición en la estructura del proyecto. La sección de propósito describe el rol del nivel y el ámbito de aplicación de las instrucciones.

Las secciones restantes dependen del tipo de nivel: en el contexto describen cómo trabajar con la documentación y cómo modificarla; en el código detallan las restricciones y convenciones que se emplean al editar los orígenes.

Los archivos locales se colocan sólo allí donde es necesario fijar explícitamente las reglas de trabajo y los límites de responsabilidad.

AGENTS.md raíz

En cada proyecto se utiliza un único archivo AGENTS.md raíz ubicado en la raíz del repositorio. Este archivo lo lee el agente primero y define las reglas generales de trabajo.

El AGENTS.md raíz establece el modelo básico del proyecto, incluyendo la división entre contexto y producto, y fija el orden de interacción entre ambos. También define los roles del humano y del agente, así como el modo de tomar en cuenta las instrucciones a lo largo del proyecto.

El archivo describe el mecanismo de jerarquía de AGENTS.md, los requisitos para las instrucciones locales, el uso de mapas de nivel, la protección de comentarios importantes en el código y la obligación de reportar al final de cada iteración.

El AGENTS.md raíz se utiliza sin cambios y proporciona una base estable sobre la que se apoyan todas las reglas del proyecto.

Un ejemplo de un AGENTS.md raíz típico utilizado en mis proyectos está disponible en:
<enlace al AGENTS.md raíz de ejemplo>

Este archivo establece una forma uniforme de trabajar con los agentes y permite aplicar el mismo enfoque en distintos proyectos.

El impacto de AGENTS.md en el trabajo del agente

Los archivos AGENTS.md no son programas en el sentido habitual. No se ejecutan y no imponen un comportamiento rígido al agente. El agente puede considerar las instrucciones parcialmente o ignorarlas, incluso si las exigencias están formuladas de forma explícita.

En la práctica esto se ve, por ejemplo, en los requerimientos de reporte. Aunque la obligación de terminar la iteración con un informe esté fijada en el archivo raíz, el agente puede olvidarse de generarlos o hacerlo de forma irregular. Esta observación resulta importante para entender correctamente el papel de AGENTS.md en el proyecto.

Al mismo tiempo, Codex sí escanea el sistema de archivos del proyecto y detecta los AGENTS.md en distintos niveles. Se puede ver esto en su comportamiento y en los registros de trabajo. Por lo tanto, los archivos son leídos por el agente, pero no lo controlan directamente.


Los límites de la gobernabilidad

La práctica muestra que las instrucciones en AGENTS.md funcionan como orientaciones más que como mandatos. No garantizan acciones concretas, pero influyen en el contexto que el agente conforma para resolver una tarea.

El agente obtiene su contexto de trabajo de forma independiente a partir de los documentos disponibles. Qué fragmentos elige y cómo los combina no se conoce de antemano. Esto impone límites naturales sobre el grado de gobernabilidad del comportamiento del agente mediante instrucciones textuales.

En ese sentido, AGENTS.md no fijan el comportamiento de forma directa, pero aumentan la probabilidad de que el agente opere dentro de los marcos previstos.

El AGENTS.md raíz como punto de entrada

En mis proyectos el AGENTS.md raíz actúa como el punto de entrada del agente en el proyecto. Su tarea es ofrecer una visión general de la estructura del proyecto, los roles y los principios de trabajo, no describir detalles.

En el archivo raíz se registran las direcciones: dónde está el contexto, dónde reside el producto, qué reglas se consideran básicas y qué invariantes deben preservarse. La detallación en este nivel no resulta eficiente y puede sobrecargar el contexto.

Este enfoque permite al agente orientarse en el proyecto sin que se le impongan instrucciones excesivas al comenzar a trabajar.

El contexto de la tarea

Al realizar una tarea concreta el agente conforma su propio contexto de trabajo. Este contexto se construye a partir de los documentos del proyecto y depende de la estructura de archivos, su volumen y su cohesión interna.

Es importante tener en cuenta que el agente no usa todo el contexto del proyecto. Selecciona fragmentos que considera relevantes para la tarea y los combina según sus reglas internas. Este proceso es opaco y no puede controlarse completamente.

Por eso el autor del contexto del proyecto no debe intentar describirlo todo en un único lugar, sino crear condiciones que permitan formar un contexto de trabajo coherente para la tarea.

Distribución de sentidos

La práctica muestra que los documentos grandes y monolíticos aumentan el riesgo de contradicciones en el contexto de la tarea. Cuando se carga un archivo así, el agente debe operar con un volumen amplio de significados diversos, lo cual complica formar un contexto interno consistente.

Un resultado más estable se obtiene distribuyendo los sentidos en varios documentos compactos y relacionados. Cada uno de ellos contiene un conjunto denso de significados vinculados a un área o nivel concreto.

De ese modo al agente le resulta más sencillo armar el contexto de trabajo a partir de bloques coherentes en lugar de fragmentos dispersos de un texto voluminoso.

Condiciones para la efectividad de AGENTS.md

AGENTS.md funcionan bien en tareas que requieren coordinación, cumplimiento de restricciones arquitectónicas y repetibilidad del proceso. Son especialmente útiles en proyectos con una estructura contextual desarrollada y un ciclo de vida prolongado.

Al mismo tiempo, en tareas pequeñas o puntuales el efecto de AGENTS.md puede ser mínimo. En esos casos el agente a menudo se apoya en el contexto local de la tarea y en sus propias heurísticas.

Esto indica que el uso de AGENTS.md tiene sentido no en todas partes, sino principalmente donde es importante gobernar el proceso a largo plazo.

AGENTS.md en ADSM

En el enfoque ADSM los archivos AGENTS.md se emplean como un elemento de apoyo para trabajar con el contexto del proyecto. Definen la estructura dentro de la cual el agente forma contextos de trabajo para tareas concretas, y enlazan la documentación, las reglas y el código en un único sistema.

AGENTS.md no están pensados para controlar directamente al agente. No dictan algoritmos ni garantizan el cumplimiento de las instrucciones. Su papel consiste en organizar el entorno en el que el agente trabaja y disminuir la incertidumbre semántica al formar el contexto de la tarea.

El AGENTS.md raíz establece el marco general y la dirección, mientras que los archivos locales precisan las reglas en niveles particulares. Juntos conforman una jerarquía de contexto que permite al agente orientarse en la estructura del proyecto y tomar en cuenta las restricciones sin atarse rígidamente a escenarios concretos.

Este enfoque no elimina por completo la incertidumbre, pero la hace manejable y reproducible. Permite utilizar agentes en proyectos complejos y de larga duración conservando la coherencia del contexto y la repetibilidad del proceso.

Esta página corresponde a la segunda etapa de AFKP (Acceptance-First Knowledge Principle) — "despliegue". La cuarta etapa ("comprensión") se puede realizar en este canal de Telegram o directamente en Habr.