AGENTS.md bien fait : un gain de 25 % de correction — ou une baisse de 30 %

Augment Code a mené une étude systématique sur les fichiers AGENTS.md dans leur monorepo. Les meilleurs fichiers ont donné à leur agent de codage un bond de qualité équivalent à une mise à niveau de Haiku à Opus ; les pires ont rendu les résultats pires que sans fichier AGENTS.md du tout. Le même fichier a amélioré best_practices de 25% sur un correctif de bogue de routine et a fait chuter completeness de 30% sur une tâche de fonctionnalité complexe dans le même module. Voici ce qui fonctionne.

Comment ils ont mesuré

Ils ont utilisé AuggieBench, une suite d'évaluation interne. Ils ont commencé avec des PR de haute qualité provenant d'un grand dépôt, reflétant les tâches typiques des agents au quotidien, configuré l'environnement et l'invite, et demandé à l'agent de reproduire la PR. Ils ont comparé les résultats avec la PR de référence (la version qui a été approuvée après examen par plusieurs ingénieurs seniors). Les PR devaient être contenues dans un seul module ou application, et le périmètre devait être celui où un fichier AGENTS.md pourrait raisonnablement aider. Chaque tâche a été exécutée deux fois — avec et sans le fichier.

Ce qui fonctionne

1. Divulgation progressive > Couverture complète

Couvrez les cas courants et les workflows à un niveau élevé ; repoussez les détails dans des fichiers de référence que l'agent peut charger à la demande. Gardez la portée de chaque référence claire. Les fichiers de 100 à 150 lignes avec une poignée de documents de référence ciblés ont apporté des améliorations de 10 à 15% sur les métriques dans les modules de taille moyenne (~100 fichiers principaux). Au-delà de cette longueur, les gains se sont inversés.

2. Flux de travail procéduraux

Un flux de travail numéroté en plusieurs étapes peut faire passer l'agent de l'échec à la réussite. Exemple : un flux de travail en six étapes pour déployer une nouvelle intégration. Les fichiers de liaison manquants sont passés de 40% à 10%, l'agent a terminé plus rapidement, la correction a augmenté de 25%, l'exhaustivité de 20%. Gardez le fichier principal concis et utilisez des fichiers de référence pour les cas dérivés.

3. Tableaux de décision

Lorsqu'il existe deux ou trois manières raisonnables (par exemple, React Query vs Zustand pour la gestion d'état), forcez le choix en amont avec un tableau. Exemple :

Question → React Query → Zustand
Le serveur est la seule source de données ? ✅
Plusieurs chemins de code modifient cet état ? ✅
Besoin de mises à jour optimistes mélangées avec un état local ? ✅

Les PR dans ce domaine ont obtenu un score 25% plus élevé sur best_practices.

4. Exemples courts de production

Des extraits de 3 à 10 lignes provenant du code de production réel ont amélioré la réutilisation et le respect des modèles. Exemple : modèles copier-coller pour les primitives Redux Toolkit (createSlice avec état initial typé, createAsyncThunk avec gestion des erreurs, useAppSelector typé). code_reuse a augmenté de 20%.

5. Règles spécifiques au domaine

Comptent toujours — le modèle que la plupart des gens associent déjà à AGENTS.md.