Pourquoi un agent IA a besoin d'une documentation de projet
Ce qu'un agent ignore d'un projet
Dans À l'ombre des jeunes filles en fleurs, le peintre Elstir dit au narrateur qu'« on ne reçoit pas la sagesse, il faut la découvrir soi-même après un trajet que personne ne peut faire pour nous, ne peut nous épargner ». La connaissance d'un projet s'acquiert de la même manière, au fil des décisions prises et des erreurs corrigées. Or un agent IA n'a pas fait ce trajet, et il repart du code à chaque session.
Certes, il lit ce code en quelques secondes et en déduit une bonne part des choix techniques. Il n'y trouve pourtant ni la raison d'une décision ni les pistes essayées puis abandonnées. Faute de ces informations, il refait les mêmes recherches et retombe dans des erreurs que nous avions déjà corrigées.
Il ne suffit pas pour autant de lui transmettre tout l'historique du projet. Un long contexte dégrade en effet les réponses d'un modèle, d'après l'étude citée dans notre article sur la mémoire des agents. L'agent doit en outre y trier lui-même ce qui concerne sa tâche, au détriment du travail demandé.
La documentation d'un projet doit donc répondre à ces deux contraintes à la fois. D'une part, elle apporte à l'agent les décisions et leurs raisons. D'autre part, elle reste assez courte pour ne pas encombrer son contexte. Dès lors qu'elle remplit ces deux conditions, nous la tenons pour le levier principal du développement avec des agents.
D'où vient notre méthode
Nos articles précédents traitaient d'une première source de contexte, la mémoire partagée des agents, installée avec Cognee puis triée par memsift. La documentation en est une seconde, écrite cette fois dans le dépôt lui-même, selon une pratique appelée docs as code.
Notre façon de l'appliquer vient d'abord des projets que nous avons menés. Nous l'avons en effet formalisée après coup, en ne gardant que les règles éprouvées d'un projet à l'autre. Elle s'aligne par ailleurs sur l'état de la recherche en matière de mémoire et de gestion du contexte. Anthropic décrit ainsi une mémoire d'agent organisée en étages, dont l'outil ne charge que le plus petit à chaque session. De même, OpenAI rapporte dans son article sur le harness engineering qu'une information absente du dépôt n'existe pas pour l'agent.
Il en résulte un système de sept fichiers et d'un dossier de guides, dont nous publions les modèles dans agent-docs-starter, un dépôt open source. Le schéma suivant regroupe ces fichiers selon leur rôle dans le projet.
Les documents d'un projet et leur rôle
AGENTS.md et CLAUDE.md, les fichiers qu'un agent IA lit à chaque session
Les premiers documents de ce schéma sont ceux que l'agent reçoit avant toute demande. Comme ils occupent son contexte en permanence, nous les limitons à deux usages, lui dire comment se comporter et lui indiquer où chercher.
Quoi écrire dans AGENTS.md
AGENTS.md reçoit ainsi les corrections de comportement. Devant une erreur de l'agent, nous regardons d'abord sa récurrence, puis son origine. Une erreur qui tient à ses habitudes de travail entre dans le fichier. À l'inverse, une erreur liée au métier du projet relève d'un guide ou d'un document de référence.
Le fichier suit quant à lui le déroulé d'une intervention, de la lecture du code à la fin de la tâche. Dans le plan suivant, tiré du dépôt d'une boutique en ligne, deux consignes sont laissées sous leur titre. Chacune répond à une habitude de l'agent.
AGENTS.md
├── Méthode de travail
│ └── renvoi vers INDEX.md, à lire d'abord
├── Avant de modifier
│ └── Expliquer d'abord l'effet concret
│ pour le produit ou l'exploitation.
├── Sources de vérité
├── Pendant le travail
│ └── Ne pas committer sans demande explicite
│ du responsable du projet.
├── Branches, commit et merge
└── Avant de déclarer terminéUn index pour trouver les documents
Reste à indiquer à l'agent où trouver les autres documents. Nous confions ce rôle à INDEX.md, qui consacre une ligne à chaque document. Chaque ligne dit ce que le document contient et à quel moment le lire.
# Index des documents
- `README.md` : prise en main du projet, pour le client.
- `docs/ARCHITECTURE.md` : décisions techniques et leurs raisons. À lire avant de toucher à la structure.
- `docs/DESIGN-SYSTEM.md` : règles visuelles. À mettre à jour après validation d'une décision, jamais avant.
- `docs/guides/deployment.md` : procédure de mise en ligne. À relire avant chaque déploiement.
- `BACKLOG.md` : chantiers restants.Grâce à cet index, l'agent sait où chercher sans explorer le dépôt par une série de commandes. Il sert aussi à un autre agent qui découvre le projet et dispose ainsi d'une carte dès sa première session.
Les deux outils ne le chargent toutefois pas de la même manière. Dans Claude Code, CLAUDE.md importe AGENTS.md et INDEX.md à chaque session. Codex charge AGENTS.md de lui-même, mais sa documentation ne prévoit pas d'import, et nous y signalons donc l'index par une consigne.
Le coût en contexte
Cet index a cependant un coût, puisqu'il occupe du contexte à chaque session. Nous avions d'abord pensé le laisser dans le README. Or celui d'un de nos sites vitrines compte 155 lignes écrites pour le client, que l'agent aurait dû charger en entier pour en lire six. Nous avons écarté de la même façon le dossier docs, puisque l'index sert à s'orienter depuis la racine. Il est donc devenu un fichier à part, et son coût reste acceptable tant qu'il tient en une ligne par document.
Ce compromis rejoint ce que décrit Anthropic. Dans son article, la part de mémoire injectée à chaque session doit rester petite, car une note fausse s'y répète d'une session à l'autre. OpenAI arrive à la même conclusion après un échec. Son équipe avait d'abord réuni ses instructions dans un seul fichier, qui vieillissait vite. Elle a donc réduit AGENTS.md à une centaine de lignes, utilisées comme une table des matières.
Architecture, design system, guides : où écrire les décisions d'un projet
L'index renvoie d'abord vers les documents qui portent nos décisions. Nous y écrivons chaque décision avec sa raison, et nous acceptons qu'un test la remette en cause. Chacun suit en outre un plan fixe, et s'ouvre sur quelques lignes qui disent ce qu'il couvre.
Une décision et sa raison
ARCHITECTURE.md explique comment le système est construit et pourquoi. Nous y consignons chaque décision structurante pour ce qu'elle est, en plus de la discussion préalable. Tous nos projets ont ce document, y compris un site vitrine. Son plan va du résumé vers le détail.
ARCHITECTURE.md
├── en-tête
│ └── ce que couvre le document,
│ ce qu'il laisse au backlog et aux guides
├── Lecture rapide
│ └── les invariants à préserver
├── Topologie du système
├── Sources de vérité
├── Index des décisions
├── Décisions détaillées
│ └── par domaine
└── Pièges connusUne décision écrite reste pourtant révisable. Pour memsift, notre plugin de mémoire, nous avions d'abord posé les principes et le flux de données. Les tests ont ensuite montré que nos premières questions au modèle de décision manquaient leur cible. Nous avons donc corrigé le fonctionnement, et nous n'avons mis le document à jour qu'une fois ces corrections validées.
Un design system contre les variations
Le design pose un problème voisin. Au fil des itérations, et à mesure que le front grossit, des variations apparaissent d'une page à l'autre. DESIGN-SYSTEM.md sert à les contenir. Nous définissons d'abord les styles dans le code, puis nous en tirons le document à la création de la direction artistique. À chaque ajout, nous vérifions ensuite qu'il respecte ce système. Dans le cas contraire, nous décidons s'il mérite d'y entrer.
Le document garde le même tronc d'un projet à l'autre, et ses règles s'écrivent autant que possible comme des comptes fermés.
DESIGN-SYSTEM.md
├── L'esprit en une phrase
├── Source de vérité technique
├── Typographie
├── Couleurs
├── Espacements
├── Composants
└── ApplicationNous avons en revanche écarté l'idée d'écrire la règle avant le code. Un réglage visuel se juge en effet à l'œil, et nous ne mettons le document à jour qu'après avoir validé le résultat à l'écran.
Les guides d'exploitation et de contrôle
Les opérations qui reviennent ont enfin leurs propres documents, rangés dans le dossier docs/guides. Nous en distinguons deux types. Les procédures d'exploitation décrivent une opération sur le système en production, comme une mise en ligne. Les séries de contrôles listent quant à elles les vérifications à rejouer avant un déploiement ou un merge.
Une procédure suit le plan ci-dessous, tandis qu'une série de contrôles va de la vérification la plus automatisée à la plus manuelle.
docs/guides/deployment.md
├── contexte
│ └── renvoi aux décisions d'architecture
├── Prérequis
├── Procédure
├── Cas particulier
├── Vérification
└── DépannageDans les deux cas, un guide dit comment faire et laisse le pourquoi à l'architecture. Ainsi, le guide de mise en ligne détaille la procédure de déploiement, tandis que le choix de l'hébergement reste expliqué dans ARCHITECTURE.md. Tous ces documents sont par ailleurs écrits en Markdown, le format dans lequel les agents travaillent le mieux.
Qui écrit la documentation, l'agent IA ou l'humain ?
Reste à savoir qui décide de ce qui entre dans ces documents. Un agent écrit au bon endroit dès lors que nous le lui indiquons. Il juge encore mal, en revanche, de ce qui mérite d'être gardé après une décision importante. Une étude de l'ETH Zurich et de LogicStar sur les fichiers d'agent va dans ce sens. Rédigés par un modèle, ces fichiers font légèrement baisser ses résultats, alors que ceux des développeurs les améliorent un peu. Nous gardons donc ce choix en main.
Ce qui mérite d'être écrit
Concrètement, chaque événement du projet nous amène à nous demander de quoi il relève, et la réponse désigne le document à mettre à jour. Le schéma suivant en donne les quatre cas.
Où s'écrit chaque événement du projet
Dans tous ces cas, nous n'écrivons une règle qu'une fois éprouvée. Un principe devient en effet source de vérité lorsqu'il a fait ses preuves. De même, noter les erreurs de l'agent réduit la surface de risque du projet, à condition de ne garder que celles qui reviennent.
Mettre le backlog à jour
La fin d'un échange avec l'agent est le moment le plus concret de cette validation. Nous y mettons à jour BACKLOG.md, qui suit au jour le jour ce qui est fait et ce qui reste à faire. Des tâches y apparaissent d'ailleurs en cours de projet, à la suite d'un test, d'une difficulté ou d'une demande du client. Nous regardons enfin si l'agent a introduit une idée nouvelle, qui peut alors y devenir une tâche.
Ce fichier sert ainsi au pilotage du projet, et nous l'écrivons pour nous plutôt que pour l'agent. Son plan place les tâches en cours et à venir en tête, puis les tâches terminées en fin de fichier.
BACKLOG.md
├── en-tête
│ └── ce que contient le fichier,
│ où se trouvent les contraintes
├── Comment écrire une tâche
├── En cours
├── À venir
└── FaitMémoire d'agent ou documentation
Cette documentation ne remplace pas pour autant la mémoire décrite dans nos articles précédents. La mémoire retient, d'une session à l'autre, ce qui évite de refaire une recherche, et un modèle de décision en fait le tri. La documentation retient pour sa part ce qu'une personne a validé. Elle suit en outre le projet chez le client, qui n'a pas toujours de mémoire installée.
Le choix d'OpenAI
OpenAI a fait un autre choix sur ce point. Son dépôt est organisé d'une façon proche de la nôtre, avec un fichier d'agent court, un document d'architecture et un dossier de documents. Les agents y rédigent toutefois la documentation, que des contrôles automatiques vérifient ensuite. L'échelle explique en partie cet écart, puisque ce dépôt compte environ un million de lignes. Sur un projet livré à un client, une personne peut encore relire ce qui entre dans la documentation.
Reprendre son projet avec son propre agent IA
Tous ces documents servent pendant le projet, et nous les livrons ensuite au client avec le code. Un seul est toutefois écrit pour lui, le README.
Le contenu du README
Le README suit les besoins du client dans l'ordre où ils se présentent. Il décrit d'abord ce que contient le projet, puis son usage au quotidien, et enfin la façon de modifier le code.
README.md
├── présentation
│ └── un paragraphe qui dit ce qu'est le projet
├── Ce que contient ce projet
├── Prise en main
├── Mise en ligne
└── renvoi vers INDEX.mdLes autres documents ne lui sont pas destinés en particulier. Un document lisible par un agent l'est cependant aussi par une personne, et le client peut donc les ouvrir.
Ce que ça change pour le client
Cette dernière partie compte surtout pour un client sans profil technique. Sur l'un de nos sites vitrines, le README le conduit en six étapes de l'ouverture du terminal à l'installation de Claude Code, en une heure environ. Il lui explique ensuite comment formuler une demande à l'agent. Celui-ci trouve alors dans le dépôt les consignes et les décisions dont il a besoin, comme pendant la construction du site.
Le client peut ainsi posséder ce que nous construisons pour lui. Il reste dès lors libre de reprendre son projet sans nous, ou de nous en confier la suite.
Adapter la documentation à la taille du projet
Ce système n'a toutefois pas la même taille d'un projet à l'autre, et chacune de ses règles s'ajuste.
Quand le dépôt grossit
Dans un petit dépôt comme celui de memsift, le document d'architecture peut garder la trace de ce que nous avons essayé. Dans un grand dépôt, la même habitude finirait par noyer l'agent sous le contexte, et nous y renonçons. De même, les guides restent à plat dans leur dossier jusqu'à une dizaine, puis ils passent en sous-dossiers. Enfin, nous n'écrivons une spécification que sur les projets où elle réduit le risque.
Les questions ouvertes
La part du tri que nous gardons en main pourrait elle aussi évoluer. D'après Anthropic, les modèles récents jugent en effet mieux ce qui mérite d'être retenu. Dans ses tests, Claude Sonnet 3.7 a écrit 413 fichiers de mémoire, quand Claude Fable 5 s'en est tenu à une dizaine. OpenAI reconnaît de son côté ne pas savoir encore où le jugement humain pèse le plus. Une partie de nos questions reviendra donc peut-être à l'agent.
Un dépôt open source pour documenter son projet
Les plans présentés dans cet article sont réunis dans agent-docs-starter, un dépôt public sous licence MIT. Le dépôt est lui-même le modèle, puisque ses neuf fichiers sont déjà à leur place et se copient tels quels dans un projet. Un fichier de conventions y explique en outre la raison de chaque règle.
agents-md · ai-agents · claude-code
agent-docs-starter
Les fichiers Markdown pour documenter un projet sur lequel travaillent des agents IA, avec un fichier d'agent, un index et le plan de chaque document.
git clone https://github.com/nualt/agent-docs-starterChez Nualt, chaque projet est livré avec sa documentation
En somme, cette documentation s'écrit pendant le projet et part avec lui. Nous la tenons à jour à chaque décision validée, puis nous la livrons au client avec le code et les accès.
Nous appliquons la même méthode à une boutique en ligne comme à un projet d'IA agentique. Dans chaque cas, le client garde un projet lisible par ses propres agents, qu'il peut faire évoluer avec ou sans nous.
Questions fréquentes
Les réponses aux questions qu’on nous pose le plus souvent sur ce sujet.
Qu'est-ce que le docs as code ?
Le docs as code consiste à écrire la documentation d'un projet en fichiers texte, le plus souvent en Markdown, et à la ranger dans le même dépôt que le code. Elle est ainsi versionnée avec lui et relue dans les mêmes commits.
Quelle est la différence entre AGENTS.md et CLAUDE.md ?
Les deux sont des fichiers de consignes chargés au début d'une session. AGENTS.md est lu par Codex et par d'autres agents, tandis que CLAUDE.md est lu par Claude Code. Dans nos dépôts, CLAUDE.md se contente d'importer AGENTS.md et l'index, ce qui évite de tenir deux jeux de consignes.
Quelle longueur pour un fichier AGENTS.md ?
OpenAI rapporte utiliser un fichier d'une centaine de lignes, qui sert de table des matières. Les nôtres vont d'une dizaine de lignes à un peu plus de cent, selon le projet. Dans tous les cas, le fichier s'en tient aux consignes de comportement, et l'index renvoie vers le reste.
Qui doit écrire la documentation, l'agent IA ou l'humain ?
Un agent peut rédiger un document et le ranger au bon endroit. Chez nous, une personne décide en revanche de ce qui mérite d'y entrer, en particulier pour les décisions importantes. OpenAI a fait un autre choix sur un dépôt d'un million de lignes, où les agents rédigent et des contrôles automatiques vérifient.
Quelle documentation garder sur un site vitrine ?
Un site vitrine garde un README pour le client, un fichier d'agent, un index et un document d'architecture, même court. Le design system s'y ajoute dès que le site a une direction artistique, et un guide de mise en ligne dès qu'il est déployé.
Un index des documents vaut-il son coût en contexte ?
Oui, tant qu'il tient en une ligne par document. Il occupe un peu de contexte à chaque session, mais il évite à l'agent d'explorer le dépôt pour trouver le bon fichier.
Quelle différence entre la documentation d'un dépôt et une mémoire d'agent ?
Une mémoire retient au fil des sessions ce qui évite de refaire une recherche, et un modèle en fait le tri. La documentation d'un dépôt retient ce qu'une personne a validé, et elle est livrée au client avec le code.
