📜Un seul fichier pour gouverner tous tes agents · maîtrise AGENTS.md

Le moment exact où vous en avez besoin

Le besoin apparaît le jour où votre projet a des règles et où plus d'un cerveau artificiel y passe. Vous utilisez peut-être Claude Code pour construire, un autre outil pour réviser, et de temps en temps vous ouvrez Cursor ou Copilot pour un point précis. Ou bien demain vous changez d'agent pour économiser des crédits. Dans tous ces cas, il existe une connaissance qui ne vit pas dans le code : comment démarrer l'environnement, avec quelle commande lancer les tests, quels dossiers sont sacrés et ne se touchent pas, comment vous voulez que soient rédigés les messages de sauvegarde. Cette connaissance vit aujourd'hui dans votre tête — et chaque nouvel agent part de zéro, sans rien en savoir.

La douleur d'où il naît · le contexte qui s'évapore

La douleur est silencieuse et se paie par mensualités. La session d'aujourd'hui avec votre IA sait parfaitement comment fonctionne votre projet parce que vous le lui avez expliqué pendant des heures. Mais cette connaissance n'est enregistrée nulle part : quand vous fermez la conversation, elle s'évapore. Demain vous ouvrez une nouvelle session — ou vous changez de modèle pour dépenser moins — et vous voilà de nouveau à la case départ, à répéter « souviens-toi que les tests se lancent avec cette commande », « ne touche pas au dossier des paiements », « les commits vont dans ce format ».

Pourquoi cela arrive-t-il ? Parce que chaque agent démarre à l'aveugle : il ne voit que votre code, pas vos règles ni vos habitudes. Et comme chaque outil enregistrait ses instructions à sa façon — Claude dans un fichier, Cursor dans un autre, Copilot dans un autre — vous deviez maintenir la même connaissance écrite trois ou quatre fois. Un chaos qui se désynchronise tout seul : vous changez une règle dans un fichier et vous l'oubliez dans les autres.

Qu'est-ce qu'AGENTS.md ? (en clair)

AGENTS.md est un README pour agents. Tout comme le README de toujours raconte à un humain de quoi parle votre projet, AGENTS.md raconte à n'importe quelle IA de code comment se comporter à l'intérieur. C'est un fichier de texte brut (Markdown) que vous placez à la racine de votre projet, et c'est tout. Sans configuration bizarre, sans code, sans cérémonies.

Ce qui le rend puissant, ce n'est pas le format — c'est qu'il est devenu un standard ouvert que lisent aujourd'hui plus de 25 outils différents : OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Jules, Aider, Zed, Windsurf, Devin, JetBrains Junie, Warp, goose et plus encore. Plus de 60 000 projets open source l'utilisent déjà. Vous écrivez vos règles UNE fois, et elles fonctionnent avec l'IA que vous utilisez aujourd'hui et avec celle que vous utiliserez demain. Vous cessez d'être marié à un seul outil.

L'anatomie réelle · ce qu'il contient

Voici la meilleure nouvelle : il n'y a pas de format rigide à apprendre. AGENTS.md, c'est du Markdown tout ce qu'il y a de normal — des titres avec #, des listes avec des tirets, du texte. Il ne comporte pas cet en-tête technique rempli de deux-points et d'accolades (ce que les programmeurs appellent le YAML frontmatter) : rien de tout ça n'est obligatoire. Vous écrivez en sections avec le nom que vous voulez, et l'agent lit ce que vous y mettez. Point.

Cela dit, il y a cinq blocs que presque tout bon AGENTS.md inclut — parce que ce sont justement la connaissance qui s'évapore entre les sessions. Voyez-les comme les cinq tiroirs du manuel du poste :

L'habitude · écrivez-le une fois, gardez-le vivant

Cette ressource n'est pas de celles qui s'appliquent tous les jours — c'est de celles qui se font bien une fois et se retouchent de temps en temps. La constance ici n'est pas dans la fréquence, mais dans deux moments concrets où vous ne pouvez pas l'oublier :

La nuance que presque personne n'explique · AGENTS.md vs CLAUDE.md vs .cursorrules

C'est là que les gens s'embrouillent, alors soyons clairs. Avant que le standard n'existe, chaque outil a inventé son propre fichier de règles : Claude Code lit un CLAUDE.md, Cursor lisait un .cursorrules, et ainsi chacun. Le problème évident : si vous utilisiez trois outils, vous mainteniez trois fichiers avec la même connaissance, se désynchronisant tout seuls. AGENTS.md est né justement pour en finir avec ce désordre : une seule source de vérité que toutes lisent.

# CLAUDE.md

# Las reglas del proyecto viven en AGENTS.md (fuente única).
# Claude Code las carga con esta línea de importación:

@AGENTS.md

# Debajo, solo lo específico de Claude Code que NO aplica
# a los demás agentes (si es que hay algo).

Quand utiliser lequel ? Facile : AGENTS.md pour tout ce que vous voulez que n'importe quel agent obéisse (95 % de vos règles). Le fichier propre à un outil (CLAUDE.md, .cursorrules) uniquement pour ce qui est exclusif à cet outil — une commande que lui seul comprend, un réglage qui ne sert qu'à lui. En cas de doute, ça va dans AGENTS.md. La règle mentale : écrivez pour tous par défaut ; écrivez pour un seul par exception.

Point & contrepoint · et si la spec dit déjà quoi construire ?

Si vous venez de l'idée d'écrire une spécification avant de construire (le quoi vous voulez construire), AGENTS.md est l'autre moitié de la paire — et ils ne se marchent pas dessus, ils se complètent. La spec gouverne QUOI se construit : la fonctionnalité, l'objectif, le résultat. AGENTS.md gouverne COMMENT se comporte n'importe quel agent pendant qu'il le construit : avec quelles commandes, quelles règles, quoi ne pas toucher. L'une est le plan du bâtiment ; l'autre, les consignes de sécurité du chantier. Vous avez besoin des deux.

Le prompt maître · génère ton AGENTS.md parfait

Voici le raccourci. Vous n'avez pas à écrire le fichier à la main ni à réfléchir à chaque section : vous donnez ce prompt à votre agent de code à l'intérieur de votre projet, et il le rédige pour vous en regardant comment votre code est réellement construit. Vous n'avez qu'à réviser et ajuster. Copiez-le tel quel, remplissez les crochets avec ce que vous savez, et laissez-le travailler :

Je veux créer un fichier AGENTS.md à la racine de mon projet : le « README pour agents » du standard ouvert (agents.md) que lisent les outils d'IA de code. C'est du Markdown brut, SANS en-tête YAML. Guide-moi en langage simple, en supposant que je ne suis pas programmeur.

D'abord, EXPLORE mon projet pour de vrai (examine la structure des dossiers, le package.json ou équivalent, et comment c'est organisé) pour NE rien inventer. Ensuite rédige un AGENTS.md avec ces sections, en Markdown propre :

1. Résumé du projet — 2 ou 3 phrases sur ce que c'est et quelles technologies il utilise (déduis-le du code).
2. Préparer l'environnement — les commandes réelles pour installer et démarrer le projet de zéro.
3. Comment se lancent les tests — la commande exacte des tests et de la vérification des erreurs/types, pour que n'importe quel agent vérifie son travail avant de le donner pour bon.
4. Règles de style — la langue du code et les conventions que tu détectes (guillemets, noms, format).
5. Commits et PR — voici mon format de messages de commit : [décris-le, ou dis-moi si je n'en ai pas et propose-en un bon].
6. Limites · ce qu'on ne touche PAS — marque comme INTOUCHABLES sans permission explicite ces dossiers/fichiers sacrés : [liste ici ce qui est sensible : paiements, secrets, configuration, migrations… ce que tu as]. Précise bien qu'un agent doit S'ARRÊTER et demander avant de les modifier.

Règles pour le rédiger :
- N'affirme que des choses que tu peux vérifier en regardant mon code. Si tu ne sais pas quelque chose, mets un marqueur [À CONFIRMER] au lieu de l'inventer.
- Que ce soit concis et actionnable, pas un roman. Un agent le lit en entier avant de travailler.
- Si mon outil principal a déjà son propre fichier de règles (par exemple CLAUDE.md), NE duplique PAS le contenu : fais que ce fichier importe l'AGENTS.md avec une seule ligne, et laisse-moi AGENTS.md comme source unique de vérité.

À la fin, montre-moi le fichier complet et explique-moi en une phrase ce que tu as mis dans chaque section, pour que je le révise.

Le chemin le plus facile · par chat vs. à la main

Comme dans toute la série, il y a deux façons de faire ça et aucune ne vous oblige à toucher le terminal si vous ne voulez pas :

Si vous prenez le chemin manuel, voici le modèle minimal prêt à copier et à remplir. Changez-le à votre goût : rappelez-vous qu'il n'y a pas de format obligatoire.

# AGENTS.md

## Résumé du projet
[Ce que c'est et avec quoi c'est fait. 2-3 phrases.]

## Préparer l'environnement
[Commandes pour installer et démarrer de zéro.]

## Comment se lancent les tests
- Tests : [commande exacte]
- Vérification des erreurs/types : [commande exacte]
> Lance ça et laisse-le au vert avant de considérer un changement comme terminé.

## Règles de style
[Langue du code, conventions de noms/format.]

## Commits et pull requests
[Ton format de messages de commit. Exemple d'un bon.]

## Limites · NE PAS toucher sans permission
- [Dossier ou fichier sacré 1 — pourquoi il est sensible]
- [Dossier ou fichier sacré 2]
> Devant l'un de ceux-ci : ARRÊTE-toi et demande avant de modifier.

La routine en or · le résumé que vous emportez