Que doit contenir une documentation d'intégration pour qu'un agent d'IA puisse, à partir d'elle, aller jusqu'à sa première modification fusionnée ?

Question ouverte

La documentation d'intégration d'un projet est censée mener une nouvelle recrue d'une machine vierge jusqu'à sa première modification fusionnée. Le chapitre sur la documentation du livre « Software Engineering at Google » recommande pour cela un document « Hello World » qui ne présuppose rien, et cite l'arrivée dans l'équipe comme le meilleur moment pour écrire un tel tutoriel ; Diátaxis le classe comme un tutoriel orienté apprentissage. Les deux sont pensés pour des humains. Mais un agent suit de plus en plus souvent le même parcours — et trébuche à d'autres endroits : sur une étape « se connecter dans le navigateur », sur un « demande dans le canal », sur une commande qui attend une saisie clavier, sur un diagramme sans version textuelle, sur une règle que tout le monde connaît et que personne n'a écrite. Concrètement, restent ouvertes les questions suivantes :

• Quelles étapes des parcours d'intégration typiques échouent le plus souvent pour des agents, et les échecs peuvent-ils être répartis en quelques classes (saisie interactive, autorisation manquante, connaissance implicite, dépendance envers une personne) ?
• Une liste de commandes non interactives avec la sortie attendue suffit-elle, ou les agents ont-ils en plus besoin d'une liste d'interdictions explicite (ne pas déployer, ne rien supprimer, n'écrire à personne) et d'une indication de ce que signifie « terminé » ?
• Comment maintenir une variante du parcours pour agents synchronisée avec la variante pour humains — un document avec des sections marquées, deux documents, ou un parcours qui fonctionne pour les deux parce que chaque étape est de toute façon une commande vérifiable ?
• Existe-t-il des observations ou des journaux sur la fréquence à laquelle un agent parcourt une intégration jusqu'à la fusion sans intervention humaine, et sur ce qui a déclenché les abandons ?
• Les obstacles rencontrés par un agent devraient-ils, comme pour les humains, être réinjectés dans la documentation comme premières contributions — et qui relit ce type de modification ?

Ce qu'une réponse utile contient

Le type de projet et d'environnement de l'agent (outils, droits, présence ou non d'un humain répondant aux questions) ; le parcours ou sa structure ; la liste des étapes qui ont posé problème, avec leur classe d'erreur ; l'ajout qui a aidé et s'il a dégradé la variante pour humains ; en cas de comptage, le nombre d'exécutions et d'abandons. Les retours d'expérience de projets isolés sont bienvenus s'ils sont présentés comme tels.