Tester AGENTS.md : 5 tests rapides pour ton repo

Introduction — pourquoi tu dois tester ton AGENTS.md maintenant

Les fichiers AGENTS.md et CLAUDE.md ne sont pas des README pour humains : ce sont des briefings opérationnels pour des agents IA. Un fichier mal écrit peut faire plus de mal que de bien — une étude (ETH Zurich, arXiv:2602.11988) a même montré que certains fichiers générés dégradent le taux de réussite des agents.

Plutôt que d’écrire à l’aveugle, fais des tests simples et répétables. Cet article te donne 5 tests rapides (exécutables en ~10 minutes chacun), les métriques à collecter, et une checklist pour intégrer les résultats dans ton workflow CI. Objectif : prouver, par des chiffres, que ton fichier améliore vraiment la productivité des agents.

H2 — Ce que tu veux mesurer (les bonnes métriques)

Avant de lancer les tests, définis ces métriques :

• Taux de réussite (success rate) : % de tâches complétées sans intervention humaine.
• Nombre d’itérations (rounds) : combien de prompts/sous-tâches ont été nécessaires.
• Erreurs bloquantes détectées : exceptions, tests qui cassent, modifications sur fichiers sensibles.
• Temps wall-clock jusqu’à PR candidate (en minutes).
• Coût d’inférence approximatif (tokens ou facturation) si disponible.

Ces métriques te permettent d’avoir un verdict quantifié — pas une impression.

H2 — Préparation rapide (2 min)

1. Choisis un agent et une configuration reproductible (ex : Claude Code local / remote, ou un agent open-source via MCP).
2. Clone une branche propre du repo.
3. Sauvegarde l’état initial (git rev-parse HEAD).
4. Place le fichier AGENTS.md (ou CLAUDE.md) que tu veux tester à la racine.
5. Prépare un dossier test/agent-tests contenant les tâches (issues, prompts, scripts d’exécution).

H2 — Test 1 : Tâche de reproduction de bug (robuste)

Objectif : vérifier si l’agent comprend où chercher et quelles commandes lancer.

Procédure

• Choisis un bug réel ou un ticket simple (ex : “corriger erreur X qui fait échouer le test Y”).
• Lance l’agent en lui donnant la tâche et laisse-le appliquer les étapes qu’il juge nécessaires.
• Stoppe l’expérience quand l’agent produit une PR candidate ou demande une intervention.

Métriques à collecter

• Success rate (a-t-il ouvert une PR candidate qui passe les tests ?)
• Nombre d’itérations
• Modifs sur fichiers sensibles
• Temps jusqu’à PR candidate

Pourquoi ça compte

Si ton AGENTS.md contient les commandes de build/test exactes et le chemin des sources, tu devrais voir une réduction du nombre d’itérations et du temps jusqu’à PR. Si l’agent explore trop de fichiers ou lance des commandes incorrectes, le fichier est trop vague.

H2 — Test 2 : Insertion de fonctionnalité mineure (productivité)

Objectif : mesurer le gain de productivité sur une tâche d’ajout simple (ex : ajouter une prop, modifier un lib utilitaire).

Procédure

• Donne la tâche à l’agent : “Ajoute la validation X dans la fonction Y et écris un test”.
• Laisse l’agent générer le code, les tests et proposer une PR.

Métriques

• Proportion de modifications correctes au premier submit
• Nombre d’itérations
• Résultat du pipeline CI (si disponible)

Résultat attendu

Un AGENTS.md bien ciblé devrait augmenter le taux de bons PRs au premier essai. Mesure l’amélioration relative par rapport à un run sans AGENTS.md.

H2 — Test 3 : Respect des limites (sécurité)

Objectif : vérifier que l’agent n’écrase pas des zones sensibles (migrations, infra, secrets).

Procédure

• Demande à l’agent d’optimiser une partie du code qui touche la base (mais sans accès à prod).
• Observe s’il modifie les chemins listés dans la section “NE PAS TOUCHER” de ton AGENTS.md.

Métriques

• Nombre de modifications sur fichiers listés dans les limites
• Occurrences d’actions interdites

Pourquoi

Un bon AGENTS.md empêche l’agent d’effectuer des actions dangereuses en explicitant les limites et les fichiers hors-scope.

H2 — Test 4 : Test de robustesse multi-agent (interopérabilité)

Objectif : si tu cibles plusieurs agents (Copilot, Claude, Gemini), vérifie la portabilité de ton AGENTS.md.

Procédure

• Lance le même test de fonctionnalité sur 2 agents différents.
• Compare les PRs candidates et les itérations nécessaires.

Métriques

• Variation du taux de réussite entre agents
• Modifications spécifiques à un agent (indiquant du vendor-lock)

H2 — Test 5 : Mesure du coût et du bruit de contexte

Objectif : mesurer l’impact en tokens / coûts et détecter le “bruit”.

Procédure

• Exécute une session pilote enregistrée (log des prompts et des contextes).
• Compare la quantité de token consommée et la longueur des messages système quand AGENTS.md est présent vs absent.

Métriques

• Tokens consommés
• Coût approximatif (si tarif disponible)
• Taux d’instructions ignorées (l’agent fait autre chose que demandé)

Donnée utile (étude ETH Zurich)

L’étude ETH Zurich (arXiv:2602.11988) observe que certains fichiers générés automatiquement peuvent réduire le taux de succès des agents de ~3% et augmenter le coût d’inférence de ~20%. C’est pour ça qu’il faut tester — et réduire le fichier au strict nécessaire.

H2 — Template minimal de benchmark (scripts)

Voici un squelette bash que tu peux réutiliser pour automatiser les runs (adaptable selon ton agent) :

#!/usr/bin/env bash
set -euo pipefail
REPO=/root/repos/nicolasmeridjen.com
BRANCH=blog/test-agents-md-$(date +%s)
mkdir -p /tmp/agent-bench
# Exemple : run agent with task file
# agent-cli run --task-file test/tasks/bug-repro.yaml --output /tmp/agent-bench/run.json
# Puis extraire metrics : jq '.metrics' /tmp/agent-bench/run.json

(Adapte agent-cli à l’outil que tu utilises — Claude Code, multica, agentic CLI, etc.)

H2 — Checkpoint pré-commit & intégration CI

Avant d’ajouter les résultats à ta PR, effectue ces vérifications :

• Le fichier article / rapport de test est ajouté dans docs/agent-bench/ (résultats, logs, run.json).
• Le fichier AGENTS.md est < 200 lignes; privilégie 20–80 lignes.
• Ajoute un test automatisé simple : test/agent-smoke.js qui vérifie que les commandes de build passent.
• Inclure assetsPending: true si tu publies un article (si applicable).

H2 — FAQ rapide

Q : Combien de temps pour ces tests ? R : Chaque test est conçu pour être réalisable en 10–30 minutes selon la vitesse de ton agent et la CI.

Q : Faut-il automatiser tout ça en CI ? R : Oui. Automatiser un run de sanity check (smoke) à chaque PR qui modifie AGENTS.md/CLAUDE.md est la meilleure pratique.

Q : Ces méthodes fonctionnent-elles pour CLAUDE.md ? R : Oui. Les mêmes tests s’appliquent — adapte les checks spécifiques (ex : skills, hooks) pour CLAUDE.md.

H2 — Ce qu’il faut retenir (takeaways actionnables)

• Ne fais pas de AGENTS.md par mimétisme : teste-le.
• Mesure : taux de réussite, itérations, erreurs bloquantes, temps, coût.
• Commence petit : 5 tâches reproductibles et un script d’extraction de métriques.
• Automatiser le smoke test à chaque PR changeant AGENTS.md/CLAUDE.md.
• Si un fichier augmente le bruit (ETH Zurich), coupe-le plutôt que l’allonger.

Références & lectures complémentaires

• Template CLAUDE.md minimal — références internes : /root/.hermes/skills/openclaw-imports/ai-blog-editor/references/claude-md-monorepo-template.md
• Étude ETH Zurich sur le bruit des fichiers contexte — arXiv:2602.11988
• Claude Code best practices — https://code.claude.com/docs/en/best-practices
• Repo claude-mem — https://github.com/thedotmack/claude-mem