Actualizar AGENTS.md automáticamente con dox

Por qué su archivo AGENTS.md queda obsoleto tres semanas después

Un archivo AGENTS.md queda obsoleto porque no existe ninguna conexión con el código. Se escribe una vez, manualmente, el día en que el repositorio tiene un estado determinado. Luego, el ejecutor de pruebas cambia, un paquete se renombra, un servicio se elimina y el archivo sigue describiendo el estado de junio. Nada falla, porque ningún paso de compilación lo lee.

El agente lo lee y le da credibilidad. Esa es la parte que le cuesta dinero. Un repositorio sin AGENTS.md obliga al agente de programación a inspeccionar el entorno antes de actuar. Un repositorio con un AGENTS.md incorrecto hace que deje de inspeccionar, porque ya tiene una respuesta. Ejecuta el comando que indica su archivo, la shell responde Missing script: "test" y, entonces, el agente comienza a adivinar. A menudo, edita package.json para añadir el script que su documentación prometía. El archivo obsoleto no falló de forma silenciosa. Provocó una edición que usted no deseaba.

dox es una respuesta a esto. Es un conjunto de reglas, escritas para el agente, que hace que actualizar la documentación sea parte de finalizar el trabajo, de modo que el archivo cambie en el mismo commit que el código que lo dejó obsoleto.

Qué es dox y qué no es

dox es un único archivo Markdown. El repositorio es agent0ai/dox, tiene licencia MIT y, a fecha de 11 de agosto de 2026, el proyecto completo es un AGENTS.md de 3906 bytes, un README, un LICENSE y dos imágenes. No hay ningún paquete que instalar ni tiempo de ejecución.

Esto es importante, porque la palabra generador sugiere un programa que analiza su código. Nada analiza su código. dox es un contrato que lee su agente de programación: su agente es el generador, y dox es el conjunto de instrucciones que le indica cuándo leer la documentación, cuándo reescribirla y qué forma debe tener cada documento.

El archivo tiene diez secciones y dos de ellas realizan el trabajo. "Leer antes de editar" indica al agente que recorra desde la raíz del repositorio hasta cada ruta que planea modificar, y que lea cada AGENTS.md a lo largo de cada ruta, en la sesión actual, sin depender de la memoria. "Actualizar después de editar" le indica que cada cambio significativo requiere una pasada de DOX, lo que significa que un paso de actualización de la documentación debe ejecutarse antes de considerar la tarea como terminada. La pasada actualiza el documento propietario más cercano cuando cambian el propósito, la estructura, el flujo de trabajo, los permisos o las preferencias del usuario.

El resto es forma. Un AGENTS.md hijo tiene un orden de secciones predeterminado: Propósito, Propiedad, Contratos locales, Guía de trabajo, Verificación e Índice de DOX hijo. El archivo raíz contiene las reglas de todo el proyecto además del Índice de DOX hijo de nivel superior, que es cómo un agente descubre los documentos hijos. "Cierre" es la lista de verificación que el agente ejecuta al final de una tarea: volver a comprobar las rutas modificadas frente a la cadena, actualizar los documentos propietarios más cercanos, actualizar cada índice afectado, eliminar contradicciones, ejecutar la verificación existente e informar de qué documentos dejó intactos deliberadamente.

Fijar la documentación a un commit específico, no a main

El repositorio no tiene etiquetas ni versiones (releases), por lo que no hay un número de versión que fijar. Fije el commit en su lugar. El archivo AGENTS.md actual corresponde al commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, con fecha del 1 de agosto de 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c debería imprimir 3906. Un número distinto significa que no ha obtenido el archivo que describe esta guía, así que léalo antes de confiar en él. Si escribe mal el hash del commit, -f hará que curl se detenga con curl: (22) The requested URL returned error: 404 y no escriba contenido, y wc -c imprimirá entonces 0. Un archivo truncado es peor que no tener archivo, porque el agente seguiría la mitad de un contrato sin saberlo.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Ese cp es para un repositorio que aún no tiene un AGENTS.md. Si ya tiene uno, no lo sobrescriba. Coloque las secciones de documentación sobre su contenido existente, mantenga sus propias reglas debajo y lea el resultado una vez de principio a fin. Dos documentos que se contradicen producen un agente que sigue la última línea que leyó.

Luego, solicite a su agente, dentro del repositorio, que realice la primera pasada. El README proporciona la redacción exacta:

Initialize DOX tree for this project now.

Esto crea los archivos AGENTS.md secundarios y los índices que apuntan a ellos. Verifique lo que hizo antes de confiar en el resultado:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Cada archivo en esa salida de find debería aparecer en algún Índice de Documentación Secundario (Child DOX Index) por encima de él. Un documento secundario que no menciona ningún índice es uno que el agente puede pasar por alto, ya que el índice es el mecanismo mediante el cual encuentra documentos que no se encuentran directamente en la ruta que está recorriendo.

Lo que dox puede ver y lo que no puede saber

El agente que construye su árbol lee el repositorio, por lo que cualquier elemento del repositorio puede incluirse en el inventario: la estructura de directorios, los manifiestos de paquetes y archivos de bloqueo, los scripts en package.json, Makefile o pyproject.toml, los archivos de flujo de trabajo de CI, los Dockerfiles, los puntos de entrada y el CODEOWNERS si dispone de uno. Un inventario construido a partir de estos elementos se mantiene realmente por sí mismo. Cuando un paquete se mueve, la siguiente pasada mueve la línea que lo describe.

Todo lo que aparece a continuación debe declararlo usted, ya que no se encuentra en el repositorio para ser leído:

• por qué existe una regla, lo cual evita que un agente la elimine por considerarla una complejidad innecesaria
• cuál de las dos rutas de trabajo es la admitida y cuál está pendiente de eliminación
• cualquier elemento fuera del repositorio, como el entorno de staging o el motivo por el que una dependencia está fijada dos versiones atrás
• lo que planea hacer la próxima semana, que es la diferencia entre un archivo actual y un archivo útil

dox sabe esto sobre sí mismo. Sus propias reglas indican que la Guía de Trabajo debe reflejar los estándares actuales del proyecto o las instrucciones del usuario, y que si aún no existen, debe dejar la sección vacía. La verificación debe reflejar una comprobación existente, por lo que si no hay un framework de pruebas en el repositorio, esa sección permanece vacía hasta que lo haya. Un archivo generado que inventa un estándar es peor que una sección vacía, porque el agente aplicará entonces dicha invención.

Mantenga la intención escrita a mano fuera del inventario generado

Este es el fallo que hace que la gente abandone la documentación generada. Usted escribe un párrafo explicando que la cola de trabajos debe mantener un único consumidor. Tres semanas después, un proceso de automatización reescribe el archivo y su párrafo desaparece, oculto en un diff de cuarenta líneas que mayormente reorganiza nombres de archivos, y nadie se da cuenta.

Existen dos mecanismos, y usted necesita ambos.

Primero, mueva la intención duradera a un archivo diferente. Las decisiones de diseño y el razonamiento detrás de ellas pertenecen a un DESIGN.md escrito para el agente, y las notas que existen para las personas pertenecen al lugar donde usted separa HUMAN.md de AGENTS.md. AGENTS.md contiene entonces el inventario y los contratos locales, que es exactamente la parte que debe cambiar cuando el código cambia.

Segundo, proteja la intención que debe permanecer dentro de AGENTS.md. Envuélvala en marcadores y trate el bloque como propiedad humana:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Los comentarios de Markdown no se renderizan en la página, y el agente sigue leyéndolos. Ahora haga que la supervivencia del bloque sea verificable, de modo que un proceso que lo elimine falle de forma notoria. Ejecute esto en CI (integración continua) en cada pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff no imprime nada y sale con código 0 cuando el bloque no ha sido modificado. Cualquier salida significa que el proceso reescribió texto propiedad de los humanos, por lo que una persona debe aprobarlo o revertirlo. La verificación se mantiene sin que nadie tenga que recordarlo.

Regenerar en el pull request, no mediante un temporizador

El mejor momento para actualizar un documento es el commit que lo deja obsoleto. Incluya la ejecución de DOX en el mismo pull request que el cambio estructural; así, el diff será lo suficientemente pequeño como para poder leerlo.

Una comprobación bloqueante que lo garantiza:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Ajuste las rutas a su repositorio. La ventaja es que falla en la rama, donde la corrección es sencilla, y falla por un motivo sobre el cual un revisor puede actuar.

Una programación es el respaldo, no el mecanismo. Una tarea semanal detecta lo que nadie notó en una rama: archivos movidos por un rebase, un paquete eliminado en un merge, un documento que menciona un directorio que ya no existe. Ejecútela en una máquina pequeña, la misma que podría usar para ejecutar un agente de programación en un VPS, y haga que abra un pull request en lugar de enviar cambios directamente a main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Ese comentario es un marcador de posición a propósito. Cada agente tiene su propia CLI (interfaz de línea de comandos) y su propio flag no interactivo; un comando copiado de una página web que no coincide con su versión fallará dentro de cron, donde nadie verá el error. Rellénelo y ejecute el script manualmente una vez antes de programarlo. El || exit 0 también es importante: git commit termina con un código distinto de cero con nothing to commit, working tree clean cuando el árbol ya está actualizado, y bajo set -e eso reportaría una ejecución correcta como un fallo.

Cada ejecución consume tokens, ya que "Leer antes de editar" hace que el agente lea toda la cadena en cada tarea. Ese es el compromiso, y vale la pena vigilarlo si ya está contabilizando el coste de lo que ejecuta su agente.

Monorepos: muchos contratos, un índice

Un archivo AGENTS.md raíz en un repositorio con cuarenta paquetes genera una diferencia de regeneración que nadie lee y un documento que, en su mayor parte, es irrelevante para lo que el agente esté haciendo en ese momento. La respuesta de dox es el Índice de DOX hijo: la raíz contiene las reglas de todo el repositorio y apunta a sus hijos, y cada límite duradero posee su propio archivo. La forma de estructurar ese árbol y qué herramientas leen archivos anidados se explica en archivos AGENTS.md anidados para monorepos.

Lo que cambia dox es la superficie de revisión. Una solicitud de extracción (pull request) que afecte a packages/api debería producir una diferencia en la documentación dentro de packages/api y en ningún otro lugar:

git diff --stat -- '*AGENTS.md'

Si ese comando lista seis archivos para un cambio en un solo paquete, el árbol es incorrecto. O bien los límites son demasiado amplios, o una regla que pertenece a la raíz se copió en cada hijo. dox indica la solución directamente: las reglas generales van en los documentos padres, los detalles concretos van en los documentos hijos. Las reglas duplicadas son las que provocan que una revisión rutinaria lo reescriba todo. Si las mismas reglas se aplican genuinamente a través de repositorios separados, ese es un problema distinto, y compartir habilidades de agente entre repositorios es la herramienta más adecuada para ello.

Revise el diff como si fuera código

Es fácil aprobar un diff de documentación generada sin leerlo, lo cual provoca que se publique un archivo incorrecto. Léalo con la misma sospecha que aplicaría a código generado y busque cuatro elementos:

• Un comando que el archivo mencione ahora, el cual debe ejecutar usted mismo antes de realizar el merge. Las instrucciones de compilación inventadas son el fallo más común.
• Una línea eliminada que contenía una intención. Las adiciones son triviales. Las eliminaciones son donde ocurre la pérdida de información.
• Una ruta absoluta, un nombre de host, una URL interna o cualquier elemento con formato de credencial.
• Una entrada de inventario para algo que ya no existe, lo cual ls resuelve en un segundo.

Luego, verifique el tamaño con wc -l AGENTS.md. Un archivo raíz que supere las doscientas líneas es una señal para dividirlo, ya que el valor total de la cadena reside en que el agente lea la parte pequeña relevante en lugar de todo el contenido.

Cuando algo falla

El paso eliminó su bloque de intención. La comprobación diff anterior imprime las líneas eliminadas. Restaure el archivo desde el punto de ramificación con git restore --source=origin/main AGENTS.md y, a continuación, vuelva a ejecutar el paso con una instrucción más precisa que nombre las secciones que puede modificar.

Ambas ramas se regeneraron. Obtiene CONFLICT (content): Merge conflict in AGENTS.md y marcadores de conflicto <<<<<<< HEAD dentro del archivo. No edite los marcadores manualmente. El archivo es generado, por lo que la resolución correcta es realizar un nuevo paso sobre el árbol fusionado.

El agente ignora el archivo por completo. Compruebe qué nombre de archivo lee realmente su herramienta. Si lee uno diferente, apunte al mismo contenido con ln -s AGENTS.md CLAUDE.md y confirme el enlace simbólico; así mantendrá una única fuente en lugar de dos documentos que divergen.

El árbol generó nodos secundarios sin indexar. Compare la salida de find . -name AGENTS.md con las entradas del índice en los documentos principales. Un nodo secundario que no menciona ningún índice es un nodo que el agente puede pasar por alto.

Cuándo un generador es innecesario

Un paquete, un comando de prueba, dos personas que conocen el repositorio: escriba las veinte líneas a mano. Un archivo AGENTS.md de veinte líneas no se degrada lo suficiente como para justificar un árbol, un índice, una comprobación de CI y una tarea semanal. Vuelva a leerlo cuando cambie la compilación. Ese es todo el coste de mantenimiento, y es menor que el coste de la maquinaria necesaria para gestionarlo.

Vale la pena pagar el coste de dox cuando el repositorio tiene límites que nadie puede retener en su cabeza: varios paquetes con reglas diferentes, o colaboradores que llegan sin el contexto previo. El valor no reside en el texto generado. El valor reside en que la documentación se convierte en algo que puede hacer fallar una pull request, que es la única razón por la que cualquier archivo en un repositorio se mantiene actualizado.

FAQ

¿Necesito instalar algo para usar dox?

No. dox es un único archivo Markdown, con licencia MIT, y a fecha de 11 de agosto de 2026 el repositorio no distribuye ningún paquete ni versiones (releases). Copie su contenido en el archivo AGENTS.md de su proyecto y su agente de programación seguirá las reglas definidas allí. Fije el commit que copió, f34ec7ad1055d3393887e5a2670e8cb7320c9165 en el momento de escribir esto, e inclúyalo en su mensaje de commit para poder identificar más tarde bajo qué versión de las reglas se construyó su árbol.

¿Cómo evito que una regeneración borre mis reglas escritas a mano?

Mantenga la intención y el inventario separados. El razonamiento duradero debe ir en un documento independiente, y todo lo que deba permanecer dentro de AGENTS.md debe incluirse en un bloque marcado. Luego, verifique el bloque en su CI: extráigalo de la rama y de origin/main con sed, compare ambos con diff y haga que la compilación falle ante cualquier diferencia. De esta forma, una persona aprueba o revierte el cambio, en lugar de que pase desapercibido dentro de un diff extenso.

¿Con qué frecuencia debo regenerar AGENTS.md?

En la solicitud de extracción (pull request) que lo hace incorrecto. Un cambio estructural y su documentación pertenecen al mismo diff, ya que es el único momento en que alguien tiene el contexto necesario para revisar ambos. Una ejecución programada semanal sirve como respaldo para desviaciones que hayan pasado desapercibidas en una rama, y debería abrir una solicitud de extracción en lugar de realizar un commit directamente en main.

¿Deben los comandos de compilación residir en el AGENTS.md raíz o en uno secundario?

En el documento más cercano que los gestione. Las reglas generales del repositorio y el índice secundario residen en la raíz. Un comando que se aplica a un paquete específico reside en el AGENTS.md de ese paquete. dox resuelve los conflictos por proximidad: el documento más cercano controla los detalles locales, y ningún documento secundario puede debilitar una regla del padre. Copiar el mismo comando en cada hijo es lo que provoca que una ejecución rutinaria reescriba todo el árbol.

¿Vale la pena usar dox en un repositorio pequeño?

Normalmente no. Un paquete con un comando de prueba y un AGENTS.md de veinte líneas se degrada lentamente, y puede corregirlo en el minuto siguiente a detectarlo. dox compensa su coste cuando el repositorio tiene varios límites con reglas diferentes, o colaboradores que carecen de los antecedentes necesarios, ya que en ese caso la cadena de documentos realiza un trabajo que ninguna persona por sí sola está haciendo.