Documenter vos projets pour les agents
30 septembre 2026
Un CLAUDE.md court, un AGENTS.md, un dossier .ai/ quand le projet grossit. L'agent écrit, vous relisez. Voici comment le mettre en place, et comment le tenir à jour.
Dans Je n'écris pas la documentation, je raconte pourquoi chacun de mes projets porte maintenant son propre manuel, écrit par l'agent et relu par moi, et ce que ça évite en production.
Voici comment mettre ça en place sur les vôtres.
Vous n'écrivez rien : l'agent écrit, vous relisez.
Étape 1 : un CLAUDE.md court à la racine
C'est le fichier que l'agent lit au début de chaque session, avant même votre première phrase.
Si vous travaillez avec un agent depuis quelques mois, vous en avez sans doute déjà un. Ouvrez-le. S'il n'existe pas, la commande /init de Claude Code lit le projet et l'écrit pour vous. Avec un autre agent, demandez-lui la même chose en clair.
Ce qu'il doit contenir :
- ce que fait le projet, en trois lignes
- la stack, et les commandes pour le lancer, le construire, le tester
- les conventions à respecter
- ce qu'on ne touche pas, nommé explicitement
- où trouver le reste
Puis regardez sa longueur. Il est chargé en entier au début de chaque session. Plus il est long, plus il coûte en contexte à chaque conversation, et moins chaque consigne a de poids au milieu des autres. Chez nous, il fait entre trente et soixante-dix lignes. Le vôtre en fait trois cents ? C'est l'étape 3.
Pour la relecture, trois questions. Est-ce que c'est juste. Est-ce que ça dit bien ce qu'on ne touche pas. Est-ce qu'il n'a pas inventé une règle que vous n'avez jamais suivie.
Étape 2 : un AGENTS.md à côté
CLAUDE.md, c'est la convention de Claude Code. Codex lit AGENTS.md, et d'autres outils liront autre chose demain.
Pas besoin de maintenir deux contenus. Chez nous, AGENTS.md fait trois lignes :
# Mon projet
See [CLAUDE.md](./CLAUDE.md).Un seul contenu à tenir, et le projet reste lisible le jour où vous changez d'agent.
Étape 3 : le dossier .ai/ quand le projet grossit
Pour un petit projet, CLAUDE.md suffit. Ne créez pas la suite par principe.
Passez à la suite le jour où CLAUDE.md ne peut plus tout porter sans gonfler. Un serveur, des règles de sécurité, un design system, des tâches planifiées, et c'est plié. On sort alors le détail dans un dossier à part, un fichier par sujet, et CLAUDE.md redevient un sommaire qui renvoie vers lui. L'agent ne lit que ce dont la tâche a besoin.
Le squelette qu'on utilise, le même sur vingt-huit projets :
mon-projet/
├── CLAUDE.md le sommaire, lu à chaque session
├── AGENTS.md le même contrat, pour un autre agent
└── .ai/
├── AGENTS.md point d'entrée, ordre de lecture
├── ARCHITECTURE.md stack, dossiers, dépendances
├── DOMAIN.md de quoi parle le projet
├── FLOWS.md les parcours principaux, bout en bout
├── RULES.md ce qui est interdit, et pourquoi
├── TASKS.md les procédures pas à pas
└── TOOLS.md outils, accès, connecteursDOMAIN.md, c'est le domaine au sens du métier, pas du nom de domaine. Il dit de quoi parle le projet, avec ses mots à lui. Pour notre radio : les émissions, les épisodes, les animateurs, et les états par lesquels passe un épisode, de programmé à diffusé puis publié. Pour un site vitrine : ses pages et ses sections. Pour une boutique Shopify : ses collections, ses fiches produit, et ce que veulent dire section, bloc ou template dans son thème. Sans lui, l'agent confond deux notions qui se ressemblent dans le code.
TASKS.md contient les procédures pour ce qui revient souvent : ajouter un champ, créer un point d'API, faire tourner une clé d'accès. Étape par étape, avec ce qu'on peut modifier sans risque et ce qu'on ne touche pas sans vérifier.
Le squelette est fixe, la liste ne l'est pas. On ajoute une pièce quand un projet a une contrainte que les autres n'ont pas : un INFRA.md là où il y a des serveurs, un AUTOMATIONS.md là où tournent des tâches planifiées, un BRAND.md sur un projet client.
Le point d'entrée, .ai/AGENTS.md, dit à l'agent quoi lire, et dans quel ordre, selon la tâche. « Tu touches au player ? Lis l'architecture, puis les flux, puis les règles. » Sans lui, l'agent lit tout ou ne lit rien.
Le prompt pour le mettre en place
Vous n'écrivez pas ces fichiers non plus. Ouvrez une session dans le projet, remplissez les trois lignes du haut, collez le reste tel quel. Il marche sur un projet vierge comme sur un projet qui a déjà un CLAUDE.md trop long : l'agent part de l'existant, propose un plan, attend votre accord, puis écrit.
Tu vas écrire, ou remettre en ordre, le manuel de ce projet : les
instructions que les agents liront avant d'y travailler. Un humain
doit pouvoir le lire aussi.
CE QU'EST LE PROJET : [EN UNE PHRASE]
CE QUI NE DOIT JAMAIS CASSER : [LA PROD, UN FLUX, DES DONNÉES]
CE QUE JE RÉEXPLIQUE LE PLUS SOUVENT : [UNE PROCÉDURE, UNE CONVENTION]
LA LOGIQUE
CLAUDE.md est chargé en entier au début de chaque session. Il reste
un sommaire, une page au plus : ce que fait le projet, la stack, les
commandes, ce qu'on ne touche pas, et où lire le détail.
Le détail va dans un dossier .ai/, un fichier par sujet, pour qu'un
agent ne lise que ce dont sa tâche a besoin :
- .ai/AGENTS.md : le point d'entrée. Quoi lire, dans quel ordre,
selon la tâche.
- ARCHITECTURE.md : la stack, les dossiers, ce qui dépend de quoi.
- DOMAIN.md : de quoi parle le projet, au sens métier : ses notions,
ce qu'elles veulent dire ici, leurs états.
- FLOWS.md : les parcours importants, de bout en bout.
- RULES.md : ce qui est interdit ou risqué, et pourquoi.
- TASKS.md : les procédures pas à pas pour ce qui revient souvent.
- TOOLS.md : les outils, commandes, accès et connecteurs utilisés.
Un fichier de plus seulement pour une contrainte propre au projet :
INFRA.md s'il y a des serveurs, AUTOMATIONS.md s'il y a des tâches
planifiées.
AGENTS.md, à la racine, renvoie simplement à CLAUDE.md, pour les
autres agents.
AVANT D'ÉCRIRE
S'il existe déjà un CLAUDE.md, un README ou une doc, lis-les en
premier : c'est de la matière, ne l'écrase pas. Lis ensuite le code,
la config, les scripts et l'historique git. Puis pose-moi jusqu'à
cinq questions, une par une, seulement celles dont la réponse
changerait ce que tu vas écrire.
LE PLAN, PUIS L'ÉCRITURE
Propose d'abord le plan : quels fichiers tu crées, et ce que tu
déplaces d'un CLAUDE.md existant vers .ai/. Attends mon accord.
Ensuite écris. Ne crée que les fichiers dont tu as vraiment le
contenu.
RÈGLES
Décris ce que tu as lu, pas ce qui serait souhaitable.
Nomme ce qu'on ne touche pas, et pourquoi.
Écris aussi ce qui n'est pas ce qu'il paraît : un dossier qui a
l'air d'être la source et n'en est pas une, un script dangereux.
Écris dans la langue de la doc existante. S'il n'y en a pas,
demande-moi.
Quand une information te manque, écris [À COMPLÉTER] et continue.
N'invente aucune règle que le code ne montre pas.
POUR FINIR
Liste les points dont tu n'es pas sûr, pour que je les relise en
premier.Relisez d'abord les points qu'il signale lui-même, puis tout ce qui touche à ce qui ne doit jamais casser.
Dans le manuel de l'infrastructure de notre radio, une ligne dit qu'un dossier du serveur n'est pas la source de vérité : c'est un cache des vingt-quatre prochaines heures, et un fichier absent n'est pas un fichier perdu. Sans elle, un agent qui ne trouve pas un épisode conclut à une perte de données.
Tenir à jour
Un manuel décrit le projet à un moment donné. Le projet bouge, le manuel non. Un manuel faux est plus dangereux qu'un manuel absent, parce que l'agent le croit.
Deux habitudes suffisent.
Quand vous changez quelque chose que le manuel décrit, une commande, une règle, une procédure, demandez à l'agent de le mettre à jour dans la foulée. Il vient de faire le changement, il sait exactement quoi corriger.
Et de temps en temps, posez la question telle quelle :
Est-ce que le manuel de ce projet est encore à jour ? Compare-le au
code et à l'historique git récent. Dis-moi ce qui a changé et ce
qu'il faut corriger, puis attends mon accord avant de modifier.Il rend une liste, vous validez, il corrige. Au bout de la troisième fois, demandez-lui d'en faire une skill : il connaît le processus, il vient de le suivre trois fois avec vous.
Ce qu'il ne faut pas faire
Ne l'écrivez pas vous-même. Vous décririez le projet de mémoire, l'agent le décrit à partir du code.
Ne remplissez pas les sept fichiers d'un coup sur un projet qui n'en a pas besoin. Un CLAUDE.md court et bien relu vaut mieux qu'un dossier .ai/ à moitié vide.
Et ne gardez pas une ligne fausse en vous disant que vous la corrigerez plus tard. Corrigez-la, ou supprimez-la.
Pour commencer, ouvrez le CLAUDE.md du projet sur lequel vous travaillez le plus. S'il est long, collez le prompt : l'agent vous proposera de le découper. S'il n'existe pas, lancez /init. La prochaine fois que vous ouvrirez une session sur ce projet, vous verrez ce que vous n'avez plus besoin de réexpliquer.