Mettre AGENTS.md à jour automatiquement avec dox

Pourquoi votre AGENTS.md est incorrect trois semaines plus tard

Un fichier AGENTS.md devient obsolète, car rien ne le relie au code. Vous le rédigez une fois, manuellement, le jour où le dépôt présente une certaine structure. Ensuite, le test runner change, un package est renommé, un service est supprimé, mais le fichier décrit toujours l’état de juin. Rien n’échoue, car aucune étape du build ne le lit.

L’agent le lit et le considère comme fiable. C’est cela qui vous coûte du temps. Dans un dépôt sans AGENTS.md, un agent de programmation examine son environnement avant d’agir. Dans un dépôt avec un AGENTS.md incorrect, il cesse de vérifier, car il pense déjà avoir la réponse. Il exécute la commande indiquée dans votre fichier, le shell renvoie Missing script: "test", puis l’agent commence à deviner. Souvent, il modifie package.json pour ajouter le script promis par votre documentation. Le fichier obsolète n’a pas simplement échoué en silence. Il a provoqué une modification que vous ne vouliez pas.

dox apporte une réponse à ce problème. Il s’agit d’un ensemble de règles destinées à l’agent. Elles font de la mise à jour de la documentation une partie intégrante de la finalisation du travail. Le fichier est ainsi modifié dans le même commit que le code qui l’a rendu incorrect.

Ce que dox est, et ce qu’il n’est pas

dox est un fichier Markdown unique. Le dépôt est agent0ai/dox, il est sous licence MIT et, au 11 août 2026, l’ensemble du projet tient dans un seul AGENTS.md de 3906 octets, un README, un LICENSE et deux images. Aucun package n’est à installer et aucun runtime n’est nécessaire.

C’est important, car le terme générateur laisse penser qu’un programme analyse votre code. Rien n’analyse votre code. dox est un contrat que votre agent de codage lit : votre agent est le générateur, et dox est le jeu d’instructions qui lui indique quand lire la documentation, quand la réécrire et quelle structure donner à chaque document.

Le fichier comporte dix sections, dont deux assurent l’essentiel du travail. « Read Before Editing » indique à l’agent de parcourir, depuis la racine du dépôt, chaque chemin qu’il prévoit de modifier, puis de lire chaque AGENTS.md présent sur chaque parcours, pendant la session en cours, sans se fier à sa mémoire. « Update After Editing » lui indique que toute modification significative nécessite un passage DOX, c’est-à-dire une étape de mise à jour de la documentation à exécuter avant de considérer la tâche comme terminée. Ce passage met à jour le document propriétaire le plus proche lorsque l’objectif, la structure, le workflow, les permissions ou les préférences utilisateur ont changé.

Le reste définit la structure. Un AGENTS.md enfant suit un ordre de sections par défaut : Purpose, Ownership, Local Contracts, Work Guidance, Verification et Child DOX Index. Le fichier racine contient les règles communes au projet ainsi que le Child DOX Index de niveau supérieur, qui permet à un agent de découvrir les documents enfants. « Closeout » est la checklist que l’agent exécute à la fin d’une tâche : vérifier à nouveau les chemins modifiés par rapport à la chaîne, mettre à jour les documents propriétaires les plus proches, actualiser chaque index concerné, supprimer les contradictions, exécuter la vérification existante et indiquer quels documents il a volontairement laissés inchangés.

Épingler dox sur un seul commit, pas sur main

Le dépôt ne contient ni tags ni releases. Il n’y a donc aucun numéro de version à épingler. Épinglez plutôt le commit. Le fichier AGENTS.md actuel correspond au commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, daté du 1 August 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 doit afficher 3906. Un autre nombre signifie que vous n’avez pas récupéré le fichier décrit dans ce guide. Lisez-le avant de lui faire confiance. Si vous saisissez incorrectement le hash du commit, -f fait arrêter curl avec curl: (22) The requested URL returned error: 404 et n’écrit aucun contenu, puis wc -c affiche 0. Un fichier tronqué est pire qu’un fichier absent, car l’agent applique la moitié d’un contrat sans le savoir.

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

Ce cp s’applique à un dépôt qui ne contient encore aucun AGENTS.md. Si vous en avez déjà un, ne l’écrasez pas. Placez les sections dox au-dessus de votre contenu existant, conservez vos propres règles en dessous, puis relisez le résultat du début à la fin. Deux documents contradictoires produisent un agent qui suit la dernière ligne qu’il a lue.

Demandez ensuite à votre agent d’effectuer le premier passage depuis le dépôt. Le README fournit la formulation exacte :

Initialize DOX tree for this project now.

Cette commande crée les fichiers AGENTS.md enfants et les index qui pointent vers eux. Vérifiez ce qu’elle a fait avant de lui faire confiance :

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

Chaque fichier de cette sortie find doit apparaître quelque part au-dessus dans un Child DOX Index. Un document enfant qui n’est mentionné dans aucun index peut être ignoré par l’agent, car l’index lui permet de trouver les documents qui ne se trouvent pas directement sur le chemin qu’il parcourt.

Ce que dox peut voir et ce qu’il ne peut pas savoir

L’agent qui construit votre arborescence lit le dépôt. Tout ce qui s’y trouve peut donc apparaître dans l’inventaire : l’organisation des répertoires, les manifests de packages et les lockfiles, les scripts dans package.json, Makefile ou pyproject.toml, les fichiers de workflow CI, les Dockerfiles, les points d’entrée et CODEOWNERS si vous en avez un. Un inventaire construit à partir de ces éléments s’auto-maintient réellement. Lorsqu’un package est déplacé, l’exécution suivante déplace la ligne qui le décrit.

Tout ce qui suit doit être indiqué par vos soins, car ces informations ne se trouvent pas dans le dépôt :

• pourquoi une règle existe, ce qui empêche un agent de la supprimer en la considérant comme une complexité inutile
• lequel de deux chemins fonctionnels est pris en charge et lequel doit encore être supprimé
• tout ce qui se trouve en dehors du dépôt, comme l’environnement de staging ou la raison pour laquelle une dépendance est épinglée deux versions en arrière
• ce que vous prévoyez de faire la semaine prochaine, ce qui distingue un fichier à jour d’un fichier utile

dox le sait à son propre sujet. Ses règles indiquent que Work Guidance doit refléter les standards actuels du projet ou les instructions de l’utilisateur et que, s’il n’y en a pas encore, vous devez laisser cette section vide. Verification doit correspondre à un contrôle existant. Si le dépôt ne contient aucun framework de test, cette section reste donc vide jusqu’à ce qu’il y en ait un. Un fichier généré qui invente un standard est pire qu’une section vide, car l’agent appliquera ensuite cette invention.

Conservez l’intention rédigée manuellement en dehors de l’inventaire généré

C’est l’échec qui pousse à abandonner la documentation générée. Vous rédigez un paragraphe expliquant que la file de jobs doit rester utilisée par un seul consommateur. Trois semaines plus tard, un passage réécrit le fichier et votre paragraphe disparaît dans un diff de quarante lignes qui réorganise principalement des noms de fichiers. Personne ne le remarque.

Utilisez deux mécanismes, et utilisez-les tous les deux.

Commencez par déplacer l’intention durable dans un autre fichier. Les décisions de conception et leur justification doivent figurer dans un DESIGN.md rédigé pour l’agent, tandis que les notes destinées aux personnes doivent se trouver là où vous séparez HUMAN.md d’AGENTS.md. AGENTS.md contient alors l’inventaire et les contrats locaux. C’est précisément la partie qui doit changer lorsque le code évolue.

Ensuite, délimitez l’intention qui doit rester dans AGENTS.md. Entourez-la de marqueurs et considérez ce bloc comme géré par les personnes :

## 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 -->

Les commentaires Markdown ne sont pas affichés sur la page, mais l’agent les lit toujours. Rendez maintenant la conservation du bloc vérifiable, afin qu’un passage qui le supprime échoue clairement. Exécutez ceci dans la CI (intégration continue) pour chaque 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 n’affiche rien et se termine avec le code 0 lorsque le bloc n’a pas été modifié. Toute sortie signifie que le passage a réécrit du texte géré par les personnes. Une personne doit alors l’approuver ou l’annuler. Le contrôle reste effectif sans que personne ait besoin d’y penser.

Régénérez sur la pull request, pas selon un calendrier

Le meilleur moment pour actualiser un document est le commit qui le rend incorrect. Placez l’étape DOX dans la même pull request que la modification structurelle. Le diff reste ainsi suffisamment court pour être réellement lu.

Un contrôle bloquant peut l’imposer :

#!/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

Adaptez les chemins à votre dépôt. L’intérêt est que le contrôle échoue sur la branche, là où la correction coûte peu, et pour une raison sur laquelle un reviewer peut agir.

La planification est le plan de secours, pas le mécanisme principal. Une tâche hebdomadaire détecte ce que personne n’a remarqué sur une branche : des fichiers déplacés par un rebase, un paquet supprimé lors d’une fusion ou un document qui référence un répertoire qui n’existe plus. Exécutez-la sur une petite machine, la même que vous pourriez utiliser pour exécuter un agent de programmation sur un VPS, et faites-lui ouvrir une pull request au lieu de pousser sur 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

Ce commentaire est volontairement un placeholder. Chaque agent possède sa propre CLI (command line interface) et son propre flag non interactif. Une commande copiée depuis une page web qui ne correspond pas à votre version échoue dans cron, sans que personne ne voie l’erreur. Complétez-la, puis exécutez le script manuellement une fois avant de planifier son lancement. Le || exit 0 est également important : git commit se termine avec un code différent de zéro avec nothing to commit, working tree clean lorsque l’arborescence est déjà à jour. Avec set -e, cela signalerait alors à tort une exécution réussie comme un échec.

Chaque exécution consomme des tokens, car « Read Before Editing » oblige l’agent à lire toute la chaîne à chaque tâche. C’est le compromis à accepter. Il mérite d’être surveillé si vous calculez déjà le coût des exécutions de votre agent.

Monorepos : plusieurs contrats, un seul index

Un seul fichier AGENTS.md à la racine d’un dépôt contenant quarante paquets produit un diff de régénération que personne ne lit, ainsi qu’un document largement sans rapport avec la tâche actuelle de l’agent. dox répond à ce problème avec l’index Child DOX : la racine contient les règles communes au dépôt et pointe vers ses enfants, tandis que chaque frontière durable possède son propre fichier. La structure de cet arbre et les outils qui lisent réellement les fichiers imbriqués sont décrites dans les fichiers AGENTS.md imbriqués pour les monorepos.

dox modifie la surface de revue. Une pull request qui modifie packages/api doit produire un diff de documentation dans packages/api, et nulle part ailleurs :

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

Si cette commande liste six fichiers pour une modification limitée à un seul paquet, l’arborescence est incorrecte. Les frontières sont soit trop larges, soit une règle qui devrait se trouver à la racine a été copiée dans chaque enfant. dox indique directement la correction : les règles générales vont dans les documents parents, les détails concrets dans les documents enfants. Ce sont les règles dupliquées qui obligent une passe courante à tout réécrire. Si les mêmes règles s’appliquent réellement à plusieurs dépôts distincts, le problème est différent ; partager des compétences d’agent entre dépôts est alors l’outil le plus adapté.

Relisez le diff comme du code

Un diff de documentation généré peut être approuvé facilement sans être lu. C’est ainsi qu’un mauvais fichier est publié. Lisez-le avec la même attention que du code généré et recherchez quatre éléments.

• une commande que le fichier mentionne désormais et que vous devez exécuter vous-même avant la fusion. Les instructions de build inventées sont l’erreur la plus fréquente ;
• une ligne supprimée qui exprimait une intention. Les ajouts sont faciles à faire. C’est dans les suppressions que l’information se perd ;
• un chemin absolu, un nom d’hôte, une URL interne ou tout élément qui ressemble à un identifiant d’authentification ;
• une entrée d’inventaire correspondant à un élément qui n’existe plus, ce que ls permet de vérifier en une seconde.

Vérifiez ensuite la taille avec wc -l AGENTS.md. Un fichier racine de plus de 200 lignes indique qu’il faut le scinder, car tout l’intérêt de cette chaîne est que l’agent lise uniquement la partie pertinente, et non l’ensemble du fichier.

Quand cela échoue

Le passage a supprimé votre bloc d’instructions. La vérification diff ci-dessus affiche les lignes supprimées. Restaurez le fichier depuis le point de branchement avec git restore --source=origin/main AGENTS.md, puis relancez le passage avec une instruction plus ciblée qui nomme les sections qu’il peut modifier.

Deux branches ont toutes deux régénéré le fichier. Vous obtenez CONFLICT (content): Merge conflict in AGENTS.md et des marqueurs de conflit <<<<<<< HEAD dans le fichier. Ne modifiez pas ces marqueurs manuellement. Le fichier est généré : la bonne résolution consiste à relancer le passage sur l’arborescence fusionnée.

L’agent ignore complètement le fichier. Vérifiez le nom de fichier réellement lu par votre outil. S’il en lit un autre, faites-le pointer vers le même contenu avec ln -s AGENTS.md CLAUDE.md et validez le lien symbolique, afin de conserver une seule source au lieu de deux documents qui divergent. Si le nom de fichier est déjà correct et que les règles sont toujours ignorées, exécutez le diagnostic pourquoi les agents de programmation ignorent vos instructions avant de réécrire le document.

L’arborescence a de nouveaux enfants que personne n’a indexés. Comparez la sortie de find . -name AGENTS.md avec les entrées d’index des documents parents. Un enfant absent de tous les index est un enfant que l’agent peut parcourir sans le voir.

Quand un générateur est excessif

Un seul paquet, une seule commande de test et deux personnes qui connaissent toutes les deux le dépôt : écrivez les vingt lignes à la main. Un fichier AGENTS.md de vingt lignes ne se dégrade pas assez vite pour justifier un arbre, un index, un contrôle CI et une tâche hebdomadaire. Relisez-le lorsque vous modifiez le build. C’est tout le coût de maintenance, et il est inférieur à celui de l’outillage associé.

dox vaut le coût lorsque le dépôt comporte des limites que personne ne garde entièrement en tête : plusieurs paquets avec des règles différentes, ou des contributeurs qui arrivent sans connaître le contexte. La valeur ne réside pas dans le texte généré. Elle vient du fait que la documentation devient un élément sur lequel une pull request peut échouer. C’est la seule raison pour laquelle un fichier d’un dépôt reste à jour.

FAQ

Dois-je installer quelque chose pour utiliser dox ?

Non. dox est un fichier Markdown sous licence MIT et, au 11 août 2026, le dépôt ne contient aucun package ni aucune release. Vous copiez son contenu dans le fichier AGENTS.md de votre projet, puis votre coding agent applique ces règles. Épinglez le commit copié, f34ec7ad1055d3393887e5a2670e8cb7320c9165 au moment de la rédaction, et indiquez-le dans votre message de commit. Vous pourrez ainsi déterminer plus tard avec quelle version des règles votre arborescence a été construite.

Comment empêcher une régénération de supprimer mes règles écrites manuellement ?

Séparez l’intention de l’inventaire. Placez le raisonnement durable dans un document distinct, et placez dans AGENTS.md tout ce qui doit y rester, à l’intérieur d’un bloc balisé. Vérifiez ensuite ce bloc dans la CI : extrayez-le de la branche et de origin/main avec sed, comparez les deux avec diff, puis faites échouer le build en cas de différence. Une personne approuve alors la modification ou la rétablit, au lieu de la laisser passer inaperçue dans un diff volumineux.

À quelle fréquence dois-je régénérer AGENTS.md ?

Dans la pull request qui le rend incorrect. Une modification structurelle et sa documentation doivent figurer dans le même diff, car c’est le seul moment où quelqu’un dispose du contexte nécessaire pour examiner les deux. Un passage planifié chaque semaine sert de secours pour les dérives qui ont échappé à une branche, et il doit ouvrir une pull request au lieu de commiter directement dans main.

Les commandes de build doivent-elles se trouver dans l’AGENTS.md racine ou dans un fichier enfant ?

Dans le document le plus proche qui en est responsable. Les règles communes au dépôt et l’index enfant se trouvent à la racine. Une commande qui s’applique à un seul package se trouve dans l’AGENTS.md de ce package. dox résout les conflits selon la distance : le document le plus proche contrôle les détails locaux, et aucun enfant ne peut assouplir une règle du parent. Copier la même commande dans chaque enfant est ce qui pousse un passage de routine à réécrire toute l’arborescence.

dox est-il utile pour un petit dépôt ?

En général, non. Un package avec une seule commande de test et un AGENTS.md de vingt lignes évolue lentement, et vous pouvez le corriger dans la minute qui suit sa détection. dox justifie son coût lorsque le dépôt comporte plusieurs frontières soumises à des règles différentes ou des contributeurs qui ne disposent pas du contexte nécessaire. Dans ce cas, la chaîne de documents effectue un travail qu’aucune personne ne réalise seule.