Le problème : pourquoi l’IA plante toujours au même endroit

Tu utilises Cursor, Windsurf ou Claude Code sur un vrai projet. L’IA te pond un bloc de code, tu colles, tu lances — build cassé, tests rouges, dépendances installées n’importe où. Le problème n’est pas l’intelligence du modèle : il ne connaît tout simplement pas les « règles non écrites » de ton projet.

AGENTS.md, c’est un fichier Markdown à la racine du repo, écrit pour l’IA. Tu lui dis comment build, comment tester, quel style de code respecter. README.md, lui, s’adresse aux humains : présentation du projet, guide de contribution, histoire de la boîte. Quand l’IA lit ça, c’est comme un nouveau collaborateur qui reçoit la plaquette marketing le jour de son arrivée et qui doit coder dans l’heure — il sait ce que fait la boîte, mais il ignore la commande de build, la commande de test, la config ESLint. Résultat : tu répètes en boucle « utilise pnpm pas npm », « les tests sont dans packages/web », « oublie pas le lint ». Cent fois, mille fois, le projet reste bordélique.

Sur une mission freelance, la perte est directe. Tu prends un contrat Next.js + Prisma, tu accélères avec Cursor, et l’IA lance npm install — ta config pnpm workspace est morte. Elle ne sait pas où vit ton schéma Prisma, les migrations qu’elle génère explosent. Le client pressure pour la livraison, tu passes trois heures à débugger du code généré par l’IA. Le tarif ne compense plus la douleur.

Trois plantages classiques quand l’IA ignore les règles du projet : ① Mauvais gestionnaire de paquets (le projet tourne sous pnpm, l’IA tape npm install par défaut), dépendances au mauvais endroit, workspace HS ; ② Tests introuvables (tests dans packages/web, l’IA lance pnpm test à la racine, message « aucun fichier de test ») ; ③ Style incohérent (ESLint + Prettier configurés, l’IA sort du code avec mauvaise indentation et mauvais guillemets, le CI tombe).

L’opportunité : séparer « doc humaine » et « doc machine » pour de bon

Le projet open source AGENTS.md sur GitHub (repo github.com/agentsmd/agents.md, ~24 000 stars au 26-08-2026) règle ce problème. L’idée est bête comme chou : un fichier Markdown à la racine, dédié à l’IA, qui lui dit comment build, tester, formatter.

Ce n’est pas un remplaçant du README, c’est un complément. README sert les contributeurs humains, AGENTS.md sert les agents IA. Chacun son job, zéro interférence.

Le fichier est déjà adopté par des dizaines de milliers de projets open source (chiffre précis à recouper), et confirmé compatible avec VS Code, Cursor, Windsurf, Aider, GitHub Copilot. La communauté signale aussi un support sur OpenAI Codex, Google Jules (⚠️ non vérifié). Si tu ne t’y mets pas maintenant, tu laisses l’IA te parler en dialecte.

Voie 1 : écrire un AGENTS.md minimal à la main

Coût quasi nul. Tu crées le fichier, tu écris trois blocs, c’est prêt.

Prérequis : les exemples ci-dessous utilisent pnpm (plus économe en disque que npm, gère les workspaces monorepo), turbo est l’orchestrateur de tâches monorepo, le flag --filter cible un sous-paquet précis sans toucher au reste du repo.

Bloc 1 « Dev environment tips » : tu dis à l’IA quel gestionnaire de paquets utiliser, comment naviguer entre sous-paquets, comment créer un nouveau module. Exemples tirés du template officiel :

• pnpm dlx turbo run where <project_name> — saute direct dans le bon sous-paquet, fini le ls à l’aveugle
• pnpm install --filter <project_name> — installe les deps d’un seul sous-paquet, le monorepo reste intact
• pnpm create vite@latest <project_name> -- --template react-ts — crée un sous-paquet React + Vite avec TypeScript

L’IA ne devinera jamais ces commandes toute seule. Une fois écrites, elle les exécute.

Bloc 2 « Testing instructions » : tu dis comment lancer les tests, où vit la config CI, quels checks passer avant chaque commit. Le template officiel inclut :

• pnpm turbo run test --filter <project_name> — lance tous les checks d’un sous-paquet
• pnpm vitest run -t "<test name>" — n’exécute qu’un seul test par son nom
• « Fix any test or type errors until the whole suite is green » — pas de sortie tant que tout n’est pas vert
• « Add or update tests for the code you change, even if nobody asked » — la ligne clé. Sans elle, l’IA zappe les tests neuf fois sur dix

Bloc 3 « PR instructions » : format du titre de commit, obligation de passer lint + test. Le template officiel : Title format: [<project_name>] <Title> et « Always run pnpm lint and pnpm test before committing ».

Trois blocs, moins de 50 lignes, et le taux de code généré qui passe du premier coup grimpe nettement (retour communauté, chiffre précis à recouper).

Voie 2 : imbriquer les fichiers dans un gros monorepo

Sur un contrat entreprise avec un repo monorepo (plusieurs projets liés dans un même dépôt Git — front, back, code partagé chacun dans son dossier), un seul AGENTS.md ne suffit pas. AGENTS.md supporte l’imbrication : tu déposes un fichier dédié dans chaque sous-dossier, et l’IA lit automatiquement « le plus proche ».

Mise en pratique : le AGENTS.md racine porte les règles globales (gestionnaire de paquets,流程 CI, sécurité). Ensuite tu poses un fichier dans packages/web/, packages/api/, packages/shared/ avec les commandes spécifiques au sous-paquet, l’entrée des tests, les dépendances spéciales. Le front doit préciser « composants via shadcn, styles via Tailwind, icônes via lucide-react ». Le back doit préciser « migrations Prisma, routes API dans src/routes, auth JWT ».

Quand l’IA travaille dans un sous-dossier, elle charge le AGENTS.md le plus proche, priorité sur la racine. Résultat : dans le même projet, l’assistant front et l’assistant back reçoivent des instructions différentes, zéro mélange.

Voie 3 : en faire ton argumentaire freelance

Le marché du dev IA freelance est devenu un champ de bataille. Tout le monde sait ouvrir Cursor, mais la qualité de livraison varie du tout au tout. Si tu glisses dans ta proposition cette phrase — « ce projet est livré avec un AGENTS.md standard, le développement IA suit les conventions du repo » — tu prends un avantage net sur les concurrents qui se contentent de dire « je code avec l’IA ».

Plan d’action : sur chaque nouveau contrat, tu prends 30 minutes pour lire la structure du projet client, puis tu écris un AGENTS.md sur-mesure. Ce fichier fait partie du livrable — le client pourra maintenir son code avec l’IA plus tard, sans douleur.

Tarifie le service de configuration AGENTS.md séparément (prix à ajuster selon ton marché local) : version basique ~70 € (un fichier + un mini README explicatif), version entreprise ~400 € (imbrication monorepo + règles de sécurité + formation équipe). Livrables : ① fichier AGENTS.md sur-mesure ② 30 jours de support via messagerie ③ une vidéo de formation de 10 minutes. Cible : clients déjà abonnés Cursor/Windsurf mais qui n’arrivent pas à en tirer de la valeur. Pas adapté : clients encore en dev 100 % manuel, sans outil IA installé.

Étude de cas : la moat de compatibilité d’AGENTS.md

AGENTS.md est sous licence MIT (confirmé), maintenu par la communauté (gouvernance exacte à recouper), site officiel agents.md.

La compatibilité, c’est sa vraie moat. Confirmé : VS Code, Cursor, Windsurf, Aider, GitHub Copilot lisent tous AGENTS.md. La communauté signale aussi OpenAI Codex, Claude Code, Gemini CLI, Google Jules (⚠️ non vérifié). Tu écris un fichier, tous les assistants majeurs l’exploitent — pas besoin de config séparée par outil.

Compare avec le reste : .cursorrules de Cursor ne marche que sur Cursor, passe à Windsurf et tout est à refaire. CLAUDE.md de Claude Code ne sert que Claude. Le système d’instructions de GitHub Copilot est encore une autre usine à gaz. Le « write once, run anywhere » d’AGENTS.md explique son adoption éclair.

Coût de migration d’outil : zéro. Aujourd’hui tu es sur Cursor, demain sur Windsurf, AGENTS.md reste tel quel. Pas de réécriture.

Appel à l’action : ce soir, ajoute ton manuel machine

Checklist 5 minutes : ① ouvre la racine de ton projet ② crée AGENTS.md ③ copie le template officiel (github.com/agentsmd/agents.md) ④ remplis trois commandes (build, test, lint) ⑤ observe le résultat à la prochaine session IA.

Si tu bosses en monorepo, ajoute 20 minutes ce soir pour imbriquer un fichier par sous-paquet. Demain matin, tu constates que le code généré n’a plus besoin d’être corrigé en boucle.

AGENTS.md, c’est le meilleur ROI de ta stack IA dev — 30 minutes d’investissement contre plusieurs heures de debug économisées chaque mois.