784 façons de dire « non » : ce que les plus gros dépôts mettent dans leur AGENTS.md (2026)
By Surya Pratap
22 août 2026
12 min de lecture
IA et technologie
22 août 2026
12 min de lecture
Le fichier qui vous est facturé à chaque sessionHover to exploreQuelqu'un sur r/AI_Agents a fait le travail que personne n'avait fait : lire le AGENTS.md des 100 dépôts GitHub les plus étoilés qui en possèdent un — environ 27 % du top 1 000, selon son décompte — et recenser ce qu'on y trouve.
Le constat structurel n'a rien de surprenant. Architecture et organisation du dépôt, comment lancer les tests, commandes de build, ce qu'il faut faire et ne pas faire, étiquette des PR, style de code. Les intitulés les plus fréquents : tests, commandes, présentation du projet, architecture. Attendu.
Ce qui surprend, c'est le ton. Environ 90 % de ces fichiers sont écrits à coups de « doit », « toujours », « jamais ». Sur l'ensemble du corpus, on compte 784 puces explicites de type « ne fais pas », et la plupart sont d'une précision presque médico-légale.
La meilleure qu'il ait trouvée :
« N'affirme pas qu'un test interrompu ou expiré est passé. »
Personne n'écrit cette phrase dans l'abstrait. On l'écrit parce qu'un agent l'a fait.
C'est le changement de cadrage à retenir, et il modifie la façon d'écrire le fichier.
Un README s'écrit vers l'extérieur : il explique un projet à quelqu'un qui ne l'a jamais vu. Un AGENTS.md écrit de la même manière produit une présentation soignée qui n'aide personne, parce que l'agent sait déjà lire votre package.json, votre arborescence et le nom de vos fichiers de test.
Ce que l'agent ne peut pas deviner, c'est l'ensemble des choses qu'il a déjà ratées ici. Ces 784 puces sont exactement cela. Lisez attentivement un bon AGENTS.md et vous reconstituez le journal d'incidents : l'agent de quelqu'un a validé un test bloqué, l'agent de quelqu'un a fait un force-push, l'agent de quelqu'un a inventé un script qui n'existe pas, l'agent de quelqu'un a discrètement réécrit une migration.
Why the prohibitive voice actually works
La formulation « doit / toujours / jamais » n'est pas de l'autoritarisme, c'est de la compression. « Mieux vaut lancer la suite complète » est une préférence qu'un agent peut mettre en balance avec d'autres et écarter. « Ne marque jamais un test comme réussi sans avoir vu le code de sortie 0 » est un prédicat vérifiable, sans marge de négociation. Quand le lecteur est un modèle qui optimise le fait de paraître avoir fini, l'ambiguïté n'est pas de la politesse : c'est une faille.
Le plus court de l'échantillon est celui de neovim : 35 mots. Une seule règle, qu'il vaut la peine de reproduire en entier parce qu'elle démontre l'idée mieux que n'importe quel argument :
# AGENTS.md
## AI Disclosure
If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.
C'est tout le fichier. Il encode exactement une chose à laquelle le projet tient et qu'un agent ne pourrait jamais déduire seul — une convention de provenance — et rien d'autre.
Comparez maintenant avec Next.js. Vingt et une sections : structure du code, commandes de build, choix du bundler, tests, écriture des tests, linting et types, « travaillez dans un worktree jetable », état des PR et échecs de CI, sécurité des secrets et des variables d'environnement, workflows économes en contexte, découpage et vérification des tâches, recompiler avant de lancer les tests, anti-patterns de développement. Dont celle-ci, qui parlera à quiconque a relu la PR d'un agent :
« N'ajoute PAS de mentions "Generated with Claude Code" ni de co-auteur aux commits ou aux PR »
Les deux fichiers sont corrects. La variable n'est pas le sérieux, c'est la quantité de trafic d'agents que le dépôt a absorbée et le coût de ses modes de défaillance. Next.js fait passer des agents dans un monorepo avec un bundler en Rust et une matrice de CI qu'il coûte cher de relancer. Neovim a une convention sur laquelle il ne transigera pas.
La bonne longueur pour votre AGENTS.md, c'est le nombre d'erreurs que vos agents ont réellement commises, plus les quelques conventions qu'ils n'auraient jamais pu deviner. Chaque ligne au-delà est quelque chose que vous payez à chaque session, indéfiniment.
Voici ce que les fondateurs manquent systématiquement, et pourquoi « écris-le à fond » est un mauvais conseil.
AGENTS.md est lu au début de chaque session. Chaque phrase qu'il contient est une dépense récurrente, sur chaque tâche, qu'elle soit pertinente ou non pour ce que l'agent fait à cet instant. Un fichier de 400 lignes qui explique votre architecture n'est pas du contexte gratuit : c'est un impôt fixe prélevé sur chaque correction de bug, chaque montée de version, chaque coquille.
C'est toute la contrainte de conception du fichier, et cela explique la réponse de neovim.
Cela explique aussi pourquoi l'écosystème a fait émerger un second mécanisme. Une skill — un SKILL.md dans un dossier — se charge paresseusement : au démarrage, l'agent ne lit que le frontmatter YAML, un nom et une description. Le corps ne se charge que si une tâche correspond vraiment. Dix skills inutilisées ne coûtent presque rien.
Où tracer la limite entre les deux
AGENTS.md. « Ne committe jamais de secrets. » « Lance npm run test:unit -- --coverage, pas la suite complète. » « Les migrations ne font que s'ajouter. »C'est de cette troisième puce que viennent la plupart des fichiers obèses. Si votre AGENTS.md s'ouvre sur trois paragraphes décrivant une arborescence que l'agent va lister dès son premier appel d'outil, vous payez des tokens pour lui apprendre ce qu'il allait découvrir gratuitement.
GitHub a mené une version plus large de cette étude sur plus de 2 500 fichiers agents.md, et les résultats convergent utilement avec l'échantillon Reddit.
pytest -v tests/unit est utilisable. « Lance les tests comme il faut » est ignoré, parce que ce n'est pas une instruction : c'est un vœu.never commit secrets. Si vous n'écrivez rien d'autre cette semaine, écrivez celle-là et la commande de test exacte.Le sujet revient dans toutes les discussions, et la raison mécanique convainc mieux que les anecdotes.
Demandez à un agent de générer votre AGENTS.md et il produira un résumé compétent, bien formaté, de trois cents lignes sur votre dépôt — parce que c'est ce qu'il voit. Il décrira l'arborescence, listera les dépendances et caractérisera la configuration des tests. Autant de choses qu'il aurait pu retrouver à la demande.
Ce qu'il ne peut pas écrire, c'est la partie qui compte : les 784 interdits. Ceux-là viennent de l'avoir vu échouer. Un fichier généré est, presque par construction, l'impôt fixe par session sans aucun des bénéfices.
Je ne connais pas de mesure publique rigoureuse sur ce point — les praticiens rapportent que les fichiers générés donnent de moins bons résultats, et certaines recherches proches des éditeurs vont dans le même sens —, mais tenez cela pour une forte présomption plutôt que pour un chiffre établi. L'argument structurel se suffit à lui-même : un fichier qui ne contient que des faits déductibles coûte des tokens et n'apporte rien.
Une voie médiane utile : laissez l'agent rédiger la section commandes, puisqu'il lit vos scripts avec exactitude et que cette partie est fastidieuse. Écrivez vous-même les limites, une ligne à la fois, au fil des incidents. N'acceptez jamais une présentation d'architecture générée.
AGENTS.md est utilisé par plus de 60 000 projets open source et il est placé sous la garde de l'Agentic AI Foundation, au sein de la Linux Foundation — l'organisme qui héberge déjà MCP et, depuis cette semaine, Agent2Agent. Il est lu par Codex, Cursor, Gemini CLI, Jules, l'agent de code de Copilot, Aider, goose, opencode, Zed, Devin, Windsurf, JetBrains Junie et une longue liste d'autres.
Nous écrivions il y a deux jours que tous les protocoles d'agents sont passés sous le même toit. C'est la même consolidation qui affleure au niveau du fichier, et elle a un bénéfice concret : un fichier, pas cinq.
Le mode de défaillance qu'elle remplace est réel et coûteux. Vous durcissez une limite dans CLAUDE.md, vous oubliez .cursorrules, vous changez d'outil en milieu de semaine, et l'agent qui n'a pas reçu la mise à jour lance la commande destructrice. La dérive des règles entre CLAUDE.md, .cursorrules, .windsurfrules et copilot-instructions.md est la plainte opérationnelle la plus rapportée par les équipes qui font tourner plus d'un agent — certains publient des harnais de synchronisation uniquement pour la régler.
Si vous démarrez maintenant, le bon geste est ennuyeux : faites de AGENTS.md la source de vérité et générez à partir de là les fichiers propres à chaque outil. Un script de dix lignes vaut mieux que sa mémoire.
Deux limites honnêtes, parce que le fichier est parfois survendu.
Ce n'est pas de la mémoire. AGENTS.md est statique. Il ignore que la PR #184 a tranché le débat Postgres contre Mongo il y a trois mois : votre agent reproposera donc Mongo sans état d'âme dans une nouvelle session, et une ligne périmée du type « on utilise X » sera servie avec un aplomb total longtemps après la disparition de X. C'est une lacune réellement non résolue — certains construisent des outils de mémoire des décisions précisément pour cela — et aucune écriture soignée ne la comble.
Il ne contraint rien. Chaque ligne est une suggestion adressée à un système probabiliste. « Ne fais jamais de force-push » dans un fichier Markdown est une demande ; un hook qui bloque git push --force est un contrôle. Confondre les deux est un travers que nous avions traité dans Les agents IA ont besoin de systèmes de permissions, pas de meilleurs prompts, et les douze derniers mois n'ont pas changé la conclusion. AGENTS.md réduit la fréquence de l'erreur. Il n'en supprime pas la possibilité.
Si vous n'avez pas de AGENTS.md, ne partez pas d'un modèle. Partez de ceci, et laissez-le grossir uniquement quand quelque chose tourne mal.
# AGENTS.md
## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.
## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.
## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.
Cela fait environ 150 mots d'instructions réelles. Aucune présentation d'architecture, aucune description de ce que fait le produit, rien que l'agent aurait pu lire dans le dépôt — et cela couvre les quatre limites qui expliquent l'essentiel des dégâts qu'un agent cause à une petite base de code.
Ensuite, traitez-le comme un journal d'incidents. Chaque fois qu'un agent fait quelque chose que vous devez défaire, ajoutez une ligne, à l'impératif, aussi précise que l'erreur l'était. Dans six mois, vous aurez votre propre version de ces 784 interdits, et chacun aura été payé.
Les dépôts les plus étoilés de l'open source ont convergé vers un format qui ne ressemble en rien à de la documentation, parce que le lecteur n'est pas une personne. Il est prohibitif, précis, chargé de commandes et — dans les meilleurs cas — très court.
Pour un fondateur qui livre un MVP avec des agents qui tapent l'essentiel du code, ce fichier est sans doute les 150 lignes les plus rentables du dépôt. C'est aussi le seul fichier du projet que vous payez à chaque tâche, et c'est précisément pourquoi l'envie de le faire exhaustif est l'envie à laquelle il faut résister.
Écrivez les erreurs. Sautez la visite guidée. Laissez-le grandir d'une cicatrice à la fois.
Sources : r/AI_Agents, « What the 100 biggest GitHub repos put in their AGENTS.md files » · Blog GitHub, « How to write a great agents.md: lessons from over 2,500 repositories » · agents.md, sur le format, son adoption et la garde de l'Agentic AI Foundation · AGENTS.md de neovim/neovim · AGENTS.md de vercel/next.js
IdeaToMVP Academy
4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.
