La documentation d’un projet est rarement à jour. Ce n’est pas par manque de bonne volonté — c’est juste que personne n’a le temps. Conséquence : un nouvel arrivant perd 2 à 5 jours à comprendre le code, et les équipes posent dix fois les mêmes questions.
Le principe d’une doc « auto-vivante »
Un agent IA lit régulièrement votre repository (toutes les semaines, ou à chaque merge dans main) et met à jour les fichiers de documentation en se basant sur le code, les commits récents, et les PR descriptions. La doc devient un reflet automatique du code, pas un artefact à entretenir.
Ce qu’on automatise concrètement
(1) Le README principal (vue d’ensemble, comment démarrer). (2) Les ADR (Architecture Decision Records) à partir des PR significatives. (3) Le glossaire interne. (4) Les diagrammes Mermaid qui décrivent la stack et les flux de données. (5) Le changelog visible côté utilisateur.
Le piège à éviter
Ne pas générer 5000 lignes de documentation prolifique. La règle d’or : la doc générée doit faire la moitié du volume que vous auriez écrit à la main. Sinon, personne ne la lit. L’IA a tendance à sur-expliquer si on ne la cadre pas.
Notre setup type
Une GitHub Action déclenchée à chaque merge dans main appelle Claude avec un prompt structuré. Le résultat est commité automatiquement dans un branch docs-bot qu’un humain peut relire et merger. C’est rapide à mettre en place (1-2 jours) et ça produit un ROI immédiat.
