Documenter le contexte d'un agent IA pour qu'un autre puisse le reprendre

Où vit le contexte de ton agent, ce qu'un dépôt ne transmet pas à lui seul et comment vérifier qu'un collègue peut reprendre.

· 10 min de lecture

Un agent IA qui te rend service peut s'appuyer sur du contexte resté personnel : un fichier d'instructions, des skills, des règles de garde, l'état de tes projets. Tant que c'est toi qui le lances, ça ne se voit pas. Le jour où tu es absent, ou où un collègue veut faire tourner le même agent sur le même sujet, il risque de devoir reconstruire ce contexte avec un outil qui a l'air identique et qui se comporte autrement.

Je fais du produit depuis quinze ans, en organisation, et j'ai monté mon propre dispositif d'agents avec deux outils (Claude Code et Codex) qui lisent les mêmes instructions. Ce texte part de l'inventaire de ce dispositif, fait en préparant cet article, et de la question que pose un PM avec une équipe : si ce n'est plus moi, qui reprend, et avec quoi ?

Où vit ce que ton agent lit

Le contexte qui rend un agent utile se range en général à trois endroits : dans le compte d'une application, sur ton disque, ou dans un dépôt. Les deux premiers peuvent rester liés à ton compte ou à ta machine, même quand tu les utilises pour un projet d'équipe. La mémoire d'une application dépend de son fonctionnement : elle peut prendre la forme de fichiers, de souvenirs consultables ou d'éléments moins accessibles. Tant que tu n'as pas extrait et relu ce qui compte pour le projet, tu ne sais pas ce qu'un collègue pourra reprendre. Un fichier sur ton disque n'existe que là où se trouve ton disque.

Mon inventaire, vérifié sur mon poste, donne ceci. Mon fichier d'instructions global n'est pas dans un dépôt Git : je n'ai donc pas cet historique pour suivre ses changements et les transmettre. Mon deuxième outil lit ce même fichier par un lien symbolique, ce qui évite deux copies divergentes et ne change rien au problème. Mes skills sont des liens vers des dossiers de mon Mac. Mes garde-fous, des hooks, sont déclarés dans mes réglages utilisateur, donc sur ma machine aussi. Tout fonctionne entre deux outils, tant que je suis assis devant mon ordinateur. La transmission de cet ensemble à un collègue reste à organiser.

Le premier geste de documentation est cet inventaire : pour chaque chose que ton agent lit, noter où elle vit et qui d'autre y a accès. La durée dépend du dispositif ; commence par un agent et une tâche que tu voudrais pouvoir transmettre.

Voici un exemple de grille pour une équipe, à remplir avec ses vrais chemins et ses vrais responsables :

ÉlémentOù il vitCe que le collègue doit récupérerComment vérifier la reprise
Instructions du projetDépôt partagéFichier et éventuels importsVérifier qu'ils sont chargés dans une nouvelle session
Décisions et état du chantierNotes ou documents d'équipeRéférences accessibles et date de mise à jourRetrouver une décision et sa source
SkillDépôt ou installation localeInstructions, scripts et dépendancesExécuter une petite tâche connue
Garde-fouRéglages et scriptDéclaration, script et conditions d'activationVérifier une action permise et une action bloquée
Accès aux outilsCompte ou posteProcédure d'accès, sans copier les secretsOuvrir une ressource autorisée

Ce qui ne se transmet pas : les garde-fous

Les instructions se copient facilement, puisque ce sont des fichiers texte. Les garde-fous sont plus fragiles, et c'est là que la reprise casse sans bruit.

J'ai ajouté un hook fin septembre parce qu'une consigne écrite dans un fichier ne suffisait pas : sur plusieurs sessions, l'agent avait tranché seul et écrit dans mes notes là où il devait d'abord me demander. La documentation de Claude Code est cohérente avec ce constat : elle précise que le contenu de CLAUDE.md est traité comme du contexte, pas comme une configuration appliquée, et recommande un hook de type PreToolUse pour bloquer une action quoi que décide le modèle. Or l'endroit où le hook est déclaré décide de qui en bénéficie. Dans la même documentation, les réglages du dossier utilisateur valent pour toi seul et pour tous tes projets, ceux du fichier .claude/settings.json d'un projet valent pour tous ceux qui travaillent dessus, par le dépôt. Un collègue qui clone ton dépôt récupère ton contexte et tes instructions, pas les hooks restés dans ton dossier utilisateur. Il travaille alors avec ta façon de faire, sans la protection que tu avais jugée nécessaire, et rien ne l'en avertit.

Déplacer le hook dans le dépôt ne suffit pas toujours. Les miens sont déclarés avec des chemins propres à mon Mac : copiés tels quels, ils casseraient sur une autre machine. Il faut utiliser des chemins ancrés sur le projet et vérifier le comportement ailleurs que chez soi. Dans Claude Code, la documentation prévoit notamment ${CLAUDE_PROJECT_DIR}. Le script, ses dépendances et sa déclaration doivent voyager ensemble. Un hook commité rend la protection partageable ; son activation et son effet restent à tester.

Un fichier de contexte pour plusieurs outils

Deux conventions se côtoient pour écrire des instructions à un agent. AGENTS.md est un format ouvert, présenté sur agents.md comme maintenu par l'Agentic AI Foundation, une fondation de la Linux Foundation, et lu par de nombreux outils (Codex, Cursor, Gemini CLI, GitHub Copilot, entre autres). Claude Code lit CLAUDE.md. Dans sa documentation consultée en octobre 2026, la lecture directe d'AGENTS.md dépend de la version et du réglage des instructions du projet. Avec le comportement par défaut, un CLAUDE.md ou CLAUDE.local.md dans le dossier courant ou un parent peut empêcher cette lecture directe. Un CLAUDE.md contenant l'import @AGENTS.md permet de partager le même texte. C'est ce que je fais dans mes projets, et c'est le détail à vérifier avant de croire qu'un collègue sous un autre outil lit les mêmes règles que toi. Ces comportements évoluent avec les versions des outils : relis la documentation de l'outil de ton équipe plutôt que de t'y fier ici.

L'intérêt pour la reprise tient moins à l'outil qu'à l'endroit : un fichier dans le dépôt, lisible par le suivant quel que soit son outil.

Trois dépôts, trois propriétaires

Qui reprend dépend de ce que le dépôt contient, et de qui en est propriétaire. Aakash Gupta et Shubham Saboo, dans un article sur le versionnage des artefacts d'agent destiné aux PM, proposent trois dépôts, que je résume d'après la distillation que j'en ai faite, la fin de l'article étant payante.

  • Un espace privé, avec ton CLAUDE.md personnel et tes skills, où tu travailles directement sur la branche principale parce que personne d'autre ne le lit.
  • Un dépôt d'outils partagés, avec les mêmes types de fichiers dépouillés de tout ce qui est personnel ou propre à une entreprise, qu'un collègue peut cloner pour avoir la boîte à outils complète.
  • Un dépôt par projet, qui devient à la livraison l'historique de ce qui a été construit, pourquoi, et comment ça a été évalué.

Ce découpage dit aussi quand Git devient utile pour autre chose que la sauvegarde. Seul face à tes fichiers, tu n'as pas besoin de branche ni de pull request. Dès qu'une deuxième personne dépend du même skill ou fichier d'instructions, une pull request donne un endroit pour relire le changement avant de l'adopter. Cela suppose d'en faire une règle d'équipe et d'avoir quelqu'un qui relit.

Pour un PM en entreprise, une question s'ajoute, que le découpage ne tranche pas : à qui appartient chaque dépôt. Ton contexte personnel dit comment tu travailles, et il te suit. Le contexte d'un projet de l'équipe dit ce qu'est le produit, ce qui a été décidé et pourquoi, où en sont les chantiers. Il doit rester dans un espace contrôlé par l'organisation, accessible au prochain responsable. Le dépôt d'outils réutilisables, lui, demande un autre tri : retirer le contexte d'entreprise et les données personnelles avant tout partage extérieur.

Ce qui n'a rien à faire dans le dépôt

Plus un dépôt est destiné à être cloné par d'autres, plus la question de ce qu'on y met compte. J'ai déjà fait deux erreurs sur ce point, en mars, en versionnant mes notes pour suivre ce que les agents y modifiaient. Mon premier commit embarquait plus de 100 000 fichiers : pièces jointes, fichiers de plugins, fichiers système. J'avais aussi mis un jeton d'accès GitHub en clair dans un fichier de configuration pour qu'un service de déploiement puisse cloner un dépôt privé. Ça fonctionnait, et c'était une mauvaise idée.

J'en ai retenu qu'un .gitignore est une décision de périmètre, pas un détail technique. Un dépôt privé n'est pas une stratégie de confidentialité : le .gitignore d'abord, un scan de secrets ensuite, le push en dernier. Les clés d'API, les fichiers d'environnement, les noms réels de clients, les transcriptions et les données personnelles restent dehors. Le fichier de contexte qu'un collègue va lire ne doit pas non plus devenir une autobiographie : limite-le à la façon de travailler.

Qui tient le contexte à jour

Un fichier de contexte vieillit sans rien dire. L'agent lit un état périmé avec la même confiance qu'un état à jour, et ses réponses se dégradent sans qu'aucune erreur apparaisse. Un propriétaire nommé et une cadence de relecture permettent de le corriger avant que ce décalage ne s'installe.

La cadence n'est pas la même pour tous les fichiers. Dans les procédures de dossier de contexte produit que j'ai distillées, les fichiers qui décrivent le pari en cours se rafraîchissent souvent, ceux qui décrivent l'identité du produit ou le ton presque jamais. Un propriétaire qui relit tout au même rythme finit par ne plus rien relire. Et ces fichiers restent courts : du contexte, pas une archive, avec les comptes rendus et les rapports ailleurs.

Ce que cela change dans une équipe : le jour où tu pars, le dépôt de contexte doit avoir un nom à la ligne « qui le met à jour », comme n'importe quel document dont dépend un travail courant.

Ce qui reste fragile

Je n'ai pas terminé cette migration chez moi. Mon dispositif est inventorié, pas encore déplacé dans un dépôt partagé, donc ce texte décrit des écarts constatés et une méthode, pas une reprise réussie par un collègue. La reprise effective par un collègue reste à vérifier.

Trois limites restent entières. Le contexte implicite ne se transmet pas automatiquement avec les fichiers ; il faut identifier ce qui a été conservé et ce qui manque. Un fichier versionné peut être faux et bien rangé : l'historique prouve qu'il a changé, pas qu'il est juste. Et un hook commité ne protège que si quelqu'un vérifie qu'il tourne sur la machine du suivant.

Ce que tu peux faire lundi

  1. Choisis une tâche réelle à transmettre et remplis l'inventaire pour cette tâche : fichiers lus, emplacement, accès et responsable.
  2. Rassemble le contexte dans l'espace partagé de l'équipe. À côté des instructions, ajoute une courte note de reprise : objectif, état actuel daté, décisions et sources, questions ouvertes, prochaine action. Sépare les scripts et les accès nécessaires des informations métier.
  3. Fais ouvrir une session neuve à un collègue avec sa propre installation et ses propres accès. Qu'il retrouve une décision, accomplisse une petite tâche connue et vérifie le garde-fou critique avec un cas permis et un cas bloqué, dans un environnement d'essai. Un script présent mais jamais déclenché ne passe pas ce contrôle.
  4. Note ce qui a manqué pendant cette reprise, le nom de la personne qui corrige et la date de relecture. Le résultat attendu est un collègue capable d'exécuter la tâche sans tes explications orales, avec des limites visibles lorsqu'un accès ou une protection manque.

Sources

Les ressources dont je parle

À lire ensuite

Recevoir la newsletter

Des tutos, des essais et des retours bruts sur ce que je construis. Le lien pour te désabonner est en bas de chaque édition.

L’inscription se termine sur Substack, dans un nouvel onglet.