Documentation avec l’IA : du README au changelog

Pour rédiger de la documentation avec l’IA, laissez un agent de code lire le code et lancer les commandes qu’il documente, donnez à chaque document un public clair, et vérifiez dans le dépôt chaque fonction, flag et exemple qu’il mentionne. Des agents comme Claude Code et Codex sont doués pour les parties fastidieuses de la documentation : transformer une base de code en README, remplir des docstrings, résumer une version à partir de l’historique git. Leur point faible, c’est l’assurance : ils décriront une option qui semble plausible mais n’a jamais été implémentée.

Ce guide couvre ce qu’il faut documenter avec un agent, des prompts qui fonctionnent pour chaque type de doc, la génération de changelogs à partir de git log, la synchronisation de la doc, la place de AGENTS.md, et la relecture de la doc écrite par l’IA pour repérer les API inventées.

Un agent, pas une fenêtre de chat

Le plus grand gain de qualité dépend de l’endroit où le modèle écrit. Coller un fichier dans une fenêtre de chat et demander de la doc donne au modèle un seul fichier et aucun moyen de vérifier quoi que ce soit. Un agent de code qui tourne dans votre dépôt peut :

• ouvrir les fichiers que le code appelle, pas seulement celui que vous avez collé ;
• lancer --help, la suite de tests ou l’exemple qu’il vient d’écrire ;
• chercher tous les endroits où une fonction est utilisée ;
• lire la doc existante et en reprendre le style.

Tous les prompts ci-dessous partent du principe que l’agent tourne dans le dépôt. Si vous n’en avez pas encore configuré un, comment utiliser Claude Code et comment utiliser Codex CLI vous y mènent.

Choisir le public d’abord

« Écris la doc de ce projet » produit une page générique. Chaque type de document a un lecteur différent et une source de vérité différente :

Indiquez le lecteur et la source dans le prompt. Cela change davantage le résultat que n’importe quelle consigne de style.

README

Un bon README répond vite à quatre questions : qu’est-ce que c’est, comment l’installer, comment l’utiliser et comment contribuer. Demandez à l’agent de vérifier au fil de l’écriture :

Écris le README.md de ce dépôt. Public : un développeur qui le découvre
pour la première fois. Sections : ce qu’il fait (2-3 phrases), prérequis,
installation, démarrage rapide, configuration, lancement des tests, organisation du projet.

Règles :
- Prends les commandes dans les scripts de package.json et le workflow de CI ; lance chaque
  commande d’installation et de démarrage rapide et corrige le README si l’une échoue.
- Ne liste que les variables d’environnement réellement lues dans le code ;
  cite le fichier pour chacune.
- Pas de badges, pas de langage marketing, pas de fonctionnalités absentes du code.

« Lance chaque commande » est ce qui transforme un README plausible en README correct. Si l’agent ne peut pas lancer quelque chose (parce qu’il faut des identifiants, par exemple), demandez-lui de marquer cette étape comme non vérifiée pour que vous la contrôliez à la main.

Référence d’API

Pour les bibliothèques et les services, générez autant de documentation de référence que possible à partir des sources, et servez-vous de l’agent pour ce que les générateurs ne savent pas écrire : vues d’ensemble, exemples et explications des comportements délicats.

Pour une API HTTP, demandez à l’agent de construire la référence à partir des définitions de routes elles-mêmes :

Documente chaque endpoint HTTP de src/routes. Pour chacun : méthode, chemin,
authentification requise, corps de requête et paramètres de requête avec leurs types,
forme de la réponse, codes de statut d’erreur. Lis le handler et le
schéma de validation ; ne déduis rien des noms. Ajoute un exemple curl par
endpoint et lance-le contre le serveur de dev local.

Si le projet utilise déjà OpenAPI, faites mettre à jour le fichier de spécification par l’agent au lieu d’écrire une référence Markdown séparée, et laissez vos outils existants l’afficher. Une seule source de vérité est plus facile à garder honnête que deux.

Docstrings et JSDoc

Les agents remplissent vite les docstrings de tout un module, et c’est là qu’ils décrivent le plus souvent ce qu’une fonction devrait faire au lieu de ce qu’elle fait. Demandez un comportement visible dans le corps de la fonction :

Ajoute de la JSDoc à chaque fonction exportée de src/billing/. Pour chacune :
un résumé d’une ligne, @param avec le type et le sens, @returns, et @throws
pour chaque erreur que la fonction peut réellement lever (lis le corps et
les fonctions qu’elle appelle). N’ajoute un @example que si tu le lances.
Ne modifie aucun code.

Deux vérifications peu coûteuses rendent les docstrings fiables :

• TypeScript dans les projets JS : avec // @ts-check en haut d’un fichier ou checkJs dans tsconfig.json, TypeScript vérifie les types de la JSDoc, si bien qu’un mauvais type de @param apparaît comme une erreur.
• Python : les exemples écrits au format doctest (lignes >>>) se lancent avec python -m doctest module.py -v, si bien qu’un exemple qui s’éloigne du code échoue.

Une règle empirique utile : une docstring doit dire pourquoi et à quoi ça sert, pas répéter la signature. « Renvoie l’utilisateur » sur getUser(id): User n’apporte rien ; « Renvoie null pour les utilisateurs supprimés logiquement ; les appelants doivent gérer ce cas » vaut la peine d’être écrit. Dites-le à l’agent.

Notes d’architecture

C’est sur la doc d’architecture que les agents font gagner le plus de temps, car le plus dur est de lire beaucoup de code et de le résumer. C’est aussi là que les hallucinations se cachent le mieux, puisque personne ne vérifie un diagramme ligne par ligne. Encadrez le travail :

Écris docs/architecture.md pour des ingénieurs qui découvrent la base de code.
Couvre : les modules principaux et ce dont chacun est responsable, le chemin d’une requête
de la couche HTTP jusqu’à la base de données, les tâches de fond et les services externes.
Pour chaque affirmation, cite le fichier (et la fonction) d’où elle vient.
Inclus un diagramme Mermaid du chemin d’une requête.
Marque tout ce dont tu n’es pas sûr avec "TODO: verify".

Les citations sont l’essentiel : elles permettent à un relecteur de vérifier des affirmations en quelques secondes, et elles montrent quelles parties deviendront obsolètes quand ces fichiers changeront. Consignez pourquoi les décisions ont été prises, pas seulement ce qui existe ; un court journal des décisions (façon ADR : contexte, décision, conséquences) vieillit mieux qu’une description du code actuel. Une carte de la base de code pour les agents IA traite du problème voisin : donner aux agents une vue d’ensemble dans laquelle ils peuvent naviguer.

Des changelogs à partir de git log

Les notes de version sont une tâche idéale pour un agent : la matière première est dans git, et le travail consiste à filtrer et réécrire pour les utilisateurs. Partez de la plage depuis le dernier tag :

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Puis le prompt :

Écris l’entrée de CHANGELOG.md pour la prochaine version à partir de
git log v1.4.0..HEAD --no-merges. Public : les utilisateurs qui mettent à jour.
Utilise les titres de Keep a Changelog (Added, Changed, Deprecated,
Removed, Fixed, Security). Ignore les refactorings, les tests, la CI et la maintenance.
Réécris chaque entrée du point de vue de l’utilisateur, place les changements cassants en premier avec
les étapes de mise à jour, et garde le hash court à côté de chaque entrée.

Si votre équipe écrit des Conventional Commits (feat:, fix:, feat!: pour les changements cassants), mentionnez-le ; l’agent peut alors trier par type de façon fiable. Si les messages de commit sont laconiques, laissez l’agent lire le diff (git show <hash>) ou la pull request liée pour les entrées qui comptent. Garder le hash à côté de chaque ligne accélère la relecture : vous vérifiez une entrée en ouvrant son commit.

Garder la doc synchronisée

La doc se dégrade parce qu’elle est mise à jour dans une étape séparée que personne ne planifie. La solution est d’intégrer la doc au changement :

1. Même changement, même agent. Ajoutez une ligne à vos règles d’agent : « Quand tu modifies un comportement, des flags, des variables d’environnement ou des API publiques, mets à jour la doc correspondante dans le même commit. »

2. Demandez une vérification de la doc à la fin de chaque tâche :

   Liste chaque doc, section de README, docstring et exemple qui mentionne
   le code que tu as modifié. Mets à jour ceux qui sont désormais faux.

3. Vérifiez une branche avant de la fusionner : donnez à l’agent le diff (git diff main...HEAD) et le dossier de doc, et demandez-lui quelles affirmations de la doc le diff rend fausses.

4. Lancez les exemples comme des tests. Les doctests, un script qui exécute les extraits du README ou une JSDoc dont les types sont vérifiés transforment une doc obsolète en build qui échoue.

5. Générez ce que vous pouvez. Le texte d’aide d’un CLI, les spécifications OpenAPI et les références de types générés à partir des sources ne peuvent pas dériver.

AGENTS.md n’est pas votre documentation

AGENTS.md (lu par Codex et de nombreux autres agents) et CLAUDE.md (lu par Claude Code) sont des fichiers d’instructions pour les agents de code. Ils sont chargés dans chaque session et doivent donc rester courts : commandes de build et de test, conventions, dossiers à ne pas toucher. Lancer /init dans Claude Code ou Codex en génère une première version.

Votre documentation destinée aux personnes a un autre rôle et peut être aussi longue que nécessaire. Mélanger les deux pose deux problèmes : un long AGENTS.md gaspille le contexte de l’agent à chaque tâche, et un README rempli de règles pour agents embrouille les lecteurs. Gardez-les séparés et reliez-les :

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md et AGENTS.md explique ce qui a sa place dans ces fichiers et comment partager un même ensemble de règles entre agents.

Relire la doc écrite par l’IA pour repérer les API inventées

Le bug de documentation le plus dommageable est une API qui n’existe pas : une option de configuration, un flag de CLI ou une méthode que le modèle a inventé parce que des projets similaires l’ont. Les lecteurs font confiance à la doc, et perdent donc du temps avant de soupçonner qu’elle est fausse. Relisez spécifiquement pour cela :

• Cherchez chaque nom avec grep. Demandez à l’agent (ou à un second agent) d’extraire chaque fonction, option, flag, variable d’environnement et endpoint mentionné dans la nouvelle doc et de chercher chacun dans le code. Tout ce qui est introuvable disparaît.

  Extrais chaque identifiant, flag de CLI, clé de configuration et variable d’environnement de
  docs/api.md. Pour chacun, montre où il est défini dans le code avec
  fichier:ligne, ou indique NOT FOUND. Ne modifie rien.

• Lancez chaque exemple. Des blocs de code qui n’ont jamais été exécutés sont des suppositions.

• Vérifiez les valeurs par défaut et les limites. Les nombres (timeouts, tailles, nouvelles tentatives) sont souvent inventés ; chacun doit pouvoir être relié à une constante du code.

• Méfiez-vous des « prend aussi en charge ». Des lignes comme « prend aussi en charge une configuration YAML » ou « peut être utilisé avec Redis » sont du remplissage classique. Demandez le code qui le fait.

• Faites appel à un second relecteur. Un agent distinct qui relit la doc par rapport au code y est moins attaché que celui qui l’a écrite. La revue de code par IA explique comment la mettre en place.

La documentation avec AgentVera

AgentVera est une application de bureau pour macOS, Windows et Linux qui exécute Claude Code, Codex, Gemini CLI et d’autres agents CLI côte à côte. Quelques-uns de ses outils aident pour la doc :

• Rédacteur et vérificateur côte à côte : faites tourner un agent qui écrit la doc et un second qui la vérifie par rapport au code dans le même workspace, ou donnez au travail de documentation son propre worktree.
• Onglet Specs : liste les fichiers Markdown du dépôt, du plus récent au plus ancien, classés en specs, plans et documents, y compris les fichiers non commités que des agents ont écrits dans d’autres worktrees. Le Markdown s’ouvre en aperçu.
• Brain : lit votre README, ARCHITECTURE, CHANGELOG, vos ADR, commits et PR, liste les décisions avec leurs raisons et signale celles dont les termes de code n’apparaissent plus dans le code, un bon indice de doc obsolète.
• Visite du projet : une exécution de Claude Code en lecture seule qui résume la stack, les modules et les fichiers clés d’un dépôt, un bon premier jet pour des notes d’architecture.
• Code review : faites relire les modifications de doc d’un agent par le modèle Claude de votre choix, avec des remarques liées au fichier et à la ligne.
• Panneau Git : parcourez l’historique à partir duquel vous construisez les changelogs, et laissez Claude Haiku écrire les messages de commit dans le style de votre dépôt, ce qui facilite le prochain changelog.

En résumé

L’IA rend la documentation peu coûteuse à écrire, ce qui fait de l’exactitude le vrai travail. Faites tourner l’agent dans le dépôt, dites-lui qui est le lecteur et où se trouve la vérité, faites-lui lancer les commandes et les exemples, et construisez les changelogs à partir de git log en gardant les hashes. Mettez à jour la doc dans le même changement que le code, réservez AGENTS.md aux agents et la doc aux personnes, et cherchez chaque nom documenté avant de publier. Quand une doc révèle plutôt un bug, déboguer du code avec l’IA prend le relais.