Modèle de handoff Claude Code : garder le contexte pour la prochaine personne ou le prochain agent

Claude Code devient beaucoup plus utile quand une session peut survivre à un handoff. Le problème classique n’est pas que l’agent ne trouve pas les fichiers. Il les trouve, lit le diff, élimine plusieurs hypothèses, applique parfois une partie du correctif, puis la session se termine avec “on continue demain”. La personne suivante doit alors reconstruire le contexte.

Dans cet article, handoff signifie une note de passation courte et opérationnelle. Elle permet à un humain ou à un agent IA de reprendre sans relire toute la conversation. Elle contient l’objectif, l’état actuel, les fichiers importants, les preuves de vérification, les risques restants et le prochain prompt à donner à Claude Code.

Pour la base officielle, garde la documentation Claude Code ouverte. How Claude Code works explique la boucle agentique, l’accès au projet, l’état git, les sessions et le contexte. Memory explique CLAUDE.md et les instructions de projet. CLI reference couvre l’usage en ligne de commande. Côté ClaudeCodeLab, lis aussi CLAUDE.md best practices, verification receipt workflow et team handoff rules.

Le bon découpage

Les débutants mélangent souvent CLAUDE.md et la note de handoff. CLAUDE.md doit contenir les règles durables du projet : commandes de build, standards de code, conventions d’architecture, politique de revue et chemins sensibles.

La note de handoff contient l’état temporaire de la tâche. Elle dit ce qui s’est passé aujourd’hui : quelle hypothèse était fausse, quels fichiers comptent, ce qui a été vérifié, ce qui ne l’a pas été et quelle action lancer ensuite. En français simple, le contexte est l’arrière-plan de travail, le verification receipt est le reçu de vérification, et le harness est le cadre qui aide l’agent à travailler dans les bonnes limites.

flowchart LR
  A["Goal<br/>Quel résultat vise-t-on"] --> B["Current state<br/>Où s'est-on arrêté"]
  B --> C["Evidence<br/>Qu'est-ce qui est vérifié"]
  C --> D["Risk<br/>Qu'est-ce qui reste incertain"]
  D --> E["Next prompt<br/>Que demander d'abord"]

Avec cette chaîne, la session suivante peut démarrer par une action utile au lieu de relire tout l’historique.

Modèle Markdown à copier

# Claude Code session handoff

## Goal
- target outcome:
- explicitly out of scope:

## Current state
- branch:
- dirty files:
- related URL:
- what is known:

## What changed
- changed files:
- reason for change:
- important files not touched:

## Verification receipt
- commands run:
- result:
- manual checks:
- not checked:

## Risks and constraints
- fragile area:
- do not touch:
- requires approval:

## Next prompt
In the next session, compare git status with this handoff, then continue from the unchecked verification items.

Le champ le plus important est not checked. Un build local qui passe ne prouve pas que l’URL publique, la vue mobile, le lien de CTA, l’événement analytics ou la traduction sont corrects. Déclarer ce qui manque évite de transmettre une fausse impression de fin.

Exemple JSON structuré

Si ton équipe envoie les handoffs dans GitHub Issues, Slack, Notion ou un tableau interne, ajoute un résumé JSON à côté de la note Markdown.

{
  "slug": "claude-code-session-handoff-template",
  "goal": "Improve the published multilingual article group",
  "status": "draft updated, verification pending",
  "files": [
    "site/src/content/blog/claude-code-session-handoff-template.mdx",
    "site/src/content/blog-en/claude-code-session-handoff-template.mdx"
  ],
  "checksRun": ["frontmatter parse", "code fence scan"],
  "checksMissing": ["production URL check"],
  "nextAction": "Run targeted validation and review locale copy"
}

JSON est utile pour les outils, mais il ne porte pas bien le raisonnement. Mets les décisions et les raisons dans Markdown. Mets l’état lisible par machine dans JSON.

Script Node.js exécutable

Enregistre ce fichier sous scripts/write-handoff.mjs. Il n’utilise que les modules intégrés de Node.js, lit l’état git courant et écrit un fichier daté dans handoffs/.

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

function run(command) {
  try {
    return execSync(command, { encoding: "utf8" }).trim() || "(no output)";
  } catch (error) {
    return `ERROR: ${error.message}`;
  }
}

const date = new Date().toISOString().slice(0, 10);
const branch = run("git branch --show-current");
const status = run("git status --short");
const recentCommit = run("git log -1 --oneline");
const outDir = "handoffs";
const outFile = join(outDir, `${date}-session-handoff.md`);

mkdirSync(outDir, { recursive: true });

const body = `# Claude Code session handoff

## Goal
-

## Current state
- branch: ${branch}
- recent commit: ${recentCommit}
- dirty files:
\`\`\`text
${status}
\`\`\`

## What changed
-

## Verification receipt
- commands:
- result:
- missing:

## Risks and constraints
-

## Next prompt
Read this handoff, compare it with git status, and continue from the missing verification items.
`;

writeFileSync(outFile, body, "utf8");
console.log(`Wrote ${outFile}`);

Vérifie la syntaxe, puis lance le script :

node --check scripts/write-handoff.mjs
node scripts/write-handoff.mjs

Cas d’usage concrets

Premier cas : la publication de contenu multilingue. Un même slug peut avoir des fichiers japonais, anglais, chinois, coréen, espagnol, français, allemand, portugais, hindi et indonésien. La difficulté est de savoir quelles locales doivent encore être relues, scannées contre le mojibake, contrôlées pour la longueur de description, les liens internes et les CTA vers /products/ et /training/.

## Goal
- raise the 10-locale article group for slug claude-code-session-handoff-template to publish quality

## Current state
- Japanese canonical body updated
- English and Indonesian reviewed for natural tone
- zh, ko, and hi still need mojibake scan

## Verification receipt
- frontmatter parse: pass
- JSON code block parse: pass
- production URL: not checked

## Next prompt
Check the remaining locale files for mojibake, description length, and missing CTA links. Report only unresolved items.

Deuxième cas : une investigation de bug interrompue. Si la vraie découverte est “à 390px, le CTA déborde car la carte de prix garde un min-width fixe”, écris cette phrase. “CSS vérifié” oblige la personne suivante à refaire le travail.

Troisième cas : une revue de code risquée. Authentification, paiement, migration de base de données et permissions exigent une note qui précise les risques déjà vus, les tests manquants et la personne qui doit approuver.

Quatrième cas : le travail parallèle de plusieurs humains ou agents. Si d’autres workers modifient d’autres slugs ou branches, le handoff doit préciser les fichiers autorisés et les fichiers à ne pas toucher.

Pièges fréquents

Piège 1 : lister des chemins sans raison. site/src/pages/products.astro est moins utile que “le min-width de la carte de prix crée un overflow à 390px”.

Piège 2 : ne noter que les vérifications réussies. npm run build peut passer alors que l’URL publique, le mobile, le tracking de clics, le formulaire ou la traduction ont encore un problème.

Piège 3 : écrire un résumé de conversation trop long. Si la prochaine action n’est pas claire, la note ajoute de la lecture sans réduire le risque.

Piège 4 : coller des informations privées. Ne mets pas d’API key, de données client, de prix interne ou de lien d’incident privé dans une note réutilisable.

CTA et monétisation

Sur un site comme ClaudeCodeLab, la qualité technique inclut aussi le parcours de monétisation. Si l’article perd ses liens internes, ressources gratuites, pages produit ou consultation, le lecteur n’a plus de prochaine étape claire. Un lecteur solo peut commencer par la fiche gratuite. Pour des modèles et checklists prêts à adapter, regarde products. Pour une équipe qui veut mettre CLAUDE.md, permissions, revues, verification receipts et handoffs dans un vrai dépôt, passe par Claude Code training and consultation.

Le rituel prend 30 secondes : objectif, état actuel, preuve, vérifications manquantes et prochain prompt. Dans le workflow de publication de Masa, ce modèle a surtout réduit le temps perdu à retrouver où la session précédente s’était arrêtée.