Écrire de la documentation avec un agent
Un agent redige vite un README, des docstrings ou un brouillon d'ADR, mais il documente le quoi mieux que le pourquoi. Documenter l'intention et les decisions, eviter le doc-code drift, et utiliser la doc comme levier d'autonomie (LP10).
Documenter le pourquoi, pas le quoi
Le code dit deja ce qu’il fait. La valeur d’une documentation est ailleurs : l’intention, le rationnel d’une decision, les contraintes, les trade-offs ecartes. Bref, le pourquoi qu’on ne peut pas lire dans le code.
Point cle : Un commentaire qui paraphrase la ligne en dessous est du bruit. Un agent a qui on demande « commente ce code » produit precisement ce bruit, par defaut.
Demande explicitement la justification, pas la description : « explique pourquoi on utilise un verrou ici » plutot que « commente cette methode ».
Les types de documentation
Chaque artefact repond a une question differente. Les confondre produit de la doc inutile.
| Artefact | Repond a |
|---|---|
| README | Comment installer, lancer, utiliser le projet ? |
| ADR (Architecture Decision Record) | Pourquoi cette decision ? Quel contexte, quelles consequences ? |
Commentaires / docstrings (/// en C#) | Quel est le contrat d’une API publique, ses cas limites ? |
| Doc d’architecture | Quelle vue d’ensemble, quelles frontieres entre modules ? |
Point cle : L’agent excelle sur le squelette et la mise en forme (generer un README a partir de la structure, des docstrings a partir des signatures). Le contenu de l’ADR, lui, vient de la discussion humaine.
La doc est un levier pour l’agent lui-meme
La documentation n’est pas qu’une sortie pour les humains : c’est aussi une entree pour l’agent. S’il peut lire pourquoi le code est structure ainsi, il respecte mieux les conventions au lieu d’inventer les siennes.
Point cle : La documentation est l’un des 12 leverage points (LP10). Un README, des ADR et des conventions ecrites rendent l’agent plus autonome : il s’aligne sur l’existant. C’est un cercle vertueux — mieux c’est documente, mieux l’agent documente a son tour.
En DDD, l’ubiquitous language documente devient un prompt naturel : l’agent reutilise le bon vocabulaire metier.
Ce que l’agent fait bien — et ce qu’il invente
Bien : echafauder un README, formater une doc, rediger des docstrings a partir des signatures, resumer un module, normaliser le style.
A surveiller : l’agent ne connait ni l’intention metier, ni la vraie raison historique d’une decision. Si on lui demande de « justifier » une architecture qu’il decouvre, il produit une justification plausible mais inventee.
Attention — rationnel hallucine. « Ce service utilise un cache car la charge est elevee » peut etre faux : peut-etre que le cache est la pour une contrainte d’un systeme tiers. Le pourquoi reel vient de toi ; l’agent le met en forme.
Le piege du drift : une doc qui ment
Une doc generee se desynchronise du code apres chaque refacto : c’est le doc-code drift. Une doc confidente mais fausse est pire que pas de doc.
Attention — effet d’amplification. Humains et agent font confiance a la doc. Si elle ment, l’agent la relit comme source de verite et propage l’erreur. Une absence de doc, au moins, n’induit personne en erreur.
Point cle : Remedes : garder la doc au plus pres du code, la deriver du code quand c’est possible (signatures, schemas), la relire comme du code, et la verifier en CI. Documenter les frontieres et les decisions, pas l’evident.
Remonte relire la fiche memo ci-dessus en pretant attention aux points rates, puis clique sur « Recommencer » pour retenter.