Claude Code : bonnes pratiques — planification, transfert de contexte, TDD

Claude Code réclame une forme de discipline que la plupart des outils de développement n’exigent pas. Si vous l’utilisez depuis quelque temps, vous avez sans doute remarqué que certaines sessions livrent exactement ce que vous souhaitez, quand d’autres consument des jetons sans aboutir. L’équipe d’Anthropic a constaté qu’en l’absence de guidage, les tentatives aboutissent environ 33 % du temps, et le créateur de l’outil abandonne 10 à 20 % des sessions. 

La différence tient aux cadres que vous mettez autour de l’outil, pas aux prompts que vous tapez.

Cet article présente à quoi ressemblent ces cadres dans la pratique, en s’appuyant sur des workflows de production chez Abnormal AI, incident.io et Trail of Bits. 

Si vous avez besoin d’un rappel sur la configuration et les fonctionnalités clés, notre guide sur Claude Code 2.1 couvre l’essentiel. Nous partons ici du principe que vous connaissez déjà les bases et cherchez à tirer davantage parti de l’outil.

Pour une vue d’ensemble du raisonnement des agents et de la place de ces schémas, je vous recommande vivement de suivre notre parcours AI Agent Fundamentals, qui en expose tous les principes sous-jacents.

Pourquoi la discipline de planification change tout

Chaque décision que Claude prend sans guidage peut être correcte avec une forte probabilité, ce qui semble acceptable isolément. Mais, cumulée sur une fonctionnalité avec de nombreux points de choix, la probabilité d’un résultat parfaitement juste s’effondre. En supposant 80 % de justesse sur 20 décisions, on obtient 0,8^20, soit à peine ~1 % de chances d’une implémentation entièrement correcte.

La planification condense ces 20 décisions ambiguës en une spécification relue où chacune frôle les 100 %… car vous avez déjà tranché.

Planifier avec le workflow en cycle d’annotations

Le workflow de planification le plus efficace à l’échelle est le cycle d’annotations, comme le propose Boris Tane. Vous faites rédiger à Claude un plan.md, vous l’ouvrez dans votre éditeur et vous ajoutez des notes en ligne partout où Claude s’est trompé ou a laissé une zone d’ombre : « utiliser drizzle:generate, pas du SQL brut » ou « ce doit être PATCH, pas PUT. » 

Ensuite, vous renvoyez le plan annoté avec la phrase de garde : « address all notes, don't implement yet. » Cette consigne est cruciale : sans elle, Claude saute le plan et code immédiatement. Vous répétez jusqu’à lever toute ambiguïté, puis Claude implémente avec bien moins d’erreurs de trajectoire, car toutes les décisions ont déjà été prises.

# plan.md — annotation cycle
 
## Step 3: Database migration
Create a new migration for the users table.
> NOTE: use drizzle:generate, not raw SQL
> NOTE: add created_at with default NOW()
 
## Step 4: API endpoint
Add PUT /users/:id endpoint.
> NOTE: this should be PATCH, not PUT. Partial updates only.
 
# After annotating, send back with:
# "address all notes, don't implement yet"Propulsé par

Utiliser le plan mode de Claude Code

Si le cycle d’annotations vous semble trop lourd, le plan mode intégré de Claude Code est une alternative plus légère : 

1. Appuyez deux fois sur Shift+Tab.
2. Faites évoluer le plan en conversation.
3. Passez en acceptation automatique avec Shift+Tab une fois. 

Les plans sont enregistrés dans ~/.claude/plans/, ils survivent donc au compactage et au redémarrage de session, ce qui en fait un excellent défaut pour la plupart des tâches. Pour de très grandes fonctionnalités, rédiger d’emblée une spécification complète fonctionne très bien : un développeur a passé deux heures sur une spec en 12 étapes et a économisé 6 à 10 heures d’implémentation.

Aller plus loin dans la planification

Quelle que soit l’approche, coller du bon code open source en référence avec la demande de plan améliore nettement le résultat : Claude préfère une base concrète à des descriptions abstraites.

La planification se parallélise aussi via des worktrees git. Chez incident.io, des ingénieurs lancent 4 à 5 sessions Claude en parallèle sur des branches distinctes, chacune suivant son propre plan. Un ingénieur a dépensé 8 $ de crédit Claude et livré une implémentation qui a amélioré de 18 % le temps de génération d’API, soit 30 secondes gagnées sur un outil utilisé quotidiennement par toute l’équipe. 

Certains vont plus loin encore en lançant des worktrees concurrents, chacun testant une approche différente du même problème pour comparer les résultats.

Bonnes pratiques d’architecture pour CLAUDE.md

Votre fichier CLAUDE.md a un budget que vous ne soupçonnez peut‑être pas. L’analyse de HumanLayer sur l’interne de Claude Code a montré que le système ajoute au-dessus de vos instructions un rappel : « This context may or may not be relevant to your tasks. » 

Comprendre le système d’instructions en couches de Claude Code

Claude filtre activement ce qu’il suit plutôt que de traiter chaque règle comme un ordre persistant. En outre, les modèles de pointe suivent environ 150 à 200 instructions avant que la conformité ne chute, et le prompt système de Claude Code en consomme environ 50. Il vous reste donc grosso modo 100 à 150 créneaux pour vos règles. HumanLayer maintient son propre fichier sous 60 lignes.

Vous pouvez observer ce budget à l’œuvre. Ajoutez à votre CLAUDE.md « always address me as Mr. Tinkleberry » et voyez à quelle vitesse Claude cesse de l’appliquer, souvent en quelques milliers de jetons. Quand le nom disparaît, vos instructions sont dépriorisées par le mécanisme d’attention, et tout le reste de votre CLAUDE.md perd de l’influence avec.

Utiliser la divulgation progressive pour les références

La bonne stratégie dans ce budget : la divulgation progressive. Votre CLAUDE.md racine reste court et centré sur les règles universelles. Pour tout ce qui est spécifique à un domaine, référencez un fichier séparé sans l’inclure en ligne : « Quand vous travaillez sur le système de paiement, lisez d’abord docs/payment-architecture.md. » 

Claude ne lit le fichier référencé que lorsqu’il entre dans cette zone du code, ce qui préserve votre budget d’instructions pour les règles prioritaires. Une entreprise consommant des milliards de jetons par mois structure son CLAUDE.md de monorepo ainsi, avec un budget de jetons alloué à chaque équipe :

# Monorepo CLAUDE.md — progressive disclosure
 
## Python
- Always use type hints for function signatures
- Test with: pytest -x --tb=short
 
## <Internal CLI Tool>
- <usage example>
- Always validate input before processing
- Never use raw SQL, prefer the ORM
For <complex usage> or <error> see path/to/<tool>_docs.mdPropulsé par

Des fichiers CLAUDE.md dans les sous-répertoires prolongent ce dispositif. Placez un CLAUDE.md dans src/persistence/ avec les consignes propres à la base de données, un autre dans src/api/ avec les conventions d’endpoints. 

Claude charge automatiquement les CLAUDE.md du répertoire courant vers la racine du projet, donc ceux des sous-dossiers ne s’activent que quand Claude travaille dans cette zone. Votre fichier racine reste général, et Claude reçoit des consignes ciblées là où il en a besoin.

Erreur fréquente : n’@-incluez pas la documentation dans CLAUDE.md. Cela embarque le fichier entier à chaque exécution, et consomme votre budget avant même de commencer.

Gestion du contexte dans Claude Code

Claude Code offre 200 000 jetons de contexte, mais la fenêtre réellement exploitable est plus petite qu’il n’y paraît. 

Une session monorepo fraîche consomme environ 20 000 jetons pour charger le prompt système, les définitions d’outils et le CLAUDE.md avant même que vous ne tapiez quoi que ce soit. Chaque serveur MCP ajoute des schémas d’outils qui occupent le contexte en permanence ; en pratique, 5 à 8 serveurs suffisent pour commencer à empiéter sur le travail réel.

Pire : la qualité baisse tôt. Plusieurs praticiens convergent vers le même seuil : ne laissez pas le contexte dépasser 60 % de capacité. 

La sortie de Claude se dégrade dès 20 à 40 % de la fenêtre, bien avant toute limite, car le mécanisme d’attention accorde moins de poids aux premières instructions à mesure que le contexte se remplit. 

L’auto‑compactage se déclenche vers 83,5 % et il est destructif : un développeur a perdu 3 heures de refactoring quand le système a effacé en milieu de session toutes les décisions de migration, ne conservant que 20 à 30 % des détails.

Adopter le schéma Documenter & Réinitialiser

La meilleure parade est le schéma Documenter & Réinitialiser. Quand le contexte devient lourd : 

1. Déversez votre plan et l’avancement dans un fichier markdown

2. Lancez /clear pour réinitialiser la session

3. Redémarrez en demandant à Claude de lire ce fichier

Ainsi, vous récupérez une fenêtre complète de 200 K avec uniquement ce que vous choisissez de préserver, ce qui est supérieur à /compact, car vous contrôlez exactement ce qui survit. 

Une commande personnalisée /catchup fluidifie la transition : après réinitialisation, elle lit tous les fichiers modifiés dans la branche git courante, et Claude reprend là où vous vous êtes arrêté, sans l’historique de conversation.

<!-- .claude/commands/catchup.md -->
Rebuild context after a /clear. Read all files modified on the
current branch compared to main. For each file, understand the
changes made. Then summarize what's been implemented so far and
what work remains.
 
Changed files on this branch:
$ git diff --name-only mainPropulsé par

Transférer le contexte avec des skills personnalisés

J’utilise un /transfer-context skill pour aller plus loin. Quand une session se dégrade, la commande génère un fichier de passation structuré listant le travail accompli, les décisions ouvertes, les pièges à éviter et les chemins de fichiers pertinents. La session suivante lit ce fichier et reprend exactement où la précédente s’était arrêtée, avec uniquement l’information utile et sans bloat de conversation.

Autres bonnes pratiques pour économiser le contexte

Vous pouvez aussi préserver le contexte en chargeant les outils à la demande. Un projet a récupéré environ 15 000 jetons par session grâce à des hooks UserPromptSubmit qui injectent les définitions de skills uniquement quand le prompt de l’utilisateur déclenche des mots‑clés pertinents, plutôt que de tout précharger au démarrage.

La règle la plus simple : une tâche par conversation. Repartir de zéro coûte 20 000 jetons, un coût dérisoire face à la perte de qualité d’une session polluée.

Les hooks Claude Code comme garde‑fous déterministes

Même un CLAUDE.md bien structuré n’est suivi qu’à environ 70 %. Pour des préférences de style de code, c’est acceptable. Pour des règles de sécurité comme « ne pas pousser sur main » ou « ne pas supprimer des données de production », non. Les hooks comblent ce fossé à 100 % en exécutant des scripts shell à des moments précis du flux Claude.

Deux types sont à connaître. Les hooks « Block‑at‑Submit » s’exécutent en PreToolUse et stoppent net une action : un code de sortie 2 bloque l’action et force Claude à tenter autre chose. Les hooks « Hints » fournissent un feedback non bloquant, par exemple en lançant un linter après chaque édition et en renvoyant la sortie sans interrompre le flux.

La configuration publique la plus complète fait notamment :

• Bloque les commandes rm -rf (en suggérant trash), 

• Empêche les pushes directs sur main, 

• Journalise toutes les mutations avec horodatage, et 

• Exécute une barrière anti‑rationalisation. 

Cette barrière utilise Haiku pour passer en revue les réponses de Claude et détecter les échappatoires du type « problèmes préexistants » ou « hors périmètre ». Quand Claude crie victoire trop tôt, la réponse est rejetée avec un retour précis et l’agent est forcé de poursuivre. Une variante plus légère lance automatiquement Prettier et les vérifications TypeScript après chaque édition :

{
  "hooks": {
	"PostToolUse": [
  	{
    	"matcher": "Edit|Write",
    	"hooks": [
      	{
        	"type": "command",
        	"command": "prettier --write \"$CLAUDE_FILE_PATHS\""
      	}
    	]
  	}
	]
  }
}Propulsé par

Un piège à éviter : ne bloquez jamais les outils Edit ou Write en plein plan. Bloquer à l’écriture casse le raisonnement multi‑étapes, Claude perd le fil. Laissez‑le terminer l’écriture, puis validez via des hooks PostToolUse ou des contrôles pré‑commit. Notre tutoriel sur les hooks Claude Code présente d’autres schémas pour aller plus loin.

Le développement piloté par les tests, stratégie optimale pour le codage agentique

Sans tests, la seule façon pour Claude de vérifier son travail est son propre jugement, qui se dégrade à mesure que le contexte se remplit. Les tests fournissent un oracle externe qui reste fiable quelle que soit la durée de la session. 

Chaque cycle rouge→vert donne à Claude un retour sans ambiguïté, et il peut itérer sur toute la suite sans intervention humaine, ce qui fait du test‑driven development (TDD) le schéma le plus robuste pour travailler avec des outils de codage agentiques.

Le workflow recommandé par Anthropic suit une séquence précise :

1. Write tests first
   > "Write tests for the auth module using pytest.
  	TDD approach, no mock implementations."
 
2. Confirm tests fail
   > "Run the tests. They should all fail."
 
3. Commit the failing tests as a checkpoint
 
4. Implement until green
   > "Write the implementation. Do not modify the tests.
  	Keep going until all tests pass."Propulsé par

La dernière instruction est plus importante qu’elle n’en a l’air. Il arrive que Claude modifie les tests pour les faire passer plutôt que de corriger l’implémentation. Valider les tests au préalable vous donne un filet de sécurité : si Claude les change, le diff montre exactement quoi, et vous pouvez revenir en arrière.

Pour le frontend, une variante visuelle fonctionne très bien : si vous fournissez une maquette et un serveur MCP Puppeteer, Claude prend une capture après implémentation, la compare à la maquette et itère. Cette boucle de vérification améliore la qualité d’un facteur 2 à 3 lorsque Claude peut contrôler sa sortie face à une cible visuelle.

Économie des coûts et choix de modèles pour Claude Code

Les données officielles d’Anthropic estiment le coût moyen de Claude Code à 6 $ par développeur et par jour au tarif API, 90 % des développeurs restant sous les 12 $/jour. Au mois, cela représente environ 100 à 200 $ par développeur sur Sonnet 4.6.

L’abonnement Max change complètement la donne. Un développeur a suivi 8 mois d’usage, soit environ 10 milliards de jetons : son équivalent API dépassait 15 000 $, alors que son abonnement Max réel était d’environ 800 $ : 93 % d’économies. 

Plus de 90 % de ses jetons étaient des lectures de cache, ce qui explique pourquoi une tarification à l’usage pèse bien plus lourd qu’un forfait. Le point mort pour l’offre Max se situe autour de 100 à 200 $/mois en équivalent API, un seuil que tout utilisateur quotidien franchit vite.

Le choix du modèle est un levier d’optimisation. Le mode « opusplan » de Claude Code route Opus 4.6 pour la planification et bascule automatiquement sur Sonnet 4.6 pour la génération de code : vous profitez du raisonnement d’Opus là où il compte, tout en utilisant les jetons d’implémentation 5× moins chers de Sonnet. 

Sonnet 4.6 a été préféré à Opus 4.5 par 59 % des utilisateurs de Claude Code dans les tests internes d’Anthropic et tend à produire un code plus propre, avec moins de sur‑ingénierie. Pour les workflows riches en sous‑agents, CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929" exécute les sous‑agents sur Sonnet tout en gardant Opus pour l’orchestrateur.

Évitez ces trois plus grands postes de gaspillage de jetons : 

• Ne pas réinitialiser le contexte entre les tâches 

• Relire les fichiers en double à cause d’un mauvais CLAUDE.md

• Des prompts vagues qui lancent Claude dans des boucles d’essais‑erreurs

Corriger ces trois points suffit en général à diviser la consommation de jetons par deux.

Dépannage de Claude Code

Avant de conclure, passons en revue les problèmes courants rencontrés avec Claude Code et comment les résoudre.

Perte de contexte

Le mode d’échec le plus impactant est la perte de contexte. Le schéma Documenter & Réinitialiser vu plus haut existe précisément pour cela : ne laissez jamais une longue session être votre seule trace des décisions. Validez souvent, déversez l’avancement dans des fichiers, et considérez chaque session comme jetable.

Hallucinations avec des technologies de niche

Claude peut produire un code convaincant et assuré pour des technologies qu’il maîtrise mal. Si vous travaillez dans un langage ou framework que vous ne pouvez pas vérifier vous‑même, redoublez de vigilance sur chaque sortie. Comme l’a dit un développeur : « Je me suis mis dans un sacré pétrin en utilisant des LLM sur des technos que je ne connais pas. Mais sur des sujets familiers, les LLM ont considérablement accéléré ma vitesse. »

Sur‑ingénierie

La sur‑ingénierie est une tendance fréquente. Claude ajoute des abstractions inutiles, des helpers non sollicités et du refactoring prématuré si vous ne l’interdisez pas. Ajouter « utilisez l’approche la plus simple possible » à votre CLAUDE.md aide, et structurer le code par domaines métier plutôt que par couches techniques allège la charge cognitive pour Claude comme pour les humains.

Perte de données critiques

L’échec le plus spectaculaire : en développant une app de phonétique, Claude a supprimé tous les fichiers audio de phonèmes qu’un développeur avait obtenus avec autorisation, puis les a remplacés par des sons générés par IA. Il a renommé des fichiers et « s’est convaincu d’avoir mal étiqueté, alors qu’il était lui‑même incapable de distinguer les phonèmes pertinents ». 

La leçon : validez ou sauvegardez toujours les fichiers irremplaçables avant de donner à Claude l’accès à ceux‑ci.

Sessions improductives

Le conseil d’Anthropic pour les sessions qui dérapent est d’une franchise salutaire : enregistrez l’état avant de laisser Claude travailler, laissez‑le dérouler, puis acceptez le résultat… ou repartez de zéro plutôt que d’acharner des corrections. 

Le degré de confiance à accorder aux commits de Claude dépend de votre couverture de tests et de votre tolérance au risque. Certains valident via slash command des dizaines de fois par jour, avec revue de PR comme garde‑fou. Pour des bases de code en production avec des clients payants, relire chaque diff vaut la peine.

Passer à la pratique avec Claude Code

Pour plus de détails, l’overview Claude Code d’Anthropic est la source amont canonique sur laquelle la plupart des contenus communautaires s’appuient. Pour prolonger ce que nous avons couvert ici et pratiquer plusieurs fonctionnalités de Claude Code, consultez ces tutoriels :

• Claude Code 2.1 Guide — découvrez les nouveautés de la version 2.1, configurez Claude Code et menez une série d’expériences ciblées
• Claude Code Hooks Tutorial — allez plus loin dans l’automatisation par hooks et apprenez à les utiliser pour les tests, le formatage et les notifications
• Using Claude Code With Ollama Local Models — exécutez GLM 4.7 Flash en local avec Claude Code et Ollama pour éviter l’enfermement fournisseur et les transferts de données vers le cloud
• How to Build Claude Code Plugins — découvrez comment installer des extensions, choisir entre skills et MCP, et créer un plugin de journalisation de session personnalisé
• Claude Code Docker — apprenez à exécuter Claude Code dans Docker pour isoler vos environnements et maîtriser les pratiques de sécurité pour les agents IA
• Claude Code Router — apprenez à connecter plusieurs fournisseurs de modèles et à utiliser le bon LLM pour chaque tâche

Plusieurs projets open source intègrent également ces pratiques dans des configurations prêtes à l’emploi :

• obra/superpowers — un framework de skills composables incluant l’application stricte du TDD, le brainstorming socratique, la planification granulaire et la revue de code automatique entre les tâches. Désormais plugin officiel sur la marketplace d’Anthropic.

• github/spec-kit — la boîte à outils officielle de GitHub pour le Spec‑Driven Development. Structure le travail en Constitution → Spécifier → Planifier → Tâches, faisant de la spec la source unique de vérité pour tout agent de code.

• bmad-code-org/BMAD-METHOD — un framework agile complet avec 12+ personas d’agents (Architecte, QA, Scrum Master) et 34+ workflows couvrant tout le cycle de développement.

• wshobson/commands — 57 commandes slash prêtes pour la production à déposer dans .claude/commands/, dont 15 workflows multi‑agents.

• awesome-claude-code — l’annuaire de référence de l’écosystème : skills, hooks, commandes, agents et plugins. Commencez ici pour explorer.

Conclusion

Toutes les pratiques de cet article convergent : contraignez Claude fortement avant l’exécution, puis offrez‑lui un moyen de vérifier sa sortie. La planification dissipe l’ambiguïté. CLAUDE.md et les hooks posent des garde‑fous. Les tests valident. Une hygiène de contexte maintient la qualité au fil des sessions.

Si vous ne devez changer qu’une chose pour commencer, adoptez Documenter & Réinitialiser. Le coût de la dérive de contexte d’une session à l’autre surpasse largement les 20 000 jetons requis pour repartir à neuf. Ensuite :

• Ajoutez un hook pré‑commit qui bloque les commits quand les tests échouent

• Démarrez chaque tâche multi‑fichiers par un plan avant de toucher au code

• Gardez votre CLAUDE.md sous 100 instructions et utilisez des fichiers par sous‑répertoire pour les règles métiers

Nous venons d’ajouter un nouveau skill track sur AI Engineering with LangChain. Le contenu est nativement IA, pour apprendre aux côtés de votre agent tuteur personnel. Je vous recommande d’y jeter un œil pour devenir un vrai pro de l’ingénierie de workflows IA.