Installer la commande /handoff dans Claude Code
La commande /handoff est une commande personnalisée qui clôture proprement une session de travail : elle fait le bilan, sauvegarde la mémoire du projet sur disque, puis compacte le contexte. Installée au niveau personnel, elle est disponible dans tous tes projets, sans avoir à la recopier à chaque fois.
Le principe en une phrase
Une commande personnalisée dans Claude Code, c'est simplement un fichier Markdown. Tu le déposes dans un dossier précis, et le nom du fichier devient le nom de la commande. Le fichier handoff.md devient la commande /handoff.
Projet ou personnel : quelle différence ?
Il existe deux emplacements possibles, selon la portée que tu veux donner à la commande.
Commande projet — stockée dans .claude/commands/ à l'intérieur d'un projet. Elle n'est disponible que dans ce projet, mais elle se partage avec ton équipe via le dépôt Git.
Commande personnelle — stockée dans ~/.claude/commands/ dans ton dossier personnel. Elle te suit sur tous tes projets, sur ta machine. C'est ce qu'on veut ici.
Installation pas à pas
Ouvre un terminal et crée le dossier des commandes personnelles s'il n'existe pas déjà :
mkdir -p ~/.claude/commandsPlace le fichier handoff.md dans ce dossier. Tu peux le déplacer depuis ton dossier de téléchargements :
mv ~/Downloads/handoff.md ~/.claude/commands/C'est tout. La commande est active. Au prochain démarrage de Claude Code, tape / dans la session : la commande /handoff apparaît dans la liste, avec sa description.
Vérifier que ça fonctionne
Dans n'importe quel projet, ouvre une session Claude Code et tape /. Le menu d'autocomplétion liste toutes les commandes disponibles, y compris les tiennes. Si /handoff y figure, l'installation est bonne. Tu peux aussi lancer /help pour voir l'ensemble des commandes.
Brancher la mémoire au démarrage
La commande /handoff écrit la mémoire du projet dans .claude/memory/, mais elle ne la recharge pas toute seule à la session suivante. Pour ça, il faut ajouter un bloc d'instructions dans ton fichier CLAUDE.md (le fichier de contexte que Claude Code lit automatiquement au démarrage).
Ce bloc dit à Claude de lire les fichiers de mémoire de travail à l'ouverture, et de ne consulter l'archive d'historique que sous conditions précises. Sans lui, le handoff écrit dans le vide : les fichiers existent mais ne sont jamais relus.
Comment l'utiliser au quotidien
En fin de session, quand tu estimes avoir atteint un palier ou que le contexte devient lourd, tape simplement :
/handoffClaude analyse la session, statue sur les objectifs, extrait les apprentissages, met à jour les fichiers de mémoire, archive le détail dans l'historique, te montre un résumé, puis compacte le contexte. La session suivante repart légère, sans rien perdre de l'essentiel.
Bon à savoir
Le déclenchement automatique de /compact en fin de commande dépend de ta version de Claude Code. Si Claude s'arrête après le résumé et te laisse lancer /compact toi-même, c'est normal : tape la commande à la main, tu ne perds que deux secondes.
Le format .claude/commands/ est aujourd'hui considéré comme historique. Le format recommandé pour les nouveaux usages est le skill (.claude/skills/). Pour une commande de clôture que tu veux déclencher manuellement, le format commande reste parfaitement adapté. Si le format venait à être retiré un jour, le même contenu se migre sans difficulté vers un skill.
Fichier /handoff
---
description: Fait le bilan de la session, persiste la mémoire de travail sur disque, puis compacte le contexte.
---
# /handoff — Passation de fin de session
Tu vas clôturer proprement la session de travail en cours. L'objectif : sauvegarder l'essentiel sur disque **avant** de compacter le contexte, pour qu'une prochaine session reparte légère sans rien perdre d'important.
Les fichiers de mémoire vivent dans `.claude/memory/`. Crée le dossier et les fichiers s'ils n'existent pas encore.
Exécute les étapes **dans l'ordre**. Ne saute aucune étape. Ne compacte qu'à la toute fin.
---
## Étape 1 — Analyser la session
Relis la conversation en cours. Identifie, factuellement :
- ce qui a été tenté, décidé, produit, modifié, cassé
- les choix techniques importants et leur raison
- ce qui a échoué et pourquoi
Ne romance rien. Tu décris ce qui s'est passé, pas ce qui aurait dû se passer.
## Étape 2 — Statuer sur les objectifs
Lis `.claude/memory/objectives.md` (s'il existe). Pour chaque objectif, statue : **atteint / en cours / abandonné**. Ajoute les nouveaux objectifs apparus pendant la session.
Règle non négociable : **distingue ce que tu peux vérifier de ce que tu supposes.**
- Un objectif n'est "atteint" que si une **preuve vérifiable** l'établit : suite de tests qui passe, build qui réussit, lint propre. Si tu as accès à ces commandes, lance-les plutôt que de te fier à ton impression.
- Si tu ne peux pas le prouver, marque-le `en cours (non vérifié)` — jamais `atteint`.
Ne te félicite pas sur la base d'une impression. Une mémoire qui s'auto-congratule est inutile.
## Étape 3 — Extraire les apprentissages
Sépare deux natures de leçons :
- **Ce qui marche et qu'il faut refaire** → destiné à `playbook.md`
- **Ce qu'il ne faut pas refaire** → destiné à `antipatterns.md`
Reformule chaque leçon en **règle actionnable**, pas en anecdote.
- ❌ "Cette fois on a écrit les tests avant et ça a bien marché."
- ✅ "Écrire les tests d'acceptation avant le code : réduit les allers-retours."
Si une leçon n'est pas réutilisable telle quelle dans une prochaine session, elle ne va pas dans ces fichiers (elle ira dans l'historique à l'étape 5).
## Étape 4 — Réécrire les fichiers vivants
Ces trois fichiers doivent rester **courts**. Tu les **réécris** entièrement, tu n'empiles pas. Si une ligne est devenue fausse ou obsolète, supprime-la.
**`.claude/memory/objectives.md`**
```
# Objectifs
## Atteints
- ...
## En cours
- ...
## À venir
- ...
```
**`.claude/memory/playbook.md`**
```
# Playbook — à refaire
- [Règle actionnable] — [bénéfice court]
```
**`.claude/memory/antipatterns.md`**
```
# Anti-patterns — à NE PAS refaire
- NE PAS [action] — [raison courte : ce que ça casse]
```
Dans ces fichiers, les raisons sont **courtes**. Le "pourquoi" détaillé va dans l'historique, pas ici.
## Étape 5 — Appender à l'historique
Ajoute **une seule entrée datée** à `.claude/memory/history.md` (append-only, ne réécris jamais ce fichier). C'est ici que va le détail verbeux : le récit de la session, les choix et leurs raisons longues, les erreurs et leur contexte.
```
## [AAAA-MM-JJ HH:MM] — [titre court de la session]
### Fait
- ...
### Décisions et pourquoi
- ...
### Erreurs et causes
- ...
```
## Étape 6 — Confirmer avant de compacter
Affiche un **résumé court** de ce que tu viens d'écrire :
- objectifs : X atteints, Y en cours, Z abandonnés
- N règles ajoutées au playbook
- N anti-patterns ajoutés
- entrée historique enregistrée
Puis vérifie une dernière fois que les quatre fichiers sont bien à jour sur disque. **Ne passe à l'étape 7 que si l'écriture est confirmée.** Si quelque chose a échoué à l'écriture, arrête-toi ici et signale-le — ne compacte pas.
## Étape 7 — Compacter
Seulement maintenant, et seulement si l'étape 6 est validée, déclenche le compactage du contexte :
`/compact`IMPORTANT lignes à mettre dans ton claude.md
## Mémoire de projet (.claude/memory/)
Au **démarrage de chaque session**, lis ces trois fichiers s'ils existent. Ils constituent l'état courant du projet :
- `.claude/memory/objectives.md` — objectifs atteints / en cours / à venir
- `.claude/memory/playbook.md` — pratiques qui marchent, à refaire
- `.claude/memory/antipatterns.md` — pratiques à NE PAS refaire, et pourquoi
Ces trois fichiers sont la **mémoire de travail** : courts, à jour, prioritaires. Respecte les `antipatterns.md` comme des contraintes dures, pas comme des suggestions.
### Historique — NE PAS charger par défaut
`.claude/memory/history.md` est une **archive append-only**. Ne la lis **jamais en entier** au démarrage : elle est longue et coûteuse en contexte.
Consulte-la (par recherche ciblée, pas lecture complète) **uniquement** dans ces cas :
1. L'utilisateur le demande explicitement (ex : "relis l'historique", "pourquoi on avait décidé X", "fais un rapport de l'historique").
2. Tu t'apprêtes à retravailler une décision ou un composant référencé dans `playbook.md` ou `antipatterns.md`, et tu as besoin du raisonnement complet qui a mené à cette règle. Dans ce cas, cherche l'entrée datée correspondante et lis **seulement** celle-là.
En dehors de ces deux cas, ignore `history.md`.
### Clôturer une session
Pour faire le bilan et sauvegarder la mémoire avant de compacter, lance la commande `/handoff`.