AGENTS.md a aidé Codex à respecter les règles du projet : 0 violation sur 13 contre 5 sur 13
Une nouvelle session d'agent IA ne se souvient pas des accords de la veille : elle place du SQL directement dans le service, ajoute une colonne cancelled_at en trop et oublie d'inscrire l'action dans le journal d'audit. Le Tech Lead Sergueï Prochtchaev a fait tourner 18 sessions de Codex sur un petit service Python. Sans règles, l'agent violait 5 des 13 décisions du projet ; avec le fichier AGENTS.md ou un skill, 0 sur 13. Il ne faut donc écrire dans ce fichier que ce que l'agent ne ferait pas correctement sans indication.
Traité par IA depuis Habr AI ; édité par Hamidun News
Vous passez une semaine à travailler sur un projet avec un agent IA et vous vous mettez d'accord : le SQL ne se trouve que dans db.py, les erreurs passent par AppError, et l'annulation d'un abonnement modifie le champ status et écrit une entrée dans le journal d'audit. La session se termine.
Le lendemain, une nouvelle session ajoute un rapport de chiffre d'affaires, place conn.execute directement dans le service, crée une colonne cancelled_at et oublie l'audit. Les tests sont verts, le rapport calcule correctement, mais les décisions de l'équipe sont restées dans le chat de la veille.
Le Tech Lead Sergueï Prochtchaev a vérifié sur 18 sessions Codex si le fichier AGENTS.md résout ce problème. Il s'agit d'un simple fichier texte contenant les règles du projet, que l'agent lit au démarrage.
Résultat : sans règles, l'agent a violé 5 des 13 décisions vérifiables ; avec AGENTS.md ou avec un skill, c'est-à-dire un répertoire séparé d'instructions, 0 sur 13.
Ce qu'a montré l'expérience
L'auteur a lancé Codex CLI 0.166.0 sur un petit service Python. La tâche : des abonnements avec un prix en roubles, l'annulation et un rapport de chiffre d'affaires. Chaque session démarrait de zéro, dans un répertoire isolé et sans historique de dialogue. Trois variantes étaient comparées : sans règles, avec AGENTS.md et avec un skill distinct. Chaque variante a été exécutée trois fois.
Dans le premier tour, il y avait huit contrôles. Sans règles, l'agent a enfreint deux d'entre eux à chaque session : il a nommé la colonne monétaire price_kopecks au lieu du nom retenu, et il a placé du SQL dans le service, alors que le fichier users.py voisin accède à la base via db.py. Le reste, il l'a déduit seul du code : stocker l'argent en kopecks, obtenir l'heure via clock, lever AppError.
Dans le second tour, l'auteur a ajouté cinq décisions qui vont à contre-courant des habitudes du modèle. Sans règles, dans les trois sessions, l'agent a créé cancelled_at au lieu de status, n'a pas appelé db.add_audit alors que la fonction existait dans le projet, et il a écrit des codes d'erreur à l'ancienne, du type bad_price. Ce sont les 5 violations sur 13 contrôles. Avec AGENTS.md ou avec le skill, aucune violation. Les tests d'acceptation passaient pourtant dans toutes les variantes, y compris « sans règles ». Les tests ordinaires ne voient pas ce type d'accord, d'où la nécessité d'un script séparé, check.py, qui analyse le code via ast.
Deux indicateurs ont été retirés du décompte, de façon honnête. L'agent a pris l'UUID sans règles, parce que la signature exigeait un identifiant de type chaîne. Le format des logs n'a pas été enfreint, simplement parce qu'il n'y avait pas de logs dans le nouveau module.
Comment rédiger les règles
Étape 1 : pour chaque décision, posez-vous la question de savoir si l'agent agirait ainsi de lui-même. Il ne faut pas deviner, mais le vérifier par une session sans règles. Étape 2 : une règle doit comporter une raison et un signe observable de violation, et l'interdit doit être nommé explicitement (cancelled_at, execute). Si le code existant ne respecte pas la règle, écrivez-le dans la règle elle-même, sinon l'agent prendra pour modèle ce qu'il voit à côté.
Étape 3 : dans le AGENTS.md racine, placez les décisions qui concernent toute modification. Codex lit le fichier global, puis un fichier par répertoire, en suivant le chemin jusqu'au répertoire de travail. La limite totale project_doc_max_bytes est de 32 Kio par défaut. Les règles d'un module gagnent à être conservées dans le AGENTS.md de son répertoire.
Étape 4 : déplacez le contenu long dans un skill, mais référencez-le depuis AGENTS.md. L'agent ne voit de chaque skill que son en-tête et décide lui-même s'il charge le reste. Dans une mesure de Vercel sur la documentation de Next.js 16, le skill n'a pas été invoqué dans 56 % des cas, et la part de tâches résolues est restée au niveau de 53 %, comme sans documentation. Une phrase explicite dans AGENTS.md l'a fait monter à 79 %, et un index condensé directement dans le fichier a donné 100 %. Dans l'expérience de Prochtchaev, la référence était toujours présente, et le skill a été ouvert dans six sessions sur six.
Étape 5 : vérifiez les règles dans un environnement propre. L'auteur possède dans son AGENTS.md global 62 Ko de règles personnelles et une centaine de skills, si bien qu'une variante « sans règles » sans isolation n'en aurait pas été une. Pour la vérification, HOME et CODEX_HOME pointent vers un répertoire temporaire. Étape 6 : transformez les décisions en contrôles automatiques, et testez les contrôles eux-mêmes sur un code volontairement cassé.
Limites et coût
L'expérience est modeste : un seul modèle, une seule tâche, trois sessions par variante. On ne peut pas en tirer la part de violations pour d'autres agents. Le skill n'a pas apporté de gain mesurable par rapport à AGENTS.md ; son avantage est uniquement organisationnel. Le script check.py ne détecte que les formes de violation connues à l'avance : du SQL passé par un autre helper lui échapperait.
Le fichier de contexte a un coût. Selon l'étude « Evaluating AGENTS.md » de l'ETH Zurich, les fichiers générés par le modèle n'ont pas amélioré la part de tâches résolues, tandis que le coût a augmenté de 20 à 23 %. Les fichiers rédigés par des développeurs ont donné +2,4 % de tâches résolues, un résultat statistiquement non significatif, pour une hausse des coûts allant jusqu'à 19 %. Les agents se mettent à explorer et à tester davantage, et cela consomme aussi des tokens.
Conclusion pratique : prenez les trois dernières corrections que vous avez dû apporter à la main après l'agent, formulez-les en règles assorties d'un signe de violation, puis lancez une session dans un environnement propre. Les règles que l'agent enfreint sans le fichier et respecte avec lui constituent votre AGENTS.md. Le reste ne fait qu'ajouter des dépenses. La prise en charge des formats dépend de l'outil : Claude Code lit CLAUDE.md, Gemini CLI lit par défaut GEMINI.md, il convient donc de vérifier la documentation de votre agent.
- 21 nov. 2026Почему с ИИ-агентами софт остаётся плохим: их гонят на фичи, а не на рефакторинг
- 21 nov. 2026Claude Code a retrouvé en une semaine les ancêtres de l'auteur jusqu'en 1728 : un généalogiste aurait demandé à partir de 230 000 roubles
- 21 nov. 2026NVIDIA enferme les agents IA dans un bac à sable OpenShell avec quatre niveaux de protection
- 21 nov. 2026Un agent IA a écrit en 40 minutes et pour environ 1 $ un émulateur de PC Windows XP dans un seul fichier HTML
Questions clés sur cet article
Que sait-on sur Ce qu'a montré l'expérience ?
L'auteur a lancé Codex CLI 0.166.0 sur un petit service Python. La tâche : des abonnements avec un prix en roubles, l'annulation et un rapport de chiffre d'affaires. Chaque session démarrait de zéro, dans un répertoire isolé et sans historique de dialogue. Trois variantes étaient comparées : sans règles, avec AGENTS.md et avec un skill distinct. Chaque variante a été exécutée trois fois. Dans le premier tour, il y avait huit contrôles.
Comment rédiger les règles?
Étape 1 : pour chaque décision, posez-vous la question de savoir si l'agent agirait ainsi de lui-même. Il ne faut pas deviner, mais le vérifier par une session sans règles. Étape 2 : une règle doit comporter une raison et un signe observable de violation, et l'interdit doit être nommé explicitement (cancelled_at, execute). Si le code existant ne respecte pas la règle, écrivez-le dans la règle elle-même, sinon l'agent prendra pour modèle ce qu'il voit à côté.
Que sait-on sur Limites et coût ?
L'expérience est modeste : un seul modèle, une seule tâche, trois sessions par variante. On ne peut pas en tirer la part de violations pour d'autres agents. Le skill n'a pas apporté de gain mesurable par rapport à AGENTS.md ; son avantage est uniquement organisationnel. Le script check.py ne détecte que les formes de violation connues à l'avance : du SQL passé par un autre helper lui échapperait. Le fichier de contexte a un coût.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
L'essentiel de l'IA — une fois par semaine
Sept actus qui ont vraiment compté, choisies à la main. Sans bruit ni communiqués.
C'est fait ! Vérifiez votre boîte mail pour la confirmation.