SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor · Actualizado 2026-10-22

Actualizar AGENTS.md automáticamente con dox

Evite errores en agentes de IA causados por archivos AGENTS.md obsoletos. Use dox para regenerar la documentación desde el repositorio y gestione los cambios mediante diff.

Por qué su AGENTS.md es incorrecto tres semanas después

Un archivo AGENTS.md queda obsoleto porque nada lo conecta con el código. Se escribe una vez, manualmente, el día en que el repositorio tiene una estructura determinada. Después cambia el ejecutor de pruebas, se cambia el nombre de un paquete, se elimina un servicio y el archivo sigue describiendo el estado de junio. No se produce ningún fallo porque ningún paso de compilación lo lee.

El agente lo lee y lo considera cierto. Esa es la parte que le perjudica. Un repositorio sin AGENTS.md hace que un agente de programación observe lo que hay antes de actuar. Un repositorio con un AGENTS.md incorrecto hace que deje de observar, porque ya tiene una respuesta. Ejecuta el comando que indica el archivo, el shell responde Missing script: "test" y entonces el agente empieza a adivinar. A menudo modifica package.json para añadir el script que prometía la documentación. El archivo obsoleto no falló de forma silenciosa. Provocó una modificación que usted no quería.

dox es una respuesta a ese problema. Es un conjunto de reglas, escrito para el agente, que convierte la actualización de la documentación en parte de la finalización del trabajo, de modo que el archivo cambie en el mismo commit que el código que lo dejó incorrecto.

Qué es dox y qué no es

dox es un único archivo Markdown. El repositorio es agent0ai/dox, usa la licencia MIT y, a fecha de 13 October 2026, todo el proyecto consta de un único AGENTS.md de 3965-byte, un README, un LICENSE y dos imágenes. No hay ningún paquete que instalar ni ningún entorno de ejecución.

Esto es importante porque el término generador sugiere un programa que analiza el código. No se analiza ningún código. dox es un contrato que lee el agente de programación: el 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é estructura debe tener cada documento.

El archivo tiene nueve secciones y dos de ellas realizan el trabajo principal. "Read Before Editing" indica al agente que recorra desde la raíz del repositorio hasta cada ruta que planea modificar y que lea cada AGENTS.md de cada recorrido, en la sesión actual y sin depender de la memoria. "Update After Editing" indica que todo cambio significativo requiere un paso DOX; es decir, un paso de actualización de la documentación que debe ejecutarse antes de considerar terminada la tarea. El paso 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 define la estructura. Un AGENTS.md secundario tiene este orden de secciones predeterminado: Purpose, Ownership, Local Contracts, Work Guidance, Verification y Child DOX Index. El archivo raíz contiene las reglas generales del proyecto y el Child DOX Index de nivel superior, que es la forma en que un agente descubre los documentos secundarios. "Closeout" es la lista de comprobación que el agente ejecuta al final de una tarea: vuelve a comprobar las rutas modificadas frente a la cadena, actualiza los documentos propietarios más cercanos, actualiza todos los índices afectados, elimina las contradicciones, ejecuta la verificación existente e informa de qué documentos dejó sin modificar deliberadamente.

Fija dox en un commit, no en main

El repositorio no tiene etiquetas ni versiones publicadas, por lo que no hay un número de versión que fijar. Fija el commit. El AGENTS.md actual corresponde al commit 765ae4ac02cc884eefcd41a3d0f71941721adb89, fechado el 1 September 2026.

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

wc -c debería mostrar 3965. Un número diferente significa que no descargaste el archivo descrito en esta guía, así que léelo antes de confiar en él. Si escribes mal el hash del commit, -f hace que curl se detenga con curl: (22) The requested URL returned error: 404 y no escriba ningún contenido, y wc -c muestra después 0. Un archivo truncado es peor que no tener archivo, porque el agente sigue la mitad de un contrato sin saberlo.

Si fijaste el commit anterior, f34ec7a de 1 August 2026, comprueba su índice DOX secundario. En esa versión, la sección describe el repositorio de dox: indica que no se necesitan archivos AGENTS.md secundarios y enumera README.md, LICENSE y las dos imágenes como archivos propiedad de root. Copiado en tu proyecto, ese índice describe el repositorio equivocado. La revisión del 1 September reemplazó esa sección por un marcador provisional que indica que el proyecto todavía no está indexado y ordena al agente explorar el repositorio y crear el árbol antes de continuar. Sustituye la sección antigua por tu índice real o por el nuevo marcador provisional.

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

Ese cp corresponde a un repositorio que todavía no tiene AGENTS.md. Si ya tienes uno, no lo sobrescribas. Coloca las secciones de dox encima del contenido existente, conserva tus propias reglas debajo y lee el resultado una vez de principio a fin. Dos documentos que se contradicen producen un agente que sigue la última línea que leyó.

Después, pide al agente, dentro del repositorio, que haga la primera pasada. El README proporciona el texto exacto:

Initialize DOX tree for this project now.

Crea los archivos AGENTS.md secundarios y los índices que apuntan a ellos. Aunque el índice provisional indica al agente que debe hacerlo antes de cualquier otra tarea, pedirlo explícitamente sigue siendo útil: obtienes todo el árbol en un único commit que puedes revisar, en lugar de obtenerlo como efecto secundario de una tarea no relacionada. Comprueba lo que hizo antes de darlo por válido:

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

Todos los archivos de esa salida de find deberían aparecer en algún índice DOX secundario situado encima. Un documento secundario que ningún índice menciona puede quedar fuera de la atención del agente, porque el índice es la forma que tiene de encontrar documentos que no están directamente en la ruta que está recorriendo.

Qué puede ver dox y qué no puede saber

El agente que crea el árbol lee el repositorio, por lo que cualquier elemento del repositorio puede formar parte del inventario: la estructura de directorios, los manifiestos de paquetes y los archivos de bloqueo, los scripts de package.json, Makefile o pyproject.toml, los archivos de flujos de trabajo de CI, los Dockerfiles, los puntos de entrada y CODEOWNERS, si existe. Un inventario creado a partir de esos elementos se mantiene automáticamente. Cuando se mueve un paquete, la siguiente ejecución mueve la línea que lo describe.

Todo lo siguiente debe indicarlo usted, porque no está en el repositorio para que el agente lo lea:

  • por qué existe una regla, ya que eso evita que un agente la elimine por considerarla complejidad innecesaria
  • cuál de dos rutas funcionales es la compatible y cuál está pendiente de eliminación
  • cualquier elemento externo al repositorio, como el entorno de staging o el motivo por el que una dependencia está fijada dos versiones atrás
  • qué tiene previsto hacer la próxima semana, que es la diferencia entre un archivo actualizado y un archivo útil

dox lo sabe sobre sí mismo. Sus propias reglas indican que Work Guidance debe reflejar los estándares actuales del proyecto o las instrucciones del usuario y que, si todavía no existe ninguno, la sección debe dejarse vacía. Verification debe reflejar una comprobación existente, por lo que, si el repositorio no tiene un marco de verificación, esa sección permanece vacía hasta que exista uno. Un archivo generado que inventa un estándar es peor que una sección vacía, porque el agente aplicará después esa 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 a 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 la solicitud de extracción, no mediante un temporizador

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

Una comprobación bloqueante que lo aplique:

#!/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 principal. Una tarea semanal detecta lo que nadie notó en una rama: archivos movidos por un rebase, un paquete eliminado en una fusión o 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 una solicitud de extracción 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 propia bandera para modo no interactivo; un comando copiado de una página web que no coincida 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" obliga al agente a leer 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 un diff de regeneración que nadie lee y un documento que resulta mayormente irrelevante para la tarea que el agente realiza en ese momento. La respuesta de dox es el Índice 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. Cómo estructurar ese árbol y qué herramientas leen archivos anidados se explica en archivos AGENTS.md anidados para monorepos.

Lo que dox cambia es la superficie de revisión. Una solicitud de extracción (pull request) que afecte a packages/api debería producir un diff de 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 reescriba todo. Si las mismas reglas se aplican genuinamente a través de repositorios separados, ese es un problema distinto, y compartir habilidades de agentes 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 al 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 y relevante en lugar de todo el contenido.

Cuando algo falla

El paso eliminó su bloque de intención. La comprobación diff anterior muestra 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 específica que nombre las secciones que puede modificar.

Ambas ramas se regeneraron. Obtendrá 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. Si el nombre de archivo ya es correcto y las reglas siguen sin aplicarse, ejecute el diagnóstico para por qué los agentes de codificación ignoran sus instrucciones antes de volver a escribir el documento.

El árbol generó elementos secundarios que nadie indexó. Compare la salida de find . -name AGENTS.md con las entradas del índice en los documentos principales. Un elemento secundario que no menciona ningún índice es un elemento 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 memoria: varios paquetes con reglas diferentes, o colaboradores que llegan sin los conocimientos previos. El valor no es 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 13 de octubre de 2026, el repositorio no incluye ningún paquete ni ninguna versión publicada. Debe copiar su contenido en el archivo AGENTS.md del proyecto; a partir de ahí, el agente de programación sigue esas reglas. Fije el commit que copió, 765ae4ac02cc884eefcd41a3d0f71941721adb89 en el momento de redactar este texto, e indíquelo en el mensaje del commit para poder identificar más adelante con qué versión de las reglas se creó el árbol.

¿Cómo evito que una regeneración elimine mis reglas escritas manualmente?

Separe la intención del inventario. Coloque el razonamiento que deba conservarse en un documento independiente y todo lo que deba permanecer dentro de AGENTS.md en un bloque delimitado. Después, compruebe el bloque en CI: extráigalo de la rama y de origin/main con sed, compare ambos con diff y haga fallar la compilación si existe cualquier diferencia. Después, una persona aprueba o revierte el cambio, en lugar de que pase inadvertido dentro de un diff grande.

¿Cada cuánto debo regenerar AGENTS.md?

En el pull request que lo deje desactualizado. El cambio estructural y su documentación deben estar en el mismo diff, porque ese es el único momento en que alguien tiene el contexto necesario para revisar ambos. Una ejecución programada semanal sirve como respaldo para detectar cambios que hayan pasado por alto en una rama y debe abrir un pull request en lugar de hacer commit en main.

¿Los comandos de compilación deben estar en el AGENTS.md raíz o en uno secundario?

En el documento más cercano que los gestione. Las reglas de todo el repositorio y el índice de los documentos secundarios se mantienen en la raíz. Un comando que se aplica a un solo paquete debe estar en el AGENTS.md de ese paquete. Cuando los documentos entran en conflicto, dox permite que el documento más cercano controle los detalles del trabajo local. Lo único que ningún documento secundario puede debilitar es el contrato de DOX. Las reglas generales deben estar en los documentos principales y los detalles concretos, en los documentos secundarios. Copiar el mismo comando en cada documento secundario es lo que hace que una ejecución rutinaria reescriba todo el árbol.

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

Normalmente, no. Un paquete con un único 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 no conocen el contexto, porque entonces la cadena de documentos realiza un trabajo que ninguna persona podría realizar por sí sola.

¿Te resultó útil este artículo?