Documenter un projet pour qu'un agent s'en serve

La première fois que j'ai branché un agent sur un projet qui avait une vraie documentation, je m'attendais à un gain immédiat. Ce que j'ai obtenu, c'est du code impeccable qui appliquait scrupuleusement une convention abandonnée un an plus tôt, parce qu'une page du wiki la décrivait encore. L'agent n'avait pas mal travaillé : il avait fait exactement ce que le projet lui disait de faire.

Une documentation qu'un agent peut utiliser est découpée par sujet, écrite sans rien supposer de connu, et exacte avant d'être complète. C'est une autre discipline que la documentation écrite pour des humains, qui peut se permettre d'être longue, narrative et un peu périmée, parce qu'un lecteur trie en lisant et devine tout seul ce qui n'est plus vrai.

Un agent lit tout, là où un humain parcourt

Quand vous ouvrez une page de documentation, vous ne la lisez pas. Vous balayez les titres, vous sautez les trois quarts, vous vous arrêtez sur le paragraphe qui ressemble à votre problème, et vous accordez spontanément plus de poids à ce qui a l'air récent. Un agent procède autrement : il absorbe le document entier et traite chaque phrase comme une affirmation du projet, sans la hiérarchie implicite que vous appliquez sans y penser. Un manuel de quarante pages dont le chapitre 2 contredit le chapitre 7 reste utilisable par un humain, qui retient la version la plus plausible. Pour l'agent, les deux chapitres pèsent pareil, et il tranche la contradiction au hasard de ce qui l'arrange au moment de produire.

La conséquence pratique est un changement de découpage. Une documentation faite pour un agent se range par sujet, pas par récit : un fichier répond à une question, et il se tient seul. Pas de « comme vu plus haut », pas de prérequis implicite laissé au chapitre précédent, parce que rien ne garantit que les deux morceaux arriveront ensemble dans la fenêtre de l'agent. Chaque fichier porte aussi ses conditions de validité : à quel environnement il s'applique, à quelle partie du code, dans quel cas il ne s'applique pas. Ce que vous perdez en élégance narrative, vous le récupérez en fiabilité, et les humains s'y retrouvent plus vite eux aussi.

Ce qui est faux coûte plus cher que ce qui manque

Une page périmée, un humain la repère d'instinct. La capture d'écran date d'une version qu'il ne reconnaît pas, le nom de l'outil cité a changé depuis, le ton sent le document de lancement jamais rouvert. Il hausse les épaules et va demander à quelqu'un. L'agent n'a aucun de ces signaux, et surtout il n'a aucun moyen de douter : ce qui est écrit dans le projet fait autorité, point. Il va donc produire un travail cohérent, bien argumenté, et faux, ce qui est la pire combinaison possible parce que le coût se déplace entièrement sur la revue. Une information absente provoque une question ou une hésitation visible. Une information fausse provoque une décision, et une décision ne se remarque qu'une fois appliquée partout.

Ce que votre équipe sait sans l'avoir écrit n'existe pas pour lui

Il y a dans tout projet une couche de savoir qui ne figure nulle part, parce qu'elle va de soi pour ceux qui sont là depuis un moment. Où vont les tests. Comment on nomme une branche. Ce que « terminé » veut dire chez vous, qui n'est pas la même chose que chez le client d'à côté. Un agent comble ces trous en imitant ce qu'il trouve dans le code existant, ce qui fonctionne tant que le code est cohérent avec lui-même : si deux conventions de nommage cohabitent parce qu'une migration n'a jamais été finie, il va piocher dans les deux. L'exercice qui attrape cette couche est très bête. Repensez au dernier arrivé dans l'équipe, et à tout ce que vous lui avez dit à l'oral pendant son premier mois : c'est exactement la liste, plus courte qu'on ne croit, et jamais écrite parce que la dire coûte deux minutes sur le moment.

Les interdits comptent autant que les règles

La plupart des documentations décrivent ce qu'il faut faire et presque jamais ce qu'il ne faut pas faire. C'est dommage, parce que la seconde catégorie évite la classe d'erreurs la plus chère : celle qui a l'air raisonnable. La commande qui marche très bien en local et qui vide quelque chose en recette. La bibliothèque qui a été remplacée pour une raison précise et vers laquelle il ne faut pas revenir. Ces lignes rouges ne sont pas dans le code, elles sont dans la mémoire de ceux qui ont payé pour les apprendre, et la raison compte autant que l'interdit lui-même. Face à un cas imprévu, un agent raisonne par analogie : un interdit sec, sans justification, il le contournera proprement en se disant que son cas est différent, alors que le même interdit accompagné de son motif, il saura l'étendre à la situation voisine que vous n'aviez pas anticipée.

Un piège rencontré vaut dix pages de bonnes pratiques

La ligne la plus rentable que vous puissiez écrire ressemble à ceci : « cette commande échoue en silence si telle variable n'est pas définie ». Elle coûte quinze secondes, elle s'écrit au moment exact où quelqu'un vient de perdre une heure dessus, et elle est strictement introuvable autrement, ni dans le code, qui ne porte que le résultat, ni dans la documentation de l'éditeur, qui décrit l'outil générique et pas votre montage. À l'inverse, les bonnes pratiques générales du métier, l'agent les connaît déjà bien mieux que la plupart des pages qu'on écrit sur le sujet : les lui répéter occupe de la place dans son contexte et crée l'illusion que la question est traitée.

Qui tient tout ça à jour ?

C'est la vraie objection, et la seule qui décide si l'ensemble tient ou s'effondre au bout de six mois. La réponse habituelle est une revue trimestrielle, et elle ne marche pas : soit elle n'a jamais lieu, soit elle a lieu et personne ne sait, en relisant une page hors contexte, si elle est encore exacte. La seule méthode que j'ai vue tenir consiste à mettre à jour au moment précis où l'on découvre que c'est faux, et ce moment est parfaitement identifiable : un agent produit quelque chose d'incohérent et vous remontez la cause jusqu'à une page, ou un humain corrige en revue un point que la documentation décrivait mal. La règle tient en une phrase : quand vous attrapez une erreur imputable à ce qui est écrit, vous corrigez ce qui est écrit avant de corriger le code.

Cette règle a un effet de bord qui est en réalité l'essentiel du bénéfice : le volume se régule tout seul. Chaque page a désormais un coût d'entretien visible, donc on supprime au lieu d'archiver, et ce qui reste est ce dont quelqu'un s'est servi récemment. L'autre effet, moins attendu, c'est que cette discipline rend la mémoire du projet lisible par des gens qui n'ouvrent jamais le code. J'ai décrit ailleurs comment rendre cette documentation accessible à un fondateur non développeur et à son propre assistant : ça ne fonctionne que parce que les fichiers sont courts, autonomes et à jour, c'est-à-dire exactement les trois propriétés qu'un agent réclamait déjà.

Si je ne donne ici ni nom de fichier ni syntaxe, c'est volontaire : le format a déjà changé plusieurs fois, il changera encore, et une page qui fige la convention du moment serait fausse avant d'être utile. Reste la limite honnête. Une bonne documentation ne transforme pas un agent médiocre en collaborateur fiable : elle déplace le goulot d'étranglement, et le travail d'écriture ne disparaît pas, il devient visible. Ce qui m'a convaincu, c'est que l'effort profite d'abord aux humains, dont l'intégration dans le projet raccourcit nettement, et que la machine se contente de révéler sans ménagement ce qui n'était écrit nulle part. Le guide de l'IA agentique en entreprise rassemble la méthode complète, et l'accompagnement IA agentique consiste souvent, les premières semaines, à faire exactement ce chantier sur votre dépôt.