Handoff Skill : Le Workflow Claude Code Qui a Résolu Ma Surcharge de Contexte

Skill Handoff : Le Workflow Claude Code Qui a Résolu Ma Surcharge de Contexte

La session était à 142 000 tokens quand j'ai remarqué que Claude avait commencé à se répéter.

J'étais plongé dans une conversation de planification sur un nouveau pipeline de contenu Aria — trois marques, quatre types de publications, un protocole de recherche partagé, tout le programme. À mi-chemin, je lui ai demandé d'élaborer une petite refactorisation d'un skill cron sans rapport qui n'avait rien à voir avec le pipeline. Quarante-cinq minutes plus tard, Claude contredisait poliment des décisions que nous avions verrouillées deux cents messages plus tôt, mélangeait la logique du cron avec la spécification du contenu, et me citait mes propres ADR légèrement de travers. La fenêtre de contexte de 1M tokens était techniquement encore ouverte. En pratique, le modèle travaillait dans le brouillard.

Cette session est la raison pour laquelle j'ai adopté le skill de handoff. Et dès que j'ai commencé à utiliser handoff au lieu de /compact pour ces moments-là, la différence n'était pas subtile — c'était la différence entre un ingénieur concentré qui termine une tâche proprement et un fatigué qui n'arrête pas de rouvrir le même fil Slack.

C'est l'article que j'aurais aimé que quelqu'un me remette il y a six semaines. Nous allons démonter le skill de handoff : comment il fonctionne, pourquoi il surpasse la compaction pour le travail multi-thread, ce que le fichier markdown contient réellement, quand l'utiliser, et comment je l'ai intégré dans mon propre workflow Aria + Claude Code sur ce site. À la fin, vous saurez exactement où dans vos sessions actuelles vous devriez écrire un handoff et où vous ne devriez pas.

La fenêtre de contexte est plus grande, et cela a empiré le problème

Laissez-moi planter le décor correctement, car le cadrage compte.

Claude Code est maintenant livré avec une fenêtre de contexte de 1M tokens. Cela ressemble à un problème résolu — versez tout dedans, le modèle s'en sortira. Ce n'est pas un problème résolu. La propre documentation d'Anthropic le confirme : la précision et le rappel se dégradent à mesure que le contexte se remplit. Les tests indépendants d'équipes qui exécutent Claude Code en production placent le point de dégradation pratique bien avant le plafond — la qualité commence à baisser autour de la barre des 120 000 tokens, bien avant que la fenêtre ne soit techniquement pleine. Certaines équipes rapportent une perte de qualité mesurable dès 50 % de la capacité.

Je conçois chaque fenêtre de contexte comme deux couches empilées l'une sur l'autre :

• La zone intelligente — les premiers tokens, le prompt système, les échanges les plus récents. L'attention est vive ici. Le modèle sait ce que vous avez demandé, ce qu'il a répondu et ce qui est sur la table en ce moment.
• La zone bête — les tokens ultérieurs, le milieu obsolète, les parties que le mécanisme d'attention doit combattre pour pondérer correctement. C'est encore « dans le contexte ». Ça ne reçoit simplement pas le focus que vous croyez.

Une fois qu'une session entre dans la zone bête, vous ne le remarquez pas toujours. Les réponses sonnent encore confiantes. Elles peuvent encore citer des échanges antérieurs. Mais la précision baisse. Des décisions que vous aviez prises sont oubliées ou silencieusement inversées. Les sélections d'outils deviennent floues. Le code commence à ressembler à un composite de trois choix de conception différents sur lesquels vous aviez presque convergé.

La version honnête de « 1M de contexte » est plutôt : 1M de plafond, ~120K de zone intelligente fiable, puis une longue courbe de dégradation. Budgétiser l'attention à l'intérieur de la fenêtre est aussi important que le plafond lui-même — et je dirais même plus important. J'ai écrit en détail sur ce compromis dans mon analyse de la gestion de contexte 1M de Claude Code et dans l'article sur l'hygiène de contexte aux limites de tokens. Les deux s'appliquent encore.

Ce que fait le handoff, en une ligne : il vous donne un moyen propre de répartir le travail sur plusieurs sessions pour que chacune reste dans sa propre zone intelligente au lieu de prétendre que la zone bête n'existe pas.

Ce que le skill de handoff fait réellement

Voici le changement de workflow qui a cliqué pour moi.

Quand le skill de handoff est invoqué, la session Claude Code actuelle compresse tout ce qui est pertinent — ce que nous essayions de faire, ce que nous avons décidé, ce que nous avons essayé, ce qui est encore ouvert, quels fichiers nous avons touchés, quels skills la prochaine session devrait récupérer — dans un seul fichier Markdown. Ce fichier est enregistré dans le répertoire temporaire du système d'exploitation (pour ne pas encombrer l'espace de travail), puis une session Claude Code fraîche ouvre ce fichier et poursuit le travail sans hériter du ballast.

Quelques détails que j'ai mis quelques essais à apprécier :

Le fichier de handoff est conçu sur mesure, pas générique. Le skill accepte un argument décrivant le focus de la prochaine session. « Continuer la conception de l'API » produit un handoff très différent de « construire un prototype UI pour le design qu'on vient d'esquisser » — même quand les deux viennent de la même session parente. La compression est intentionnelle, pas un résumé aveugle.

C'est un vrai fichier Markdown, pas un blob JSON caché. Je peux l'ouvrir, le lire, le modifier, ajouter un paragraphe, supprimer une section, expurger un token avant de le transmettre. C'est une propriété que j'ai sous-estimée jusqu'à ce que j'essaie de faire la même chose avec le résumé de /compact, qui est opaque et avec pertes de manières que vous ne pouvez pas auditer.

Il pointe au lieu de dupliquer. Si nous avions écrit un issue GitHub ou un ADR pour le travail, le fichier de handoff y fait référence au lieu d'en coller le contenu. Ça paraît évident — sauf que /compact fait l'inverse. Il re-résume tout, donc la prochaine session se retrouve avec une paraphrase floue de l'issue que vous aviez déjà rédigé précisément.

Il inclut une section « skills suggérés ». C'est la partie que je veux que chaque framework copie. La session actuelle sait quels outils, skills ou patterns de sous-agents la prochaine session aura probablement besoin — TDD, brainstorming, worktrees, vérification — et elle écrit cette indication dans le handoff. La session fraîche arrive déjà orientée vers la bonne boîte à outils.

Les données sensibles sont expurgées avant l'enregistrement. Clés API, secrets, informations personnelles — le skill les supprime avant que le fichier n'arrive sur le disque. Je scanne quand même les handoffs manuellement avant de les transmettre, mais avoir cela comme comportement par défaut intégré vaut mieux que d'espérer m'en être souvenu.

Si vous avez utilisé le framework superpowers d'Obra (environ 195k étoiles sur GitHub au moment où j'écris, en croissance rapide), cela vous semblera natif — le handoff est exactement le genre de skill discipliné et orienté méthodologie qui fait fonctionner tout cet écosystème. J'ai couvert le pattern plus large dans ma review du plugin superpowers. Le skill de handoff est la pièce que j'ai sous-utilisée les premières semaines jusqu'à ce que les mathématiques multi-session me rattrapent.

Compaction vs handoff : la comparaison qui a changé ma façon de travailler

/compact et handoff se ressemblent de loin. Les deux produisent une vue compressée de là où vous en étiez. Ils résolvent des problèmes très différents.

Voici la comparaison directe telle que je les utilise maintenant :

Lisez ce tableau en travers une seconde. La compaction est un outil de mémoire — il essaie de faire tenir un seul fil. Le handoff est un outil de workflow — il sépare les fils pour que chacun tienne naturellement. Le premier est un pansement ; le second est structurel.

Si votre tâche est « continuer à affiner cette même spec API pendant encore trois heures, juste moins verbeux » — compactez. Si votre tâche est « j'ai besoin de tester un prototype pour répondre à une question qui a émergé pendant la spécification de l'API » — handoff. Les confondre est l'erreur que j'ai faite pendant des semaines.

Il y a une heuristique encore plus simple que j'utilise maintenant. Demandez-vous : « La prochaine partie de cette conversation partagera-t-elle 80 %+ du contexte actuellement dans la fenêtre ? » Si oui, compactez. Si non, handoff. La plupart des fois où je recourais à compact auparavant, la réponse honnête était non.

Quand recourir à un handoff

Trois patterns ont gagné une place permanente dans mon workflow.

1. La tentation de la refactorisation en cours de session

Je suis plongé dans la construction de la feature A. Je remarque quelque chose dans un module partagé qui est clairement mal conçu — une fonction qui fait trois choses, un flag de configuration avec la mauvaise valeur par défaut, un test qui est silencieusement ignoré depuis six commits. L'ancien moi l'aurait corrigé tout de suite. La session actuelle aurait hérité de vingt messages sur cette refactorisation, dont la moitié serait encore dans la fenêtre quand je reviendrais à la feature A et que je devrais me rappeler ce que nous avions décidé sur ses cas limites.

Le nouveau moi écrit un handoff. « Refactoriser RoutePlanner.normalize() pour séparer la validation de chemin du formatage. Les tests dans tests/router/normalize.test.ts couvrent déjà les cas. Skills : brainstorming, TDD. » La session fraîche le prend, livre la refactorisation, revient propre. La session de la feature A reste dans la zone intelligente tout du long.

C'est le gain de workflow unitaire le moins cher que j'ai obtenu de tout changement d'outillage IA cette année. Le coût de polluer une session profonde avec une refactorisation non liée est bien plus élevé que le coût d'écrire un fichier de handoff.

2. Sessions d'interrogation qui se ramifient

Les sessions d'interrogation — exploration interactive guidée par les questions où je laisse Claude mettre un plan ou un design à l'épreuve — sont là où le handoff prouve vraiment sa valeur. Une bonne session d'interrogation va large exprès. Elle sonde les cas limites. Elle fait remonter des sous-questions. Et de temps en temps, une de ces sous-questions a besoin de sa propre session focalisée pour être réellement répondue.

Exemple de la semaine dernière. J'interrogeais un plan pour une nouvelle automatisation de cluster de contenu. À mi-chemin, Claude a demandé : « Avez-vous confirmé que le rendu markdown gère les admonitions imbriquées quand le post est chargé via votre CMS ? » Je ne l'avais pas fait. La réponse était un détour de quatre-vingt-dix minutes de prototypage que je ne voulais pas exécuter à l'intérieur de la session d'interrogation.

Handoff. « Prototype : alimenter trois posts de test avec admonitions imbriquées dans la prévisualisation locale du CMS et capturer la sortie de rendu. Skills : prototype, vérifier. Rapporter les résultats à la session d'interrogation sous forme d'un résultat d'un paragraphe. » La session de prototype tourne séparément, produit un résumé en markdown, la session d'interrogation lit ce résumé et continue sans avoir jamais chargé les posts de test ou les dépendances du renderer dans son propre contexte.

Ce second handoff — celui qui revient du prototype vers la session d'interrogation — est la partie qui m'a surpris. Les handoffs sont bidirectionnels. La session de prototype écrit ses résultats dans un document de handoff et les renvoie. La session d'interrogation lit trois paragraphes de réponse distillée, pas quatre-vingt-dix minutes d'essais et erreurs.

3. Sessions de planification se séparant des sessions de construction

L'autre pattern sur lequel je m'appuie fortement : séparer quoi construire de comment le construire. Les sessions de planification portent sur les décisions — ce qui est dans le périmètre, quel est le modèle de données, quels compromis comptent. Les sessions de construction portent sur l'exécution — écrire le code, lancer les tests, vérifier la sortie.

Ces deux activités se contaminent mutuellement quand elles partagent une fenêtre. Les conversations de planification engendrent des dizaines de petites ramifications « et si on faisait X » qui gonflent le contexte mais ne survivent pas à la décision. Les sessions de construction accumulent des sorties de tests, des messages d'erreur et des diffs de fichiers qui n'ont rien à voir avec la spécification originale.

Je les exécute maintenant en deux sessions. La session de planification produit un handoff : les décisions verrouillées, les questions ouvertes, le plan structurel. La session de construction prend ce handoff, exécute, et — si quelque chose pendant la construction invalide une décision de planification — écrit un handoff en retour. La session de planification rouvre, ingère le feedback et affine. Boucle jusqu'à ce que la session de construction n'ait plus rien à renvoyer.

C'est le même pattern d'itération que j'ai décrit dans l'article sur les agents de workflow spec, juste rendu portable entre sessions. Le handoff est ce qui fait tourner cette boucle sans que la fenêtre de contexte de quiconque ne se remplisse.

Ce qui va dans un bon fichier de handoff

Si vous ne lisez jamais qu'une seule section de cet article, que ce soit celle-ci.

Le document de handoff a un travail spécifique : donner à une session fraîche assez pour continuer le travail sans traîner le bruit que la session parente a accumulé. Ratez le contenu et vous aurez reconstruit le problème de /compact dans un nouveau fichier. Réussissez et la session fraîche arrive comme un ingénieur senior rejoignant un projet en plein sprint — briefé, orienté, productif en dix minutes.

Voici la structure que j'utilise maintenant pour chaque handoff, que le skill le génère ou que je l'édite à la main :

Deux patterns que les gens ratent quand ils écrivent des handoffs à la main :

Ne répétez pas ce qui est dans l'issue. S'il y a un issue GitHub avec la user story, les critères d'acceptation et la justification du design, le fichier de handoff devrait dire « voir issue #142 » — pas paraphraser l'issue. Paraphraser est le chemin par lequel la vérité dérive.

Soyez honnête sur les questions ouvertes. La tentation est de faire sonner le handoff comme complet. « On n'a plus qu'à livrer ça. » S'il y a des questions ouvertes, listez-les. La prochaine session les découvrira de toute façon, et vous voulez qu'elle les découvre dans la zone intelligente du nouveau contexte, pas après s'être déjà engagée dans une mauvaise direction.

Je garde un petit modèle mental. Objectif, ancre, état, verrouillé, ouvert, impasses, skills, démarrage, expurgations. Neuf sections. La plupart des miens font moins de 600 mots. Le but est qu'ils soient jetables — assez petits pour être lus en une minute, assez ciblés pour agir immédiatement.

Comment j'utilise les handoffs dans mon propre workflow

Laissez-moi concrétiser cela avec mon utilisation réelle sur mejba.me et le système de contenu Aria plus large.

Ma session typique de production de contenu a au moins trois phases. Rechercher le sujet. Planifier l'article. Écrire l'article. Chacune de ces phases veut des outils différents, un contexte différent, une attention différente. La phase de recherche ramène des résultats de recherche, des URL de concurrents scrapées et des statistiques. La phase de planification veut le fichier de voix de marque, la taxonomie de clusters et la carte de liens internes existante. La phase d'écriture veut le plan, la recherche et un éditeur vide.

Il y a quelques mois, j'ai essayé de faire les trois dans une seule session Claude Code. Au moment d'écrire le troisième article d'un cluster, le contexte avait ~80 000 tokens de recherche des articles un et deux qui flottaient encore, plus les plans des deux, plus les trois chargements de voix de marque, plus mes notes courantes. La qualité glissait visiblement dès le deuxième article.

Le nouveau flux ressemble à ceci :

1. Session de recherche — récupérer les données actuelles, trouver les lacunes, scanner les posts existants pour les liens internes. Produit un handoff : « Planifier un article sur X en utilisant ces 6 faits vérifiés, ces 3 cibles de liens internes et cet angle concurrentiel. » Fichier enregistré dans le répertoire temporaire.
2. Session de planification — fenêtre fraîche. Charge le handoff de recherche. La voix de marque et la carte de clusters arrivent propres. Produit un autre handoff : « Écrire un article sur X en suivant ce plan, en utilisant ces statistiques spécifiques, avec ces liens internes, en touchant ces accords émotionnels. »
3. Session d'écriture — encore une fenêtre fraîche. Charge le handoff de planification. Écrit l'article. Pas de résidus de recherche, pas de résidus de planification, juste le plan et un objectif.

Chaque session reste sous ~60K tokens, profondément dans la zone intelligente, concentrée sur sa tâche. La qualité de sortie est nettement meilleure que l'approche en une seule session, et les modes d'échec — quand quelque chose tourne mal — sont plus faciles à débugger parce que je peux lire chaque fichier de handoff et voir exactement ce qui a été transmis.

Pour le travail de code, je m'appuie sur la même division. Planifier l'architecture est une session. Construire le premier composant est une session. Construire le second est une session. Si la construction d'un composant soulève une question que l'architecture n'avait pas anticipée, c'est un handoff retour vers la session de planification. C'est la même logique qui rend les git worktrees avec agents parallèles et les sous-agents forkés si naturels — c'est tout le même principe : diviser le travail le long de frontières que le modèle peut garder distinctes, plutôt que de forcer le modèle à maintenir des frontières distinctes à l'intérieur d'un contexte gonflé.

Handoffs cross-outils : pourquoi Markdown a compté plus que je ne l'attendais

J'ai failli rejeter le choix de Markdown-comme-substrat comme une évidence. C'est le plus grand levier pratique de tout le skill.

Markdown est portable. Un fichier de handoff généré par Claude Code peut être lu par Codex CLI sans modification. Il peut être transmis à Copilot CLI. Il peut être chargé dans Gemini CLI. J'ai déplacé du travail entre trois outils d'agents différents dans un seul projet en passant simplement le même fichier Markdown. Pas de conversion de format, pas de code colle, pas de gymnastique SDK d'agents.

C'est là que les patterns de revue adversariale deviennent intéressants. J'ai déjà écrit sur l'exécution de la revue adversariale Codex contre la sortie de Claude Code. Le fichier de handoff est l'entrée parfaite pour ce pattern. Claude Code produit le travail et un handoff décrivant ce qu'il a fait et ce qui reste ouvert. Codex prend le handoff, exécute la critique, produit son propre handoff décrivant ce qu'il a trouvé. Claude Code reprend avec la critique en main. Chaque agent travaille dans sa zone intelligente. Le fichier Markdown est la seule chose qui doit traverser les frontières.

Même logique pour les sous-agents DIY. Vous n'avez pas besoin d'un orchestrateur multi-agents sophistiqué pour exécuter des tâches spécialisées en parallèle. Vous avez besoin d'un moyen de briefer un sous-agent, le laisser travailler et réintégrer ses résultats. Les handoffs Markdown font cela sans framework. Le « framework » c'est le fichier.

L'autre chose que Markdown vous donne : la revue-avant-envoi. Chaque handoff que j'écris reçoit un scan de trente secondes avant que je ne le transmette. Je vérifie les choses évidentes — l'expurgation a-t-elle capturé tous les secrets, les décisions verrouillées sont-elles vraiment verrouillées, a-t-il listé des impasses qui se sont avérées être le bon chemin finalement. Cette étape de revue a attrapé au moins trois mauvais handoffs le mois dernier. JSON ou blobs binaires ne vous permettent pas de faire ça.

Ce que le handoff n'est pas

Il vaut la peine d'être honnête sur les limites, car le skill n'est pas une réponse universelle.

Le handoff ne remplace pas une bonne discipline en session. Si vous laissez une session s'étaler sur six sujets sans rapport sans jamais diviser, le skill de handoff ne vous sauvera pas. Il vous donnera juste un résumé légèrement plus propre de la session étalée à la fin. La discipline de reconnaître quand diviser est la vôtre — le skill rend simplement la division peu coûteuse une fois que vous vous y engagez.

Le handoff n'est pas pour les tâches trivialement courtes. Si tout le travail tient dans 20K tokens et une session, vous feriez mieux de le terminer que d'écrire un handoff. La surcharge du format de handoff n'est pas gratuite. Je l'utilise quand le travail va réellement s'étendre sur plusieurs sessions, pas comme cérémonie.

Le handoff ne répare pas les artefacts upstream défectueux. Si vos ADR sont faux, vos modèles d'issues sont vagues et vos plans sont approximatifs, le handoff le reflétera. Les références ne valent que ce à quoi elles pointent. J'ai remarqué que mes propres ADR sont devenus plus précis après que j'ai commencé à écrire des handoffs qui les référençaient — savoir que la prochaine session lirait ces documents à froid m'a fait les écrire mieux.

Le handoff n'est pas un substitut à la vérification. Un handoff dit « nous en sommes arrivés là ». Il ne prouve pas que le code fonctionne. Les sessions fraîches doivent quand même lancer les tests, quand même vérifier avant de revendiquer l'achèvement. Le handoff décrit l'intention et l'état. La réalité doit encore être vérifiée.

Le résumé honnête : le handoff est un outil de coordination. Il coordonne le travail entre sessions qui autrement partageraient mal le contexte. Il ne remplace pas le travail lui-même, la vérification du travail, ni les documents upstream dont le travail dépend.

Ce qui change quand vous commencez à travailler de cette façon

Quelques patterns que j'ai remarqués dans mon propre travail depuis que le handoff est devenu routine.

Je planifie davantage avant de construire. Savoir que je devrai écrire un handoff à la fin de la session de planification me force à réellement terminer le plan au lieu de dériver vers « laissez-moi juste essayer la première chose ». Si je vais remettre ça à une session de construction, le plan doit être assez complet pour agir dessus. C'est une fonction contraignante que l'approche en une seule session n'avait pas.

Je remarque le scope creep plus vite. En cours de session, quand je me surprends à penser « laissez-moi aussi corriger rapidement ce truc » — cette pensée devient maintenant réflexivement « laissez-moi écrire un handoff pour ça ». Le coût d'une excursion latérale dans la session actuelle est élevé. Le coût d'écrire un handoff et de continuer mon travail actuel est faible. Le calcul penche vers la concentration.

Mes sessions sont plus courtes. Je faisais tourner des sessions Claude Code d'une heure comme habitude. Maintenant la plupart des sessions durent 20 à 40 minutes. Le travail est le même ; les sessions correspondent simplement au périmètre réel de la tâche au lieu de regrouper trois tâches dans une fenêtre.

Je fais davantage confiance à mes agents. Quand une session fraîche charge un handoff rigoureux et poursuit le travail proprement, la sortie semble plus fiable que quand une seule session tourne depuis une heure et que le modèle se souvient à moitié de ce que nous avions décidé. La zone intelligente est réelle. Garder le travail dedans est un investissement de qualité, pas un impôt.

Questions Fréquentes

Qu'est-ce que le skill de handoff dans Claude Code ?

Le skill de handoff compresse le contexte pertinent d'une session Claude Code dans un fichier Markdown qu'une session fraîche peut utiliser pour poursuivre le travail sans hériter de la surcharge de contexte. Il enregistre le fichier dans le répertoire temporaire du SE, référence les documents existants au lieu de les dupliquer, expurge les données sensibles et suggère quels skills la prochaine session devrait utiliser. Pour la configuration complète et les patterns d'utilisation, voir la section workflow ci-dessus.

En quoi le handoff diffère-t-il de /compact ?

/compact résume la session actuelle et remplace son historique par le résumé, vous gardant dans la même conversation. handoff produit un fichier Markdown portable cadré sur l'objectif spécifique de la prochaine session, puis vous permet de repartir à zéro. Compact sert à raccourcir une longue tâche ; handoff sert à répartir du travail non lié entre plusieurs sessions.

Quand devrais-je utiliser le handoff au lieu de simplement poursuivre la session ?

Utilisez le handoff quand la prochaine portion de travail partage moins de 80 % du contexte actuellement dans votre fenêtre — refactorisations en cours de session de code non lié, spikes de prototypage qui bifurquent d'une session d'interrogation, ou séparation de la planification et de l'exécution. Si le travail est une continuation directe de ce que vous faites déjà, la compaction est généralement le meilleur choix.

Quelle est la fenêtre de contexte pratique avant que Claude Code ne commence à se dégrader ?

Le plafond de 1M tokens de Claude Code est le chiffre marketing. La dégradation pratique de qualité commence typiquement autour de 120 000 tokens, certaines équipes rapportant une dérive notable dès 50 % de la fenêtre. Budgétiser l'attention dans la zone intelligente compte plus que le plafond lui-même.

Puis-je utiliser le handoff avec différents agents de codage IA ?

Oui. La sortie du handoff est du Markdown simple, ce qui la rend portable entre Claude Code, Codex CLI, Copilot CLI, Gemini CLI et tout autre agent qui lit du texte. C'est ce qui permet des patterns cross-agents comme l'exécution de la revue adversariale Codex contre la sortie de Claude Code sans écrire de code colle personnalisé.

Travaillons Ensemble

Vous cherchez à construire des systèmes IA, automatiser des workflows ou faire évoluer votre infrastructure technique ? Je serais ravi de vous aider.

• Fiverr (développements sur mesure & intégrations) : fiverr.com/s/EgxYmWD
• Portfolio : mejba.me
• Ramlit Limited (solutions entreprise) : ramlit.com
• ColorPark (design & branding) : colorpark.io
• xCyberSecurity (services de sécurité) : xcybersecurity.io