Un fichier AGENTS.md indique à un agent de programmation comment travailler dans un dépôt. Il est chargé dans le contexte à chaque session : chaque ligne ajoutée a donc un coût à chaque tâche et entre en concurrence avec la demande réelle pour capter l’attention de l’agent.

Ce seul constat explique presque tout ce qui suit.

N’écrivez que ce qui ne peut pas être découvert

Si l’agent peut apprendre quelque chose en examinant le dépôt, ne l’écrivez pas. L’arborescence, le framework utilisé et la convention de nommage des fichiers de test sont visibles dans le dépôt et n’ont pas besoin d’être répétés.

Ce qui ne peut pas être découvert relève de l’intention et des contraintes :

  • La commande qui lance les tests, lorsqu’elle n’est pas évidente
  • Les conventions que le code n’applique pas encore partout
  • Ce qui ressemble à un bug, mais est intentionnel
  • Les répertoires qui ne doivent pas être modifiés, et pourquoi

Gardez-le assez court pour être lu en entier

Au-delà d’une centaine de lignes environ, un fichier commence à se comporter comme un document que personne ne lit. Une instruction enfouie à la ligne 180 ne modifie pas le comportement de façon fiable, car elle entre en concurrence avec tout le reste du contexte.

Si votre fichier est déjà devenu trop long, la question utile n’est pas « comment obliger l’agent à le suivre ? », mais « lesquelles de ces lignes ont déjà changé un résultat ? ».

Soyez précis sur les commandes

Des consignes vagues produisent des comportements vagues. Comparez :

Run the tests before committing.

avec :

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

La seconde version évite un échec précis et récurrent. La première ne fait qu’exprimer une intention.

Expliquez la raison, pas seulement la règle

Une règle accompagnée de sa raison reste valable face à une situation inconnue ; une simple interdiction, non. « Ne modifiez pas src/generated/ » invite à faire une exception dès que le modifier directement semble pratique. « Ne modifiez pas src/generated/ : pnpm codegen l’écrase et votre modification disparaîtra » ne laisse pas cette ambiguïté.

Réexaminez-le lorsqu’il ne fonctionne plus

Considérez ce fichier comme quelque chose qui se dégrade avec le temps. Quand l’agent répète un comportement indésirable, cela renseigne sur le fichier, pas seulement sur le modèle. Soit une instruction manque, soit l’instruction existante est noyée sous trois cents lignes qui ne comptent plus.