Le départ d’un développeur est toujours un moment de vérité pour une équipe. Avec un agent IA, il devient un test de survie. Contrairement à un service classique, dont le comportement se lit dans le code, un agent tient le sien de l’interaction entre un modèle, des instructions, des données, des outils et des configurations. Si ces éléments ne vivent que dans la tête de la personne qui part, l’agent devient une boîte noire coûteuse que personne n’ose toucher.
Le constat est fréquent dans les équipes qui industrialisent leurs premiers agents: la documentation traditionnelle ne suffit pas. Des schémas d’architecture et des commentaires de code décrivent la structure, pas le comportement. Or c’est le comportement qui pose problème. Pourquoi l’agent refuse-t-il certaines demandes? Pourquoi son ton varie-t-il d’un jour à l’autre? Quelle instruction produit tel format de sortie? Autant de questions dont la réponse vit dans des fichiers de configuration, des prompts systèmes et des jeux de tests, rarement dans un document que l’équipe lit.
Cet article vous donne ce que vous pouvez réutiliser immédiatement: la liste précise de ce qu’il faut documenter pour qu’un agent survive au départ de son développeur, le niveau de détail défendable, et la méthode de transfert qui évite de dépendre d’une seule personne.
Ce qu’un agent exige de plus que le code classique
Un agent repose sur quatre couches distinctes: le prompt système, les outils, les contextes de données et les jeux d’évaluation. La documentation doit décrire chacune d’elles, mais surtout les liens entre elles. Prenons l’exemple d’un assistant de support qui s’appuie sur un RAG interne. Si le développeur part avec les détails de la base vectorielle, les règles de filtrage par client et les consignes de refus, la personne qui reprend découvre un agent qui répond mal, sans aucun moyen de comprendre pourquoi. Le composant qui pose problème n’est pas le code: c’est le compromis entre les règles du prompt et le contenu des sources indexées.
Documentez donc chaque couche pour ce qu’elle est, et notez explicitement les dépendances: quel outil utilise quelles données, quel réglage du prompt dépend de quel paramètre du modèle. Une page de dépendances vaut dix pages de description.
Les evals: la documentation qui se vérifie
Le premier document à écrire n’est pas un guide: c’est un jeu de tests. Un ensemble d’evals décrit le comportement attendu d’un agent mieux que n’importe quel texte, parce qu’il se vérifie par l’exécution. Trente cas couvrant les questions fréquentes, les refus obligatoires, les formats de sortie et les cas limites constituent la référence de ce que l’agent doit faire.
Quand le développeur part, l’équipe qui reste peut modifier un prompt, lancer les evals et constater objectivement les régressions. C’est la seule documentation qui ne ment pas. Si votre agent n’a pas d’evals, commencez par là: demandez au développeur de transformer ce qu’il sait en cas de test plutôt qu’en prose. Vous récupérez du savoir-faire mesurable, et le transfert se vérifie par l’exécution au lieu de se croire sur parole.
Prompts, configurations et outils: tout ce qui est versionné compte
Le prompt système est du code. Il doit vivre dans le dépôt, avec un historique et une justification à chaque modification. Pratique concrète: ajoutez un champ commentaire à chaque version de prompt, mentionnant l’incident ou l’objectif qui a motivé le changement. Dans six mois, l’équipe saura pourquoi telle consigne de ton existe, au lieu de la supprimer sur un coup de tête.
Les configurations méritent le même traitement: modèle utilisé, température, limite de contexte, budget par requête, clés d’API, délais de timeout. Une fiche par environnement (développement, préproduction, production) avec les valeurs exactes et la procédure de modification. Les définitions d’outils, enfin, doivent préciser leurs signatures et surtout leurs permissions: ce que l’agent peut appeler en autonomie, ce qui exige une validation humaine. C’est souvent la partie la moins documentée et la plus sensible.
Le runbook de continuité: le document qui manque partout
La plupart des équipes documentent les fonctionnalités, rarement les pannes. Un runbook de continuité est la procédure à suivre quand l’agent se met à répondre n’importe quoi: quels logs consulter en premier, quelle métrique regarder, quelle version de prompt restaurer, comment redéployer, comment joindre le fournisseur d’API et dans quel délai. Deux pages suffisent. Elles font la différence entre une heure d’intervention et une journée d’enquête.
Écrivez ce runbook du point de vue de la personne qui arrive, pas de celle qui part. Testez-le: demandez à un collègue qui n’a jamais touché au système de suivre la procédure de restauration. S’il échoue, complétez. Cette répétition est le seul moyen honnête de vérifier que le document tient sa promesse.
Le bon niveau de documentation: comment trancher
La question pratique est toujours la même: combien documenter? La règle qui tient est simple. Documentez ce qui sert à modifier le système ou à le remettre en marche; ignorez le reste. Une information qui n’aide ni à changer l’agent, ni à le réparer, ni à le faire évoluer est du bruit. Une information qui permet l’une de ces trois actions est de la documentation utile, quelle que soit sa forme: evals, prompt versionné, runbook ou fiche de configuration.
Cela donne une liste de contrôle courte en quatre points: un jeu d’evals exécutable, un prompt système versionné et justifié, une fiche de configuration par environnement, un runbook de restauration testé. Si les quatre existent et sont à jour, l’agent survivra au départ de son développeur. S’il en manque un, c’est le premier à écrire.
L’accompagnement Agenticiel: la continuité dès la conception
Cette documentation ne s’écrit pas bien dans l’urgence d’un départ. Elle se construit pendant le développement, au fil des décisions. C’est pourquoi, chez Agenticiel, la documentation des agents fait partie de la définition du travail, pas une tâche ajoutée à la fin. Chaque agent livré s’accompagne de ses evals, de ses prompts versionnés et de son runbook, parce que l’équipe qui reprend le produit est aussi importante que celle qui le construit.
Notre équipe de développeurs offshore francophones à Madagascar travaille en sous-traitance de développement sur ces sujets, en français, avec un décalage horaire réduit et des cycles de validation quotidiens. La continuité est garantie par la méthode: tout ce qui fait le comportement d’un agent est écrit, versionné et testé avant d’être livré.
Notre approche consiste à livrer des agents IA que votre équipe peut reprendre, faire évoluer et maintenir sans dépendre d’une personne en particulier, avec une documentation qui se vérifie par l’exécution plutôt que par la lecture.