Claude Code : les bonnes pratiques qui tiennent en production

CLAUDE.md est un fichier que Claude Code charge automatiquement au début de chaque session. C'est la mémoire du projet : les commandes de build et de test, les conventions qui ne se devinent pas en lisant le code, les pièges connus, ce qu'il ne faut jamais toucher. La commande /init en génère une première version à partir du dépôt.

Le fichier se versionne avec le code, à la racine du dépôt, pour que toute l'équipe partage le même contexte. Un CLAUDE.md dans un sous-dossier précise les règles locales, et un fichier personnel dans le dossier ~/.claude garde les préférences de chacun hors du dépôt.

L'erreur la plus courante est de le remplir. Chaque ligne est relue à chaque session et coûte du contexte ; une consigne noyée dans trois pages est une consigne ignorée. Gardez ce que l'agent ne peut pas trouver seul, écrivez-le comme une règle vérifiable (« lancer npm run typecheck avant de conclure », pas « écrire du code propre »), et supprimez ce qui n'a plus cours. Quand l'agent se trompe deux fois de la même façon, c'est le signe qu'une ligne manque.

Laissé à lui-même, un agent de code commence à écrire tout de suite. Sur une tâche d'une ligne, c'est très bien. Sur une tâche qui touche plusieurs fichiers, c'est la façon la plus sûre de résoudre le mauvais problème avec assurance.

L'ordre qui marche est connu : faire lire les fichiers concernés sans rien modifier, demander un plan, le relire et le corriger, puis lancer l'implémentation, et enfin le commit. Le mode plan (Maj+Tab dans le terminal, jusqu'à ce que la barre d'état l'affiche) rend cette séparation explicite : l'agent explore et propose, il n'écrit pas tant que vous n'avez pas validé.

Le plan est le moment le moins cher pour corriger une erreur. Un mauvais choix d'architecture repéré dans un plan de dix lignes se corrige en une phrase ; repéré dans un diff de six cents lignes, il se paie en relecture et en retour arrière. Si vous ne pouvez pas décrire le résultat attendu en quelques phrases, le plan n'est pas prêt, et l'agent non plus.

C'est la pratique qui change le plus le résultat. Un agent qui peut exécuter un test, un typecheck, un build ou comparer une capture d'écran à une maquette corrige ses propres erreurs avant de vous les montrer. Un agent qui ne le peut pas vous rend du code plausible, et c'est vous qui faites la vérification.

Dites-lui donc comment vérifier, dans la demande ou dans CLAUDE.md : quelle commande, quel résultat attendu, quel cas limite. Le développement piloté par les tests s'y prête particulièrement : faire écrire les tests d'abord, constater qu'ils échouent, les committer, puis demander l'implémentation sans modifier les tests. L'agent a une cible fixe, et vous savez quand il l'a atteinte.

Méfiez-vous du test qu'il écrit pour lui-même après coup. Un agent peut faire passer un test en l'affaiblissant, ou conclure « terminé » sur un test ignoré. Le critère de fin doit venir de vous, ou être figé avant l'implémentation.

« Ajoute des tests pour foo.py » produit des tests. « Ajoute un test pour foo.py qui couvre le cas où l'utilisateur est déconnecté, sans mock de la base » produit le test dont vous aviez besoin. La précision de la demande se retrouve dans la précision du résultat.

Pointez les fichiers plutôt que de les décrire, collez le message d'erreur complet plutôt qu'un résumé, joignez la capture ou la maquette quand le sujet est visuel, et citez le fichier existant dont il faut reprendre le style. L'agent lit le code ; il ne lit pas dans vos pensées.

Corrigez tôt. Échap interrompt l'agent en cours de route sans perdre ce qui est fait, et un double Échap permet de revenir à un message précédent pour reformuler. Une correction à la troisième étape coûte une phrase ; à la trentième, elle coûte une session.

La fenêtre de contexte est la ressource qui se dégrade le plus vite. Chaque fichier lu, chaque sortie de commande, chaque fausse piste y reste. Quand elle se remplit, l'agent suit moins bien les consignes du début et confond les tâches.

Une tâche par session. /clear entre deux sujets sans rapport, plutôt que d'enchaîner une correction de bug et une refonte de page dans la même conversation. /compact quand une longue tâche doit continuer, pour résumer l'historique au lieu de le traîner.

Pour les recherches larges (« où est géré le paiement ? », « qui appelle cette fonction ? »), confiez l'exploration à un sous-agent. Il lit ce qu'il faut dans son propre contexte et ne rapporte que la conclusion. La session principale garde sa place pour le travail qui compte.

Depuis la version 2.1.283, Claude Code démarre en mode auto : un second modèle, le classifieur, examine les actions à votre place et ne bloque que ce qui paraît risqué. En mode manuel, il demande avant chaque modification de fichier ou commande. Dans les deux cas, la protection qui compte est celle que vous écrivez : autorisez explicitement les commandes sûres et répétitives (lint, tests, git status) dans le fichier de réglages du projet, et interdisez ce qui ne doit jamais arriver, comme la lecture des fichiers .env ou un push sur la branche principale.

L'option qui saute toutes les permissions existe. Elle n'a sa place que dans un conteneur isolé, sans secrets et sans accès au réseau, pas sur un poste de développeur connecté à la production.

Une consigne dans CLAUDE.md est un conseil : l'agent la suit la plupart du temps. Quand une règle doit s'appliquer à chaque fois, faites-en un hook, une commande lancée par Claude Code à un moment précis (après chaque modification de fichier, avant une commande). Formater le code, lancer le linter, bloquer une écriture dans un dossier protégé : ce sont des hooks, pas des phrases.

Un diff accepté sans relecture. L'agent écrit vite ; la personne qui fusionne reste responsable du code. Relisez comme vous reliriez la pull request d'un collègue, et demandez une revue par une seconde session si le changement est gros : une instance qui n'a pas écrit le code le juge mieux que celle qui l'a écrit.

Plusieurs agents en parallèle avant d'en maîtriser un. Les worktrees git permettent de faire travailler plusieurs sessions sur des branches séparées, et le mode non interactif (claude -p) permet de brancher Claude Code dans un script ou une chaîne d'intégration. C'est utile, une fois que les pratiques ci-dessus tiennent sur une session. Avant, cela multiplie les erreurs au lieu du débit. Le montage qui les rend sûrs, un environnement de prévisualisation par branche, est détaillé dans notre article sur le multi-agents et le multi-staging.

Des secrets ou des données clients dans le contexte. Ce que l'agent lit part au modèle. Les fichiers de configuration sensibles s'excluent par les permissions, et les données de production n'ont rien à faire dans un dépôt de développement, agent ou pas.

Un « terminé » sans preuve. Une tâche n'est pas finie parce que l'agent le dit, mais parce que les tests passent, que le build réussit, et que le comportement attendu a été vu.

Les pratiques ci-dessus recoupent les recommandations publiées par Anthropic. Aucun chiffre de productivité n'est avancé dans cet article : il dépend trop du projet et de l'équipe pour être généralisé.

Documentation Claude Code, « Best practices for Claude Code », relue le 20 octobre 2026 (l'ancien article d'Anthropic sur le sujet redirige désormais vers cette page) : vérification par l'agent, explorer puis planifier puis coder, CLAUDE.md et /init, permissions, hooks, sous-agents, Échap et /rewind, /clear et /compact, mode non interactif, worktrees. Bonnes pratiques.

Documentation Claude Code : mémoire et CLAUDE.md, modes de permission, réglages, hooks, relue le 20 octobre 2026. Mémoire, Modes de permission, Réglages, Hooks.

Anthropic, « Building effective agents », 19 décembre 2024, relu le 20 octobre 2026 : la distinction entre workflow et agent reprise dans l'introduction. Article Anthropic.