Le document de passation : mémoire d'agent entre les sessions

Le 21 mars 2026, mon site de production servait des pages qui mettaient 14 secondes à se charger après qu’une purge de cache a révélé un goulot d’étranglement de performance. J’ai enquêté sur la cause racine au cours de deux sessions, identifié le chemin de code lent, rédigé un plan de correctif et consigné le tout dans un document de passation.

Un document de passation transporte un diagnostic à travers les frontières de session afin que l’agent qui met en œuvre hérite d’une compréhension corrigée au lieu de redériver les mêmes conclusions erronées. Contrairement aux tickets qui indiquent quoi faire, les passations consignent ce qui a été essayé, ce qui était faux et pourquoi les approches antérieures ont échoué. La passation de la page marché a survécu à trois corrections sur quatre jours et a guidé une implémentation qui a réduit le chargement de page de 14 secondes à 108 millisecondes.

Le premier brouillon de cette passation était erroné. Il ciblait le mauvais chemin de code. Une revue de code a détecté que les pages lentes mesurées étaient servies par market_hub(), et non par _fetch_market_data() comme le supposait la passation. La passation a été révisée.

Le deuxième brouillon proposait des partiels HTMX inutiles pour Apple Maps et les décomptes de niveaux. Une revue a détecté qu’Apple Maps signe les URL localement (aucune requête sortante à différer) et que les décomptes de niveaux devaient provenir d’une unique requête d’agrégation. La passation a de nouveau été révisée.

Le troisième brouillon proposait de rendre le point de terminaison météo asynchrone, mais ne précisait pas que le client HTTP synchrone existant continuerait à bloquer la boucle d’événements, même derrière un HTMX. La passation a été révisée une troisième fois.

Quatre jours plus tard, une session différente a lu la passation révisée trois fois et a mis en œuvre le correctif. Austin est passé de 14 290 ms à 108 ms. L’implémentation a ciblé le bon chemin de code, utilisé la bonne approche de requête et ignoré les partiels HTMX inutiles. Chaque correction issue des trois revues était déjà intégrée.

Le document de passation a porté un diagnostic sur quatre jours et à travers plusieurs sessions. Sans lui, la session d’implémentation serait repartie de zéro, aurait fait les mêmes hypothèses erronées, proposé les mêmes optimisations inutiles et nécessité les mêmes corrections. La passation a compressé quatre jours d’investigation en un document que l’agent d’implémentation a lu en quelques secondes. C’est ainsi que la gestion de la fenêtre de contexte s’applique à un problème spécifique : comment transférer un diagnostic à travers les frontières de session sans perdre les corrections qui le rendent exact.

Ce que contient une passation

Un document de passation n’est pas un ticket. Un ticket indique quoi faire. Une passation indique ce qui a été essayé, ce qui a été appris, ce qui était faux et quoi faire ensuite. La différence, c’est la mémoire institutionnelle.

La passation de la page marché contenait :

Le diagnostic. Les mesures de TTFB en rendu à froid pour six pages marché, allant de 381 ms (Tokyo, petit marché) à 14 290 ms (Austin, plus de 500 entreprises). Les mesures prouvaient que le problème évoluait avec le nombre d’entreprises, ce qui pointait la forme de la requête comme goulot d’étranglement.

Les causes racines, priorisées. Quatre causes racines classées par impact : forme de la requête (primaire), API météo bloquant (secondaire), balayage de table complet sur un chemin de code différent (tertiaire) et en-têtes de cache manquants (déjà partiellement traités). Chaque cause racine comprenait des chemins de fichiers, des numéros de ligne et le motif de code spécifique à l’origine du ralentissement.

Les fausses pistes. Le premier brouillon ciblait _fetch_market_data() au lieu de market_hub(). La passation consignait cette erreur et la correction, afin que la session d’implémentation ne redérive pas la même conclusion erronée. Elle consignait également les partiels HTMX abandonnés et les raisons de cet abandon : Apple Maps n’a pas de requête sortante, les décomptes de niveaux appartiennent à la requête d’agrégation.

Le plan d’implémentation. Cinq étapes avec des exemples SQL, des critères d’acceptation et des instructions de vérification. Étape 1 : remplacer la pagination côté Python par une requête de base de données. Étape 2 : ajouter un partiel HTMX météo avec un client async. Étape 3 : mettre en cache le chemin de code secondaire. Étape 4 : ajouter des en-têtes de cache en périphérie. Étape 5 : remesurer les six mêmes URL.

L’article gestion de la fenêtre de contexte explique pourquoi ce niveau de spécificité est important : chaque ambiguïté dans la passation est une décision que l’agent d’implémentation doit redériver, consommant du budget de contexte et risquant la même conclusion erronée.

Les pièges de contexte. Le contexte de template partagé inclut une recherche authentifiée du solde de pièces sur chaque page, y compris celles qui ne le rendent jamais. La passation le signalait comme une préoccupation d’exactitude du cache : s-maxage sans en-têtes Vary appropriés pourrait servir des données d’authentification obsolètes à des utilisateurs anonymes.

Pourquoi les tickets échouent

Un ticket pour le même travail dirait : « Les pages marché sont lentes. Optimisez la requête du hub marché. » La session d’implémentation devrait :

1. Découvrir quel chemin de code sert les pages marché (ce n’est pas évident sans lire le routeur)
2. Profiler le chemin de code pour trouver le goulot d’étranglement
3. Envisager différentes approches d’optimisation
4. En implémenter une
5. Découvrir que l’approche a un effet secondaire (exactitude du cache avec les données d’authentification)
6. Réviser l’approche

Les étapes 1 à 3 avaient déjà été accomplies lors des sessions d’investigation. La passation reporte ce travail. Un ticket le jette.

Le mode d’échec n’est pas la paresse. Le mode d’échec est la perte de contexte entre les frontières de session. Une session d’agent IA commence avec une fenêtre de contexte vierge. Elle ne se souvient pas de ce que la session précédente a découvert. C’est le même problème que celui abordé dans le contexte est architecture au niveau système : ce que vous mettez dans la fenêtre de contexte détermine la qualité de la sortie. Un ticket fournit un objectif. Une passation fournit un objectif plus la compréhension accumulée nécessaire pour l’atteindre correctement.

L’historique des révisions compte

L’historique des révisions de la passation est aussi précieux que son contenu actuel. La passation de la page marché consignait trois révisions avec horodatages et raisons :

• Capturée : 2026-03-21T17:24 (investigation originale)
• Révisée : 2026-03-21T18:20 (corrections de revue de code : mauvais chemin de code, HTMX inutile)
• Révisée : 2026-03-25T06:30 (implémentation terminée, correctif de requête déployé)

L’historique des révisions indique à la session d’implémentation : « ce diagnostic a été contesté et corrigé. La version actuelle intègre ces corrections. » Une passation sans révision peut être fausse. Une passation avec trois révisions a été mise à l’épreuve.

Les fausses pistes font partie de la valeur. Une passation qui dit « nous avons envisagé et rejeté le HTMX /_map parce qu’Apple Maps signe les URL localement » évite à la session d’implémentation de proposer la même optimisation, de la faire réviser et de la voir rejetée. La passation anticipe le rejet.

Quand rédiger une passation

Toutes les tâches ne nécessitent pas une passation. Un correctif de bug qui prend une seule session n’a pas besoin de persistance entre sessions. Une passation est utile lorsque :

L’investigation est coûteuse. Profiler un goulot d’étranglement de performance, tracer une vulnérabilité de sécurité, déboguer une interaction multi-systèmes. Si l’investigation a demandé un effort significatif, la passation préserve cet effort.

L’implémentation aura lieu dans une session différente. Si vous terminez l’investigation aujourd’hui mais que vous mettez en œuvre demain, la passation comble l’écart. Sans elle, la session de demain repart de zéro.

Le diagnostic n’est pas évident. Si le bon correctif nécessite de comprendre pourquoi trois alternatives apparemment raisonnables sont fausses, la passation saisit cette compréhension. Le système du contexte composé explique comment les passations s’intègrent dans l’accumulation plus large de connaissances projet. Un ticket qui dit « corrigez la requête » n’explique pas pourquoi la requête nécessite un correctif spécifique.

Plusieurs personnes (ou agents) pourraient y travailler. La passation est un document de compréhension partagée. Toute session qui la lit hérite du contexte complet de l’investigation.

Les passations comme contexte composé

Une passation est un dépôt dans le système du contexte composé. Chaque passation capture le temps de diagnostic et le convertit en un artefact réutilisable. La session d’implémentation retire le diagnostic à un coût quasi nul.

Au fil du temps, les passations s’accumulent en un historique d’investigation. La passation de la page marché fait référence à l’incident de purge du cache, aux mesures de nightcheck, à la garde API destructrice et au système de revue de code. Chacun d’eux est lui-même le produit de sessions antérieures. La passation les relie en un récit qu’une nouvelle session peut suivre.

La passation ne remplace pas la compréhension. La session d’implémentation doit toujours lire le code, écrire le correctif et vérifier le résultat. La passation remplace la redécouverte. La session n’a pas besoin de découvrir ce qui est déjà connu. L’architecture d’agent Ralph utilise les passations comme principal mécanisme de persistance entre sessions pour sa boucle d’exécution nocturne. Le hub d’ingénierie IA documente la manière dont les passations s’intègrent dans l’infrastructure plus large de hooks, compétences et systèmes de mémoire qui permettent au développement assisté par agent de se composer au fil du temps.

FAQ

Quelle devrait être la longueur d’une passation ?

Suffisamment longue pour saisir le diagnostic, les fausses pistes et le plan d’implémentation. Suffisamment courte pour qu’un agent puisse la lire en un seul chargement de contexte. La passation de la page marché comptait 103 lignes. La plupart des passations font de 50 à 150 lignes.

Où stockez-vous les passations ?

Dans le répertoire mémoire du projet : ~/.claude/projects/{project}/memory/handoff-{topic}.md. Le système de mémoire charge les fichiers pertinents en fonction des descriptions en frontmatter, de sorte que les passations sont découvrables par les futures sessions sans référence explicite.

Les passations remplacent-elles la documentation ?

Non. La documentation décrit comment le système fonctionne. Une passation décrit ce qui a été appris sur un problème spécifique et ce qu’il faut faire à ce sujet. La documentation est permanente. Une passation est consommée par la session d’implémentation, puis devient un contexte historique.

Que se passe-t-il si la passation devient obsolète ?

Le champ de statut de la passation suit cela. Les passations actives sont marquées PLANNED ou IN PROGRESS. Les passations terminées sont marquées RESOLVED avec le hash du commit d’implémentation. Les passations obsolètes sont visibles en tant que contexte historique, mais ne sont pas exploitables.

Sources

Cet article s’appuie sur la passation de performance de la page marché (handoff-market-page-perf.md), qui a guidé le correctif de forme de requête déployé le 25 mars 2026. La passation a survécu à trois cycles de révision sur quatre jours et a éclairé une implémentation qui a permis une amélioration de performance d’un facteur 132. Référencée dans Contexte composé.