Patterns AGENTS.md : ce qui change vraiment le comportement des agents

Mon premier AGENTS.md était un copier-coller de 200 lignes du guide de style de notre équipe. Il contenait les conventions de nommage, les checklists de revue de code, les procédures de déploiement et les principes d’architecture. L’agent en a ignoré l’essentiel. Non pas parce que les instructions étaient fausses, mais parce qu’il s’agissait de documentation, pas d’instructions opérationnelles.

Un fichier AGENTS.md doit contenir des instructions centrées sur les commandes, avec les invocations exactes, des sections organisées par tâche (développement, revue, publication) et des critères explicites de « terminé » que l’agent peut vérifier. Écrivez une politique opérationnelle, pas de la documentation pour humains. Incluez les commandes shell précises, les configurations de linter et les commandes de test que l’agent doit exécuter. Évitez les paragraphes rédigés, les directives ambiguës du type « soyez prudent » et les priorités contradictoires sans ordre explicite. AGENTS.md est un standard ouvert adopté par plus de 60 000 projets et fonctionne avec Codex, Cursor, Copilot et d’autres outils agentiques.

Cette distinction compte davantage que n’importe quel pattern de cet article. AGENTS.md est une politique opérationnelle destinée à un agent d’IA, pas un README destiné à des humains. L’agent n’a pas besoin de comprendre pourquoi vous utilisez les commits conventionnels. Il a besoin de connaître la commande exacte à exécuter et de savoir à quoi ressemble « terminé ».

TL;DR

La plupart des problèmes d’AGENTS.md viennent d’une documentation écrite pour des humains au lieu d’instructions opérationnelles pour un agent. Les fichiers efficaces sont centrés sur les commandes (invocations exactes, pas descriptions), organisés par tâche (sections développement, revue, publication) et dotés d’une définition de clôture (critères explicites de « terminé »). Les anti-patterns systématiquement ignorés : paragraphes rédigés, directives ambiguës (« soyez prudent ») et priorités contradictoires. AGENTS.md est un standard ouvert adopté par plus de 60 000 projets ¹ et fonctionne avec Codex, Cursor, Copilot, Amp, Devin Desktop et bien d’autres ².

Contexte : AGENTS.md est géré par l’Agentic AI Foundation, sous l’égide de la Linux Foundation ³, dont les membres platine comptent Anthropic, Google, Microsoft et OpenAI. Cet article traite des patterns concrets. Pour la configuration propre à Codex, consultez le guide Codex. Pour l’équivalent chez Claude Code (CLAUDE.md), consultez le guide Claude Code.

Ce qui passe à la trappe

Ces patterns ne produisent aucun changement observable dans le comportement de l’agent. J’ai identifié chacun d’eux en exécutant des tâches identiques avec puis sans l’instruction concernée, avant de comparer la justesse d’exécution sur plus de 10 essais par pattern. L’analyse par GitHub de plus de 2 500 dépôts contenant un fichier AGENTS.md aboutit à la même conclusion : « La plupart des fichiers d’agent échouent parce qu’ils sont trop vagues » ¹¹. Les patterns ci-dessous n’ont amélioré la justesse d’aucune manière mesurable.

Paragraphes rédigés sans commandes

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

L’agent lit ce texte, le retient comme une vague préférence, puis écrit du code sans tests. Aucune instruction actionnable, aucune commande à exécuter, aucun seuil à atteindre, aucune définition de « correctement testé ».

Directives ambiguës

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

« Prudent » n’est pas une contrainte. « Lorsque c’est possible » n’est pas une condition de déclenchement. « Proprement » n’est pas une spécification de comportement. Cela se lit comme des conseils d’humain à humain, pas comme des instructions destinées à un agent. Comparez avec ce qui fonctionne : « Exécute alembic check avant d’appliquer les migrations. Interromps si le chemin de downgrade est absent. »

Priorités contradictoires

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

L’agent ne peut pas satisfaire ces quatre exigences simultanément. Lorsque des instructions entrent en conflit sans ordre de priorité explicite, le modèle saute les étapes de vérification et se précipite vers la génération de code. Des travaux présentés à ICLR 2026 (Ambig-SWE) montrent que « sans sollicitation explicite, les modèles n’interagissent quasiment jamais, même face à des entrées très fortement sous-spécifiées » – les agents avancent en silence plutôt que de poser des questions de clarification – tandis que les inciter à interagir améliore les performances jusqu’à 74 % sur les tâches sous-spécifiées ¹². Corrigez les instructions contradictoires en numérotant les priorités : « Priorité 1 : les tests passent. Priorité 2 : moins de 5 minutes. Priorité 3 : livrer vite. »

Guides de style sans mécanisme d’application

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

Tant que vous n’indiquez pas la commande de lint exacte qui applique le style (ruff check --select D ou pylint --rcfile=.pylintrc), l’agent ne dispose d’aucun mécanisme pour vérifier sa propre conformité. Le principe est universel : une instruction sans commande de vérification est une suggestion, pas une règle.

Ce qui fonctionne

Ces patterns produisent des changements constants et mesurables dans le comportement de l’agent.

Instructions centrées sur les commandes

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Une commande est sans ambiguïté. L’agent sait exactement quoi exécuter, quels arguments passer, et peut vérifier la réussite en consultant le code de sortie. Chaque instruction de votre AGENTS.md doit répondre à cette question : « Quelle commande prouve que c’est bien fait ? »

Définitions de clôture

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Des définitions de clôture explicites éliminent le mode de défaillance le plus courant : l’agent annonce « terminé » sans avoir rien vérifié. Quand « terminé » se définit par des codes de sortie précis, l’agent lance chaque contrôle avant de déclarer la tâche achevée. Sans cette définition, « terminé » signifie « je crois avoir fini », source fréquente de bugs introduits par les agents.

Sections organisées par tâche

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

Un fichier organisé par tâche permet à l’agent de sélectionner les instructions pertinentes selon ce qu’il est en train de faire. Une liste plate l’oblige à analyser chaque instruction sans tenir compte du contexte. Le préfixe « Lorsque… » correspond directement à la façon dont l’agent raisonne sur le contexte de la tâche.

Règles d’escalade

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

Sans règles d’escalade, un agent bloqué se rabat sur des contournements de plus en plus créatifs : suppression de fichiers de verrouillage, contournement des contrôles, échecs passés sous silence. La liste des « jamais » compte autant que les chemins d’escalade. Interdire explicitement les solutions de secours destructrices évite les pires modes de défaillance.

Portée par répertoire dans un monorepo

AGENTS.md gère la portée hiérarchique en tant que fonctionnalité centrale de la spécification ². Les fichiers les plus proches du répertoire de travail l’emportent :

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

Les instructions de la racine se concatènent avec celles des fichiers plus profonds. Codex parcourt le chemin depuis la racine du projet jusqu’au répertoire de travail courant, en combinant chaque AGENTS.md rencontré ⁴ ; la spécification, elle, définit la priorité du fichier le plus proche, si bien que d’autres outils peuvent résoudre la hiérarchie autrement ². Le dépôt codex d’OpenAI applique ce principe : il livre un AGENTS.md imbriqué sous celui de la racine ⁴.

Dans Codex, vous pouvez également utiliser un fichier AGENTS.override.md à n’importe quel niveau pour remplacer (et non compléter) les instructions parentes ⁴. Ce mécanisme de surcharge est propre à Codex, les autres outils ne l’implémentent pas.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

Quand recourir à la surcharge : gels de version, mode incident, ou tout service dont les contraintes de sécurité priment sur les règles générales du projet.

Compatibilité entre outils

AGENTS.md est adopté par plus de 60 000 projets ¹ et reconnu par tous les grands outils de développement assisté par IA. Voici comment un même fichier se comporte selon les écosystèmes (tableau vérifié en août 2026) :

Si votre équipe utilise plusieurs outils : faites d’AGENTS.md la source canonique. Ajoutez des fichiers propres à chaque outil (CLAUDE.md, .cursorrules) qui importent ou reflètent les sections pertinentes. N’entretenez pas de jeux d’instructions parallèles qui finiront par diverger.

Ordre de rédaction : par quoi commencer

Si vous partez de zéro, ajoutez les sections dans cet ordre de priorité. Chaque couche s’appuie sur la précédente :

1. Commandes de build et de test : l’agent en a besoin avant de pouvoir faire quoi que ce soit d’utile
2. Définition de « terminé » : évite les fausses complétions du type « je crois avoir fini »
3. Règles d’escalade : évitent les contournements destructeurs quand l’agent se retrouve bloqué
4. Sections organisées par tâche : réduisent l’analyse d’instructions hors sujet à chaque tâche
5. Portée par répertoire (monorepos uniquement) : isole les instructions propres à chaque service

Laissez de côté les préférences de style tant que les quatre premiers points ne fonctionnent pas. La plupart des fichiers AGENTS.md échouent parce qu’ils commencent par des conseils de style et n’arrivent jamais aux commandes.

Tester votre AGENTS.md

Vérifiez que l’agent lit et suit réellement vos instructions :

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

Le test décisif : demandez à l’agent d’expliquer vos commandes de build. S’il ne parvient pas à les restituer mot pour mot, c’est que les instructions ne sont pas lues, ou trop verbeuses pour tenir en contexte. Les fichiers AGENTS.md trop longs sont tronqués par la fenêtre de contexte : gardez chaque section sous les 50 lignes et placez les instructions les plus critiques en tête.

FAQ

Quelle doit être la longueur d’un fichier AGENTS.md ?

Ma règle empirique : chaque section sous les 50 lignes et le fichier entier sous les 150. Le principe sous-jacent vient des recommandations de Marmelab sur l’agent experience – le fichier doit rester « court et précis » puisque les agents le lisent au début de chaque session ¹³ ; les nombres de lignes, eux, sont de moi et non d’eux. Codex applique par défaut une limite de 32 Kio (project_doc_max_bytes) ⁴. Les fichiers longs sont tronqués par la fenêtre de contexte : placez donc en tête les instructions les plus critiques, les commandes et les définitions de clôture, avant les préférences de style.

AGENTS.md remplace-t-il les fichiers d’instructions propres à chaque outil ?

Non. AGENTS.md coexiste avec CLAUDE.md, .cursor/rules et les autres fichiers propres à un outil. Faites d’AGENTS.md la source canonique, puis reflétez-en les sections pertinentes dans les fichiers spécifiques. Les patterns d’AGENTS.md (centrés sur les commandes, avec définition de clôture) fonctionnent dans n’importe quel fichier d’instructions, quel que soit l’outil.

Que faire si l’agent ignore mon AGENTS.md ?

Testez en demandant à l’agent d’expliquer vos commandes de build. S’il ne parvient pas à les restituer mot pour mot, le fichier est soit trop verbeux (le contenu est chassé du contexte), soit trop vague (l’agent n’en tire aucune instruction actionnable), soit tout simplement introuvable (vérifiez son emplacement et la documentation de l’outil). L’analyse par GitHub de plus de 2 500 dépôts a montré que la plupart des fichiers d’agent échouent parce qu’ils sont trop vagues ¹¹.

À retenir

Pour un développeur seul :

• Remplacez la prose par des commandes. Chaque instruction doit être vérifiable en exécutant quelque chose.
• Définissez la clôture explicitement. « Terminé » désigne des codes de sortie précis, pas une impression.
• Testez votre AGENTS.md en demandant à l’agent de le réciter. Ce qu’il ne sait pas réciter, il ne le suivra pas.

Pour une équipe :

• Faites d’AGENTS.md l’unique source de vérité. Reflétez-le vers les fichiers propres à chaque outil plutôt que d’entretenir des copies parallèles.
• Organisez par tâche (développement, revue, publication), pas par catégorie (style, tests, déploiement).
• Incluez des règles d’escalade. Sans elles, un agent bloqué improvise d’une manière qui ne vous plaira pas.
• Délimitez la portée par répertoire dans les monorepos. Les règles propres à un service ne doivent pas polluer les instructions globales.

Références