Comment écrire un fichier AGENTS.md pour les agents de code

Un fichier AGENTS.md est un simple fichier Markdown placé à la racine de ton dépôt, qui explique aux agents de code comment travailler sur le projet : quelles commandes lancer, où se trouve le code et à quoi ne pas toucher. Il n’a aucune section obligatoire. Garde-le court, rends chaque règle vérifiable et confirme que chaque agent le charge.

Ce guide couvre ce qu’il faut y mettre, un modèle, la façon dont Claude Code et Gemini CLI trouvent le fichier, et un test rapide. Les mêmes étapes s’appliquent quand tu lances des agents depuis ton téléphone avec Mono by Reunified.

1. Décide ce qui a sa place dans le fichier

Le site agents.md le présente comme un README pour les agents. Mets-y les informations dont chaque session a besoin, et laisse de côté tout ce que l’agent peut apprendre en lisant le code.

Dans un monorepo, tu peux ajouter un AGENTS.md dans chaque package. Le fichier le plus proche l’emporte, et une instruction directe dans ta conversation prime sur lui.

2. Pars d’un modèle court

Voici un exemple fictif pour « tidy-recipes », une application web TypeScript qui utilise pnpm :

# AGENTS.md

## Overview
TypeScript web app for saving recipes. Components live in src/components.

## Setup
- `pnpm install`

## Test and lint
- `pnpm test` and `pnpm lint`

## Code style
- TypeScript only. One component per file.

## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.

## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.

N’indique que des commandes que tu as déjà lancées dans ce dépôt. L’agent fera confiance à une commande erronée.

3. Écris des règles qu’un agent peut vérifier

Une bonne règle te permet de vérifier après coup si l’agent l’a suivie.

Formule les limites en règles « jamais » et « demander d’abord », une par ligne.

4. Fais-le lire par Claude Code et Gemini CLI

Le site agents.md cite Codex, Gemini CLI, opencode et d’autres agents qui prennent en charge ce format, mais certains demandent d’abord un réglage.

Par défaut, les versions récentes de Claude Code ne lisent AGENTS.md que s’il n’y a ni CLAUDE.md, ni .claude/CLAUDE.md, ni CLAUDE.local.md dans le dossier de travail ou l’un de ses dossiers parents (voir sa documentation sur la mémoire). Si tu as l’un de ces fichiers ou une version plus ancienne, importe AGENTS.md depuis CLAUDE.md. Le projet tidy-recipes a un ancien CLAUDE.md : ajoute donc cette ligne tout en haut et garde en dessous les notes propres à Claude :

@AGENTS.md

Prefer small commits.

Démarre une nouvelle session, lance /context et vérifie que CLAUDE.md apparaît parmi les fichiers de mémoire (« Memory files »). Sans CLAUDE.md, /memory affiche à la place le chemin d’AGENTS.md.

Gemini CLI lit GEMINI.md par défaut. Pour ajouter AGENTS.md, mets ceci dans le fichier .gemini/settings.json du projet (voir sa documentation sur GEMINI.md) :

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Démarre une nouvelle session, puis lance /memory show pour voir ce qui a été chargé. Pour les autres agents, consulte leur documentation.

5. Teste le fichier avec une petite tâche

Dans une nouvelle session, confie cette tâche à l’agent :

Liste d’abord les règles du projet que tu as chargées et le fichier d’où vient chacune. Change ensuite le texte du bouton « Save recipe » en « Save » dans src/components/SaveButton.tsx. Ne change rien d’autre.

Compare le résultat avec le fichier :

• Il a cité AGENTS.md (ou CLAUDE.md avec l’import).
• Il a lancé pnpm test et pnpm lint et a donné les résultats.
• Il n’a pas touché à db/migrations/ et n’a ajouté aucune dépendance.
• Il a listé les fichiers qu’il a modifiés.

Vérifie toi-même la modification avec git diff (voir vérifier les modifications de code de l’IA). Si l’agent ne parvient pas à citer une règle, le fichier n’a probablement pas été chargé : reviens à l’étape 4. S’il a cité une règle sans l’appliquer, rends-la plus concrète.

6. Garde-le court et à jour

La documentation de Claude Code conseille de garder CLAUDE.md sous les 200 lignes, car les fichiers plus longs consomment plus de contexte et sont suivis moins fidèlement. Vise la même chose pour AGENTS.md. Le guide sur la fenêtre de contexte explique ce qui se passe quand le contexte se remplit.

Mets le fichier à jour quand un agent répète une erreur, et supprime les commandes périmées et les règles contradictoires. Versionne-le avec le projet et relis ses modifications comme du code.

Le fichier guide l’agent ; il n’impose rien. Pour bloquer une action, utilise les réglages d’autorisation de l’agent ou refuse sa demande (voir le guide sur les permissions des outils).

Dans Mono, l’agent démarre dans le dossier de travail du projet sur ton ordinateur, là où il cherche ces fichiers. Tu peux ouvrir AGENTS.md, CLAUDE.md ou .gemini/settings.json dans l’éditeur de Mono, depuis ton téléphone aussi, et les modifications s’enregistrent automatiquement. Pour créer le fichier, demande-le à l’agent ou ouvre un terminal depuis la carte du projet. Mono ne vérifie pas le fichier et ne décide pas de celui que l’agent charge. Mono n’est pas encore disponible, mais tu peux rejoindre la liste d’attente.