Patterns AGENTS.md : ce qui change réellement le comportement des agents

Mon premier AGENTS.md était un copier-coller de 200 lignes du guide de style de notre équipe. Il incluait des conventions de nommage, des checklists de revue de code, des procédures de déploiement et des principes architecturaux. L’agent en a ignoré la majeure partie. Non pas parce que les instructions étaient fausses — mais parce que c’était de la documentation, pas des opérations.

Cette distinction compte plus que n’importe quel pattern spécifique de cet article. AGENTS.md est une politique opérationnelle pour un agent IA, pas un README pour les 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 à quoi ressemble « terminé ».

TL;DR

La plupart des problèmes d’AGENTS.md viennent du fait qu’on écrit de la documentation humaine au lieu d’opérations pour agents. Les fichiers efficaces sont orientés commandes (invocations exactes, pas des descriptions), organisés par tâches (sections codage, revue, publication) et définis par des critères de clôture (critères explicites de « terminé »). Les anti-patterns systématiquement ignorés : paragraphes en prose, 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, Windsurf et d’autres ².

Contexte : AGENTS.md est gouverné par l’Agentic AI Foundation sous la Linux Foundation ³, avec des membres platinum incluant Anthropic, Google, Microsoft et OpenAI. Cet article couvre les patterns pratiques. Pour la configuration spécifique à Codex, consultez le guide Codex. Pour l’équivalent de Claude Code (CLAUDE.md), consultez le guide Claude Code.

Ce qui est ignoré

Ces patterns ne produisent de manière fiable aucun changement observable dans le comportement de l’agent. J’ai identifié chacun d’entre eux en exécutant des tâches identiques avec et sans l’instruction en question, puis en comparant la précision d’achèvement des tâches sur plus de 10 exécutions par pattern. L’analyse de GitHub portant sur plus de 2 500 dépôts avec des fichiers AGENTS.md est arrivée à la même conclusion : « La plupart des fichiers d’agents échouent parce qu’ils sont trop vagues — pas à cause de limitations techniques » ¹¹. Les patterns ci-dessous n’ont amélioré la précision d’aucune manière mesurable.

Paragraphes en prose 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 cela, le représente comme une préférence vague et procède à l’écriture de code sans tests. Il n’y a pas d’instruction actionnable — pas de commande à exécuter, pas de seuil à atteindre, pas de 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 possible » n’est pas une condition de déclenchement. « Élégamment » n’est pas une spécification de comportement. Cela se lit comme des conseils entre humains, pas comme des instructions pour un agent. Comparez avec ce qui fonctionne : « Exécutez alembic check avant d’appliquer les migrations. Annulez si le chemin de rétrogradation est manquant. »

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 les quatre simultanément. Lorsque les instructions sont 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. Une recherche de l’ICLR 2026 (AMBIG-SWE) a révélé que les agents « adoptent par défaut un comportement non interactif sans encouragement explicite » — procédant silencieusement plutôt que de poser des questions de clarification, ce qui a fait chuter les taux de résolution de 48,8 % à 28 % ¹². Corrigez les instructions conflictuelles en numérotant les priorités : « Priorité 1 : les tests passent. Priorité 2 : moins de 5 minutes. Priorité 3 : livrer rapidement. »

Guides de style sans enforcement

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

À moins d’inclure la commande de linting exacte qui applique le style (ruff check --select D ou pylint --rcfile=.pylintrc), l’agent n’a aucun mécanisme pour vérifier sa propre conformité. Le pattern ici est universel : les instructions sans commandes de vérification sont des suggestions, pas des règles.

Ce qui fonctionne

Ces patterns produisent des changements cohérents et mesurables dans le comportement de l’agent.

Instructions orientées 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`

Les commandes sont sans ambiguïté. L’agent sait exactement quoi exécuter, quels arguments passer, et peut vérifier le succès en contrôlant le code de sortie. Chaque instruction dans votre AGENTS.md devrait répondre à la question : « Quelle commande prouve que cela a été fait correctement ? »

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`

Les définitions de clôture explicites éliminent le mode de défaillance le plus courant : l’agent rapporte « terminé » sans vérification. Quand « terminé » est défini comme des codes de sortie spécifiques, l’agent exécute chaque vérification avant de signaler la complétion. Sans cette définition, « terminé » signifie « je pense que j’ai terminé » — une source courante de bugs introduits par l’agent.

Sections organisées par tâches

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

Les fichiers organisés par tâches permettent à l’agent de sélectionner les instructions pertinentes en fonction de ce qu’il est en train de faire. Les listes plates forcent l’agent à analyser chaque instruction quel que soit le contexte. Le préfixe « When… » 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, les agents recourent par défaut à des contournements de plus en plus créatifs lorsqu’ils sont bloqués — supprimer des fichiers de verrouillage, contourner des vérifications, ou ignorer silencieusement des échecs. La liste « Never » est aussi importante que les chemins d’escalade. Interdire explicitement les patterns de récupération destructeurs prévient les pires modes de défaillance.

Portée par répertoire pour les monorepos

AGENTS.md prend en charge la portée hiérarchique comme fonctionnalité centrale de la spécification ². Les fichiers les plus proches du répertoire de travail ont la priorité :

/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 au niveau racine se concatènent avec les fichiers plus profonds. Les outils parcourent le chemin depuis la racine du projet jusqu’au répertoire de travail actuel, combinant chaque AGENTS.md trouvé le long du chemin ⁴. Le propre dépôt Codex d’OpenAI utilise 88 fichiers AGENTS.md séparés pour son monorepo — un par service et package ⁴.

Avec Codex, vous pouvez également utiliser AGENTS.override.md à n’importe quel niveau pour remplacer (et non étendre) les instructions parentes ⁴. Le mécanisme d’override est spécifique à 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 utiliser l’override : gel de version, mode incident, ou tout service avec des contraintes de sécurité qui remplacent les valeurs par défaut du projet.

Compatibilité multi-outils

AGENTS.md est adopté par plus de 60 000 projets ¹ et reconnu par tous les principaux outils de codage IA. Voici comment le même fichier se comporte à travers les écosystèmes :

Si votre équipe utilise plusieurs outils : rédigez AGENTS.md comme source canonique. Ajoutez des fichiers spécifiques aux outils (CLAUDE.md, .cursorrules) qui importent ou reflètent les sections pertinentes. Ne maintenez pas des ensembles d’instructions parallèles qui divergent.

Ordre de rédaction : quoi ajouter en premier

Si vous rédigez un AGENTS.md 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é » — empêche les fausses complétions de type « je pense que j’ai terminé »
3. Règles d’escalade — empêche les contournements destructeurs quand l’agent est bloqué
4. Sections organisées par tâches — réduit l’analyse d’instructions non pertinentes par tâche
5. Portée par répertoire (monorepos uniquement) — garde les instructions de service isolées

Ignorez 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 sans jamais arriver 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 peut pas les reproduire mot pour mot, les instructions ne sont pas lues ou sont trop verbeuses pour être retenues dans le contexte. Les fichiers AGENTS.md longs sont tronqués par les fenêtres de contexte — gardez chaque section sous 50 lignes et placez les instructions les plus critiques en premier.

FAQ

Quelle longueur devrait avoir un fichier AGENTS.md ?

Gardez chaque section sous 50 lignes et le fichier total sous 150 lignes ¹³. Codex impose une limite par défaut de 32 Kio (project_doc_max_bytes) ⁴. Les fichiers longs sont tronqués par les fenêtres de contexte, donc placez les instructions les plus critiques en premier — commandes et définitions de clôture avant les préférences de style.

Est-ce qu’AGENTS.md remplace les fichiers d’instructions spécifiques aux outils ?

Non. AGENTS.md fonctionne aux côtés de CLAUDE.md, .cursor/rules et d’autres fichiers spécifiques aux outils. Rédigez AGENTS.md comme source canonique, puis reflétez les sections pertinentes dans les fichiers spécifiques aux outils. Les patterns d’AGENTS.md (orientés commandes, définis par des critères 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 peut pas les reproduire mot pour mot, le fichier est soit trop verbeux (contenu poussé hors du contexte), soit trop vague (l’agent ne peut pas extraire d’instructions actionnables), soit non découvert (vérifiez l’emplacement du fichier et la documentation de l’outil). L’analyse de GitHub portant sur 2 500 dépôts a révélé que c’est le manque de précision — et non les limitations techniques — qui cause la plupart des échecs ¹¹.

Points clés à retenir

Pour les développeurs individuels :

• Remplacez la prose par des commandes. Chaque instruction devrait être vérifiable en exécutant quelque chose.
• Définissez la clôture explicitement. « Terminé » signifie des codes de sortie spécifiques, pas des impressions.
• Testez votre AGENTS.md en demandant à l’agent de le réciter. Ce qu’il ne peut pas réciter, il ne le suivra pas.

Pour les équipes :

• Utilisez AGENTS.md comme source unique de vérité. Reflétez-le dans les fichiers spécifiques aux outils, ne maintenez pas de copies parallèles.
• Organisez par tâche (codage, revue, publication), pas par catégorie (style, tests, déploiement).
• Incluez des règles d’escalade. Sans elles, les agents bloqués improvisent de manières qui ne vous plairont pas.
• Définissez la portée par répertoire dans les monorepos. Les règles spécifiques aux services ne devraient pas polluer les instructions globales.

Références