Documentation technique après un changement IA : quel livrable protège vraiment la qualité du code ?

Un agent IA peut produire un diff cohérent, faire passer les tests disponibles et laisser pourtant une question sans réponse : pourquoi ce changement existe-t-il, quelles hypothèses le limitent et comment vérifier qu’il reste correct après la prochaine évolution ?

La documentation technique devient alors une pièce de qualité du code, pas un supplément éditorial ajouté après coup. Elle doit rendre le changement compréhensible par un autre développeur, vérifiable par les outils et exploitable par un futur agent. GitHub recommande notamment de vérifier à la fois le comportement fonctionnel, l’alignement avec l’architecture du projet et la maintenabilité du résultat dans une revue de code généré par IA. La documentation GitHub sur la revue du code généré par IA distingue ces contrôles au lieu de réduire la validation au seul passage des tests.

Le problème : un diff ne conserve pas toutes les décisions

Le code montre ce qui a été implémenté. Il ne montre pas toujours ce qui a été envisagé puis écarté, la contrainte métier qui a limité la solution, ni le niveau de preuve attendu avant la fusion. Cette perte de contexte est plus visible lorsque l’IA accélère la production de changements : le volume de propositions augmente, tandis que la relecture doit continuer à reconstruire l’intention.

La bonne question n’est donc pas « faut-il documenter chaque ligne générée par une IA ? », mais « quel artefact doit accompagner ce changement pour que sa qualité reste contrôlable ? ». Quatre formats couvrent la plupart des cas.

Étape 1 : classer le changement avant de demander un document

Commencez par déterminer la nature du changement, avant de demander à l’agent de produire une documentation standardisée. Cette étape évite d’ajouter un fichier de contexte à chaque petite correction et concentre l’effort sur les décisions qui seront reprises plus tard.

1. Correctif local et réversible : demandez une preuve courte dans la pull request : cause identifiée, fichiers modifiés, test lancé et limite connue.
2. Comportement nouveau ou contrat modifié : ajoutez une spécification concise avec les entrées, les sorties, les erreurs attendues et les critères de réussite.
3. Choix qui survivra au changement de code : créez une décision technique qui explique les options écartées et la contrainte principale.
4. Modification influencée par un agent : conservez aussi une trace minimale de l’intervention, notamment la tâche confiée, les contrôles effectués et les propositions rejetées.

Cette classification donne une règle pratique : documenter la décision quand elle doit être réutilisée, documenter la preuve quand elle doit être vérifiée, et documenter l’intervention quand elle doit être auditée.

Étape 2 : écrire une spécification qui reste testable

Une spécification utile ne décrit pas la conversation avec l’IA. Elle décrit le comportement attendu du logiciel. Pour une tâche de développement, limitez-la à quelques éléments observables : objectif, périmètre, cas exclus, contraintes, critères d’acceptation et stratégie de retour arrière.

Évitez les formulations qui demandent seulement une qualité vague, comme « rendre le module plus propre » ou « améliorer les performances ». Préférez une condition vérifiable : « une requête invalide renvoie une erreur documentée sans modifier l’état persistant » ou « la commande reste compatible avec les formats déjà acceptés ».

La spécification devient alors un point de comparaison indépendant du texte produit par l’agent. Elle permet de demander une revue ciblée et de détecter une dérive fonctionnelle même lorsque le diff paraît lisible.

Étape 3 : réserver la décision technique aux choix durables

Une décision technique, parfois appelée ADR, n’a pas vocation à expliquer chaque correction. Elle sert lorsque plusieurs solutions étaient plausibles et qu’un choix risque d’influencer les futures évolutions : stockage, protocole, dépendance, découpage de module, stratégie de cache ou niveau d’autonomie accordé à un agent.

Son format peut rester court : contexte, décision, alternatives écartées, conséquences et conditions de réexamen. L’IA peut préparer une première version, mais l’équipe doit vérifier que le document décrit bien une décision adoptée et non une justification inventée après coup.

Cette distinction protège la documentation contre un défaut fréquent : transformer une explication générée en vérité de projet. Une décision n’est valable que si elle correspond à un choix réellement accepté par les responsables du code.

Étape 4 : joindre une preuve de validation exploitable

La preuve de validation doit permettre à un reviewer de comprendre ce qui a réellement été exécuté. Indiquez les commandes ou contrôles utilisés, leur périmètre, le résultat obtenu et ce qui n’a pas été vérifié. Si aucun test n’a été lancé, écrivez-le explicitement au lieu de laisser le lecteur l’inférer.

• Tests fonctionnels concernés et résultat observé.
• Analyse statique, lint ou contrôle de sécurité exécuté.
• Cas limite ajouté ou vérifié.
• Environnement nécessaire à la reproduction.
• Limite connue, donnée manquante ou contrôle différé.

Cette fiche ne constitue pas un benchmark. Elle ne doit pas transformer une vérification ponctuelle en affirmation générale de compatibilité ou de performance. Elle décrit seulement les contrôles effectivement réalisés pour ce changement.

Étape 5 : garder un journal d’intervention proportionné

Dans un workflow assisté par IA, le journal le plus utile ne cherche pas à conserver chaque échange. Il relie la demande, la proposition, la décision humaine et la preuve disponible. Un format compact peut tenir dans la pull request ou dans un fichier attaché au changement.

Le journal peut contenir : la tâche confiée, le périmètre fourni, les fichiers proposés, les contrôles exécutés, les suggestions rejetées et la personne qui a validé le résultat. Cette trace complète la documentation du code sans prétendre remplacer les tests ou la revue.

Pour aller plus loin sur ce point, consultez le journal d’intervention IA dans un dépôt, qui traite la piste d’audit comme un élément distinct du benchmark et de l’observabilité.

Chronologie recommandée avant le merge

1. Avant l’implémentation : formuler le résultat attendu et classer le changement.
2. Pendant l’exploration : demander à l’agent d’identifier les fichiers concernés, les hypothèses et les risques plutôt que de modifier immédiatement le dépôt.
3. Après la proposition : choisir le livrable documentaire adapté parmi spécification, décision, preuve ou journal.
4. Avant la fusion : exécuter les contrôles prévus et comparer les résultats aux critères d’acceptation.
5. Après la fusion : mettre à jour uniquement les documents qui décrivent une règle durable ou une décision encore valable.

Cette séquence sépare trois choses souvent mélangées : l’intention du changement, la qualité du code et la trace du processus. Elle réduit aussi le risque de produire une documentation abondante mais inutilisable.

La règle de décision pour une équipe

Une équipe peut adopter une matrice très simple. Si le changement modifie un contrat, exigez une spécification. S’il engage une architecture ou une dépendance durable, ajoutez une décision technique. S’il présente un risque fonctionnel, joignez une preuve de validation. S’il est produit ou transformé par un agent dans un workflow contrôlé, conservez une trace d’intervention.

Ces documents ne sont pas interchangeables. Une spécification explique ce qui devait être construit. Une décision explique pourquoi une voie a été retenue. Une preuve indique ce qui a été contrôlé. Un journal établit comment la proposition a été traitée. Les réunir systématiquement dans un seul fichier rend souvent le résultat plus difficile à maintenir.

La meilleure documentation technique après un changement IA n’est donc pas la plus longue. C’est celle qui laisse une réponse vérifiable à la question que le code seul ne couvre pas encore.