Un agent qui fonctionne mais que personne ne sait modifier n'est pas un actif. C'est une dépendance. Elle est confortable quelques mois, puis quelqu'un veut changer une phrase dans une réponse et il faut rappeler le prestataire pour ça. Après trois ans à accompagner des Startups d'État chez beta.gouv.fr, j'ai vu ce qui reste et ce qui disparaît quand une équipe change : ce qui reste, c'est ce qui est écrit à un endroit que les gens connaissent.
Le procès de la documentation
Je connais les objections. « On n'a pas le temps. » « Ça sera périmé dans deux mois. » « Le code est la documentation. »
La deuxième est la seule sérieuse, et elle a une réponse : documente ce qui bouge peu. L'intention, les entrées, les sorties, les procédures. Pas le détail d'implémentation, qui effectivement se périme et qui se lit dans le scénario.
La troisième ne s'applique pas ici. Un agent, ce n'est pas seulement du code : c'est des prompts, des seuils, des choix de périmètre et des décisions métier qui n'apparaissent nulle part. Pourquoi il escalade au-delà de tel score, pourquoi tel type de demande est exclu — ça ne se déduit d'aucun fichier.
Le minimum vital : sept blocs, deux pages
Ma règle est stricte : deux pages, pas plus. Un document de quarante pages n'est jamais relu, donc jamais à jour, donc faux. Deux pages, ça se relit en dix minutes tous les trimestres.
1. À quoi il sert
Trois phrases. Le problème traité, pour qui, et ce qu'on faisait avant. Écrit pour quelqu'un qui arrive dans l'entreprise et n'a aucun contexte.
Ajoute la phrase la plus utile de tout le document : ce qu'il ne fait pas. Les cas explicitement hors périmètre, et la raison. C'est ce qui empêche, deux ans plus tard, qu'on lui reproche de ne pas traiter quelque chose qu'il n'a jamais été censé traiter.
2. Ce qu'il consomme, ce qu'il produit
Les entrées : d'où viennent les données, dans quel format, à quelle fréquence, qui en est propriétaire. Les sorties : ce qui est écrit, où, et qui le consomme derrière.
Ce bloc est celui qu'on consulte le plus, parce que c'est celui qui répond à la question « si je change ça, qu'est-ce que je casse ? »
3. Où sont les prompts
Le chemin exact. Pas « dans le dossier IA du Drive » : le lien, le nom du fichier, le nom du nœud dans le scénario.
Et une règle sur leur gestion : les prompts sont versionnés. Un prompt modifié sans trace, c'est un comportement qui change sans que personne sache quand ni pourquoi. Un simple historique daté avec l'auteur et la raison suffit.
4. Comment le couper
Le bloc que je fais écrire en premier, et en gras. La procédure exacte pour arrêter l'agent : quel bouton, quel écran, quel effet de bord. Ce qui se passe pendant l'arrêt — les demandes sont mises en attente ou perdues ? Qui a le droit de le faire, et qui prévenir.
Une personne qui panique à 18h un vendredi doit trouver ça en quinze secondes. Si elle ne trouve pas, elle débranche quelque chose au hasard.
5. Comment le tester
Cinq à dix cas d'exemple avec leur entrée et la sortie attendue. Stockés dans un fichier, pas dans le document.
C'est le bloc qui rend la modification possible. Sans jeu de test, personne n'ose toucher au prompt : on ne saurait pas si on a cassé quelque chose. Avec dix cas à rejouer, un membre de l'équipe peut modifier, vérifier, et se corriger seul. C'est ce qui transforme un outil intouchable en outil vivant.
6. Ce qui a été décidé et pourquoi
Cinq à dix lignes, format « on a choisi X plutôt que Y parce que Z ». Pourquoi ce modèle, pourquoi ce seuil d'escalade, pourquoi ce périmètre restreint.
Ce bloc évite la reconstruction archéologique. Sans lui, la personne suivante refait les débats déjà tranchés, ou pire, défait une décision qui protégeait de quelque chose qu'elle ignore.
7. Qui appeler
Trois noms avec leur rôle : le propriétaire métier, la personne technique, le contact chez le fournisseur si applicable. Avec une date de dernière mise à jour de ce bloc, parce que c'est celui qui périme le plus vite.
Faire de la transmission un critère de fin
Quand j'interviens, la documentation n'est pas un livrable qu'on ajoute à la fin. C'est un critère de fin de mission, et il se vérifie par un test, pas par la remise d'un fichier.
Le test, je l'appelle la reprise à blanc. Une personne de l'équipe, qui n'a pas construit l'agent, doit réussir trois choses avec le seul document, sans me poser de question :
- Modifier une phrase dans une réponse et vérifier que le changement est effectif.
- Ajouter un cas au jeu de test et le faire tourner.
- Arrêter l'agent, puis le redémarrer.
Une heure, chronométrée, en ma présence mais en silence. Chaque fois qu'elle bloque, la documentation a un trou : je le note et je le comble. Aucun exercice ne m'a jamais autant appris sur la qualité de ce que j'écrivais.
Ce test a un effet secondaire précieux : la personne qui l'a passé n'a plus peur de l'outil. La peur de casser est le premier facteur d'abandon d'un agent interne, bien avant la qualité technique.
À inscrire dans le contrat ou dans le cadrage : la mission se termine quand quelqu'un d'autre a modifié l'agent seul, pas quand l'agent fonctionne.
Ce que ça change concrètement
Prends ton agent le plus utile. Ouvre un document vierge, écris les sept blocs en une heure — ce sera imparfait, ce n'est pas grave. Puis fais passer le test de reprise à quelqu'un qui n'a pas participé.
Tu découvriras en une heure ce que tu croyais évident et qui ne l'est pour personne d'autre. C'est exactement ce qu'on cherche à savoir, et il vaut mieux l'apprendre pendant que tu es encore là.