Claude Code : bonnes pratiques pour le codage agentique

(anthropic.com)

20 points par GN⁺ 2025-04-20 | 2 commentaires | Partager sur WhatsApp

Claude Code est un outil de codage agentique basé sur la CLI, qui peut s’adapter avec souplesse à divers environnements et langages de développement
La configuration de CLAUDE.md, la gestion de la liste des outils autorisés et la création de commandes personnalisées permettent de maximiser l’utilisabilité de Claude
L’application de stratégies selon le workflow (exploration-planification-implémentation-commit, développement piloté par les tests, itération visuelle, etc.) s’avère efficace
Le mode headless et les configurations multi-Claude permettent aussi l’automatisation et le travail en parallèle
Il est possible d’aller plus loin en intégrant Claude à divers outils de développement comme Git, GitHub ou Jupyter

Vue d’ensemble de Claude Code

Claude Code est un outil de codage agentique (automatisation du code en ligne de commande)
Il a été conçu pour permettre aux développeurs et chercheurs internes d’Anthropic d’intégrer Claude plus naturellement dans le codage
Grâce à une interface bas niveau et une conception découplée, il n’impose pas une méthode de développement particulière,
- et les développeurs peuvent configurer et utiliser Claude de la manière qui leur convient
Il s’impose ainsi comme un outil de codage puissant, flexible et sûr
Son inconvénient est qu’il présente une courbe d’apprentissage élevée pour les nouveaux utilisateurs,
- ce qui impose de construire progressivement ses propres bonnes pratiques
Cet article s’appuie sur l’expérience d’équipes internes et d’ingénieurs externes ayant réellement utilisé Claude Code,
- et présente des schémas généraux efficaces dans plusieurs langages, codebases et environnements
Les éléments proposés ne sont pas une réponse unique, mais un point de départ ; il est recommandé d’expérimenter et d’améliorer selon ses besoins

# 1. Personnaliser la configuration

Claude Code est un assistant de codage agentique qui collecte automatiquement le contexte pour construire les prompts
Cette collecte de contexte consomme du temps et des tokens, mais elle peut être optimisée en ajustant l’environnement

a. Créer un fichier `CLAUDE.md`

CLAUDE.md est un fichier spécial que Claude inclut automatiquement dans le contexte au début d’une conversation
Ce fichier est idéal pour documenter les éléments suivants :

les commandes bash fréquemment utilisées
les fichiers clés et les fonctions utilitaires
les règles de style du code
la manière d’exécuter les tests
la façon de travailler sur le dépôt (par ex. nommage des branches, merge vs. rebase)
la configuration de l’environnement de développement (par ex. utilisation ou non de pyenv, compilateurs compatibles)
les comportements atypiques ou avertissements propres au projet
toute autre information que Claude doit retenir

Le fichier CLAUDE.md n’impose aucun format particulier ; il est recommandé de le rédiger de façon concise et lisible par un humain
Exemple :

# Bash commands  
- npm run build: Build the project  
- npm run typecheck: Run the typechecker  
  
# Code style  
- Use ES modules (import/export) syntax, not CommonJS (require)  
- Destructure imports when possible (eg. import { foo } from 'bar')  
  
# Workflow  
- Be sure to typecheck when you’re done making a series of code changes  
- Prefer running single tests, and not the whole test suite, for performance

Emplacement du fichier `CLAUDE.md`

Claude recherche CLAUDE.md aux emplacements suivants pour l’inclure dans le contexte :

à la racine du dépôt ou dans le répertoire depuis lequel claude a été lancé
- il est recommandé de l’enregistrer sous CLAUDE.md et de le versionner avec Git pour le partager entre sessions et entre membres d’une équipe
- pour des réglages personnels, il peut être enregistré sous CLAUDE.local.md puis ajouté à .gitignore
dans les répertoires parents du répertoire d’exécution
- utile dans une structure monorepo (par ex. root/CLAUDE.md et root/foo/CLAUDE.md peuvent être utilisés ensemble)
dans les sous-répertoires du répertoire d’exécution
- automatiquement inclus dans le contexte lors du travail sur des fichiers de ce répertoire
dans le répertoire personnel (~/.claude/CLAUDE.md)
- application globale à toutes les sessions

Lorsque la commande /init est exécutée, Claude crée automatiquement le fichier CLAUDE.md

b. Affiner le fichier `CLAUDE.md`

Comme CLAUDE.md est utilisé comme une partie du prompt de Claude, il faut le retravailler et l’optimiser de manière itérative, comme un prompt
Une erreur fréquente consiste à y mettre trop de contenu sans vérifier son effet

Il est important d’identifier par l’expérimentation quels contenus améliorent les performances des réponses du modèle
Le contenu peut être ajouté manuellement, ou bien en appuyant sur la touche # pour demander à Claude de le répercuter automatiquement dans CLAUDE.md
Beaucoup d’ingénieurs documentent en temps réel les commandes, guides de style, etc., et incluent les modifications de CLAUDE.md dans leurs commits pour les partager avec l’équipe

Chez Anthropic, un prompt improver est utilisé pour affiner CLAUDE.md,
et des formulations d’insistance comme « IMPORTANT » ou « YOU MUST » sont ajoutées pour améliorer la précision des réponses

c. Gérer la liste des outils autorisés de Claude

Pour les actions susceptibles de modifier le système (écriture de fichiers, exécution de commandes bash, utilisation d’outils MCP, etc.), Claude Code demande par défaut l’approbation de l’utilisateur
Il s’agit d’une conception prudente pour des raisons de sécurité, et les outils que l’utilisateur juge sûrs peuvent être préapprouvés via une liste d’autorisation (allowlist)

Comment configurer les outils autorisés

Pendant une session, sélectionner « Always allow » lorsqu’une invite s’affiche
Ajouter ou supprimer des outils avec la commande /allowed-tools
Exemples :
- Edit → autoriser l’édition de fichiers
- Bash(git commit:*) → autoriser les commits Git
- mcp__puppeteer__puppeteer_navigate → autoriser la navigation via le serveur MCP Puppeteer
Modifier manuellement .claude/settings.json ou ~/.claude.json
- pour un partage avec l’équipe, il est recommandé d’utiliser le premier et de le versionner avec Git
Utiliser le flag CLI --allowedTools pour une session donnée

d. Installer la CLI `gh` pour utiliser GitHub

Claude peut utiliser la CLI gh, ce qui permet d’automatiser des tâches GitHub comme la création d’issues, la rédaction de PR ou la lecture de commentaires
Même sans installer gh, il est possible de passer par l’API GitHub ou un serveur MCP

# 2. Donner plus d’outils à Claude

Claude peut accéder à l’environnement shell de l’utilisateur, et donc utiliser directement les scripts et fonctions créés par celui-ci
Il peut aussi se connecter à des outils externes plus complexes via MCP ou une API REST

a. Utiliser Claude avec des outils Bash

Claude Code hérite de l’environnement bash de l’utilisateur, ce qui lui donne accès aux utilitaires déjà installés

Claude connaît déjà les outils Unix courants ou la CLI gh
En revanche, les outils bash personnalisés créés par l’utilisateur doivent lui être explicitement présentés

Pour que Claude reconnaisse des outils personnalisés, il faut :

indiquer explicitement le nom de l’outil et des exemples d’usage à Claude
lui demander de consulter l’usage de l’outil via l’option --help
documenter les outils fréquemment utilisés dans CLAUDE.md

b. Utiliser Claude avec MCP

Claude Code joue à la fois le rôle de serveur MCP et de client MCP
En tant que client, il peut se connecter à plusieurs serveurs MCP pour exploiter différents outils

Les outils d’un serveur MCP peuvent être connectés à Claude de trois façons :

définis dans les paramètres du projet (utilisables uniquement dans ce répertoire)
définis dans les paramètres globaux pour être utilisables dans tous les projets
versionnés dans un fichier .mcp.json afin que tous les développeurs collaborant sur le projet puissent utiliser immédiatement ces outils
- par exemple, enregistrer dans .mcp.json des serveurs Puppeteer et Sentry permet de les rendre disponibles à toute l’équipe

Pour déboguer des problèmes de configuration lors de l’utilisation de MCP, il est utile de lancer Claude avec le flag --mcp-debug

c. Commandes slash personnalisées

Pour des workflows récurrents (débogage, analyse de logs, etc.),
il est possible d’enregistrer des modèles de prompt sous forme de fichiers Markdown dans le dossier .claude/commands

La commande correspondante apparaît dans le menu d’autocomplétion quand on saisit / dans Claude
Peut être commitée dans git afin d’être partagée avec les membres de l’équipe

Transmission de paramètres : `$ARGUMENTS`

En incluant $ARGUMENTS dans une commande slash, il est possible d’insérer automatiquement les paramètres transmis lors de l’exécution de la commande

Exemple : analyse et correction automatiques d’une issue GitHub

Please analyze and fix the GitHub issue: $ARGUMENTS.  
  
Follow these steps:  
  
1. Use `gh issue view` to get the issue details  
2. Understand the problem described in the issue  
3. Search the codebase for relevant files  
4. Implement the necessary changes to fix the issue  
5. Write and run tests to verify the fix  
6. Ensure code passes linting and type checking  
7. Create a descriptive commit message  
8. Push and create a PR  
  
Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

En enregistrant ce contenu dans .claude/commands/fix-github-issue.md, on peut l’utiliser avec la commande /project:fix-github-issue
Ex. : /project:fix-github-issue 1234 → Claude tente automatiquement de corriger l’issue #1234

Les commandes de configuration personnelle peuvent être enregistrées dans le dossier ~/.claude/commands, ce qui les rend disponibles dans toutes les sessions

# 3. Exploiter des workflows courants

Claude Code n’impose aucun workflow particulier et offre à l’utilisateur une flexibilité totale
Sur cette base, la communauté d’utilisateurs a fait émerger divers modèles d’usage qui se sont révélés efficaces

a. Exploration → planification → implémentation → commit

Demander à Claude de lire les fichiers, images et URL pertinents
- Ex. : « Lis le fichier qui gère les logs », « Lis logging.py »
- Mais préciser explicitement de ne pas coder
- À cette étape, l’usage de subagents est très efficace (et encore plus utile lorsque le problème est complexe)
Demander à Claude d’élaborer un plan pour résoudre le problème
- En utilisant des mots-clés comme « think », « think hard » ou « ultrathink », davantage de budget de calcul lui est alloué
- Si le plan est pertinent, le consigner dans un document ou créer une issue GitHub permet de garder un point de référence
Ensuite, demander à Claude d’implémenter le code selon le plan établi
- Pendant l’implémentation, on peut aussi lui demander explicitement de vérifier lui-même la validité du résultat
Enfin, lui demander de committer le résultat et de créer une PR
- Si nécessaire, on peut aussi lui demander de mettre à jour le README ou le CHANGELOG

📌 Dans ce flux, si les étapes 1 à 2 sont omises, Claude se mettra immédiatement à coder ; la phase de planification est donc particulièrement importante pour les problèmes complexes

b. Écrire les tests → commit → écrire le code → itérer → commit (développement piloté par les tests)

C’est une approche souvent utilisée en interne chez Anthropic, adaptée aux tâches disposant de tests unitaires, d’intégration ou e2e

Demander à Claude d’écrire les tests à partir des critères d’entrée/sortie
- Préciser clairement qu’il s’agit d’un développement piloté par les tests → l’orienter vers l’écriture des seuls tests, sans implémenter la fonctionnalité
Demander de vérifier que les tests échouent
- Indiquer de seulement exécuter les tests, sans implémenter
Si les tests conviennent, faire un commit
Demander ensuite à Claude d’écrire le code qui fait passer les tests
- Préciser de ne pas modifier les tests
- En général, plusieurs itérations sont nécessaires avant d’obtenir un passage complet des tests
- Il est aussi efficace d’utiliser des subagents pour vérifier l’absence de surapprentissage
Une fois tous les tests passés, demander de committer le code

✅ Claude fonctionne particulièrement bien lorsqu’il dispose d’une cible claire (par ex. des cas de test, des images, etc.)

c. Écrire le code → fournir une capture d’écran du résultat → améliorer par itérations

Mettre en place un environnement capable de fournir automatiquement des captures d’écran du navigateur (par ex. Puppeteer MCP, simulateur iOS, etc.)
Fournir une maquette visuelle (coller une image, transmettre un chemin, etc.)
Demander à Claude d’implémenter le design → fournir une capture du résultat → redemander une comparaison et des améliorations
Si le résultat est satisfaisant, faire un commit

💡 Comme pour une personne, le résultat s’améliore nettement après 2 ou 3 itérations avec Claude → la boucle de feedback visuel est importante

d. Mode Safe YOLO

Avec l’option --dangerously-skip-permissions, toutes les demandes d’approbation sont ignorées
Claude exécute alors les tâches de façon entièrement automatique, sans validation de l’utilisateur

⚠️ Il existe des risques de perte de données, de détérioration du système et de prompt injection → exécution recommandée uniquement dans un conteneur isolé d’Internet
→ Pour une implémentation type, il est recommandé d’utiliser un Docker Dev Container

e. Q&R sur la codebase

Lorsqu’on découvre un nouveau projet, il est possible de poser des questions à Claude comme on le ferait à un collègue ingénieur
Claude explore alors la codebase et trouve lui-même les réponses

Exemples de questions :

Comment fonctionne le logging ?
Comment créer un nouvel endpoint API ?
À quoi sert l’async move à la ligne 134 de foo.rs ?
Quels cas limites CustomerOnboardingFlowImpl traite-t-il ?
Pourquoi appelle-t-on bar() plutôt que foo() ?
Quel code Java ressemble à la ligne 334 de baz.py ?

📌 L’exploration est possible simplement avec des questions en langage naturel, sans prompt séparé
→ Chez Anthropic, cette approche est utilisée comme outil principal d’onboarding

f. Intégration Git

Claude gère très bien l’automatisation de tâches Git telles que :

Recherche dans l’historique Git :
- Ex. : « Quels changements ont été inclus dans la v1.2.3 ? », « Qui a créé cette fonctionnalité ? », « Pourquoi cette API a-t-elle cette structure ? »
Rédaction de messages de commit :
- Générés automatiquement à partir des modifications et du contexte environnant
Tâches Git avancées :
- Restauration de fichiers, résolution de conflits de rebase, comparaison et fusion de patchs, etc.

g. Intégration GitHub

Claude Code peut fortement automatiser les tâches liées à GitHub :

Création de Pull Request :
- Il reconnaît le mot-clé pr et génère automatiquement un message de commit à partir des changements
Correction de commentaires de code review :
- Avec un simple « Corrige les commentaires sur la PR », il peut modifier puis pousser les changements
Correction des échecs de build et des erreurs de lint
Tri et organisation des issues :
- Demander à Claude : « Passe en revue les issues ouvertes et organise-les »

💡 Pas besoin de mémoriser les commandes gh pour automatiser les tâches GitHub

h. Travail avec Jupyter Notebook

Claude peut lire et écrire des fichiers .ipynb, et interpréter les sorties incluant des images
Dans VS Code, il est recommandé d’ouvrir Claude Code et le fichier notebook côte à côte

Fonctionnalités supplémentaires :

Avant de partager avec d’autres, il est possible de demander à Claude de nettoyer le notebook et d’en améliorer la présentation visuelle
- Des demandes comme « Mets-le en forme pour qu’il soit agréable à lire » ou « Rends la visualisation plus jolie » fonctionnent bien, car elles optimisent la vue pour des humains

# 4. Optimiser le workflow

Les suggestions ci-dessous sont des méthodes d’optimisation applicables à tous les workflows

a. Rédiger des consignes spécifiques

Avec Claude Code, plus les consignes sont spécifiques dès la première tentative, plus le taux de réussite est élevé
Demander clairement les choses dès le départ réduit le besoin de corrections en cours de route

Comparaison d’exemples

❌ add tests for foo.py → trop large
✅ Pour foo.py, écris un nouveau cas de test qui couvre le cas d’un utilisateur déconnecté. N’utilise pas de mock
❌ why does ExecutionFactory have such a weird api? → ambigu
✅ Remonte l’historique git de ExecutionFactory et résume pourquoi l’API a été conçue sous sa forme actuelle
❌ add a calendar widget → orientation d’implémentation floue
✅ Analyse la manière dont les widgets existants sont implémentés sur la page d’accueil (par ex. HotDogWidget.php), identifie le pattern de séparation entre le code et l’interface, puis implémente un nouveau widget calendrier de la même façon, avec sélection du mois et navigation entre les années. Les bibliothèques externes autorisées sont uniquement celles déjà utilisées dans le projet

Claude peut inférer l’intention, mais ne peut pas lire dans les pensées → la clarté est essentielle

b. Fournir des images

Claude est très performant pour traiter des images ou des diagrammes
Vous pouvez lui fournir des images de plusieurs façons :

Sur macOS, cmd+ctrl+shift+4 → capture d’écran vers le presse-papiers → coller avec ctrl+v (impossible en environnement distant)
Glisser-déposer un fichier image
Fournir le chemin d’un fichier image

Très utile pour implémenter des maquettes de design, analyser des graphiques visuels, etc.
Même sans visuel, il est utile de préciser clairement si la qualité visuelle du résultat est importante

c. Spécifier les fichiers à traiter

Si vous indiquez clairement à Claude quels fichiers consulter ou modifier, la précision du travail s’améliore

L’autocomplétion avec la touche Tab permet de saisir rapidement les chemins de fichiers/dossiers

d. Fournir des URL à Claude

Si vous donnez une URL à Claude, il peut lire directement la documentation ou la page web

Exemple : lien vers une documentation d’API, page de design system, etc.
Pour accéder plusieurs fois au même domaine, vous pouvez ajouter le domaine à la liste blanche avec la commande /allowed-tools, afin d’éviter les validations répétées

e. Réorienter rapidement et souvent le travail

Vous pouvez appuyer sur Shift + Tab pour automatiser le travail avec le mode d’acceptation automatique (auto-accept mode),
mais en général, collaborer activement avec Claude et ajuster la direction donne de meilleurs résultats

4 outils d’ajustement utiles :

Demander d’abord un plan : demander systématiquement un plan avant l’implémentation, puis valider avant de poursuivre
Interrompre immédiatement avec la touche Escape : vous pouvez arrêter à tout moment, y compris pendant la réflexion ou l’édition des fichiers
Appuyer deux fois sur Escape pour modifier le prompt précédent : cela permet de corriger la commande précédente et de repartir dans une nouvelle direction
Demander l’annulation des modifications : vous pouvez demander à Claude de revenir en arrière pour tester une autre approche

Il arrive que Claude résolve tout parfaitement du premier coup, mais en utilisant ces outils, vous pouvez obtenir des résultats plus rapides et plus précis

f. Réinitialiser le contexte avec la commande /clear

Lorsqu’une session dure longtemps, la fenêtre de contexte (context window) de Claude peut se remplir d’informations inutiles et dégrader les performances
→ il est recommandé de prendre l’habitude de réinitialiser le contexte avec /clear à chaque unité de travail

g. Utiliser des checklists et un scratchpad

Pour les tâches complexes (par ex. migration de code, correction massive d’erreurs de lint, etc.),
utiliser un fichier Markdown ou une issue GitHub comme checklist améliore l’efficacité

Exemple : résolution d’erreurs de lint

Demander à Claude d’exécuter la commande lint → organiser les erreurs sous forme de checklist Markdown
Traiter chaque élément un par un, vérifier puis cocher → passer à l’élément suivant

Cette méthode permet de suivre l’avancement tout en gardant la qualité sous contrôle

h. Transmettre des données à Claude

Il existe plusieurs façons de transmettre des données à Claude :

Copier/coller (la méthode la plus courante)
Entrée par pipe (par ex. cat foo.txt | claude)
- adaptée aux logs, CSV et gros volumes de texte
Lui demander de récupérer directement les données via une commande bash, un outil MCP ou une slash command
Demander la lecture d’un fichier ou d’une URL (images incluses)

En pratique, il est courant de combiner plusieurs méthodes
Exemple : transmettre des logs par pipe, puis demander à Claude d’utiliser un outil MCP pour récupérer du contexte supplémentaire

# 5. Automatiser l’infrastructure avec le mode headless

Claude Code prend en charge un mode headless pour les environnements non interactifs (CI, hooks pre-commit, scripts de build, automatisation, etc.)

Exécuter le mode headless avec un prompt via le flag -p
Utiliser une sortie JSON en streaming avec l’option --output-format stream-json

⚠️ Le mode headless ne persiste pas d’une session à l’autre et doit être relancé manuellement à chaque fois

a. Catégoriser automatiquement les issues avec Claude

Le mode headless est adapté aux déclencheurs d’automatisation basés sur des événements GitHub
Exemple : analyser automatiquement une nouvelle issue à sa création et lui attribuer des labels

Cette fonctionnalité est effectivement utilisée dans le dépôt public de Claude Code pour ajouter automatiquement des labels aux nouvelles issues

b. Utiliser Claude comme linter

Claude peut automatiser une revue de code subjective que les outils de lint traditionnels détectent difficilement
Exemples :

fautes de frappe
commentaires obsolètes
noms de fonctions/variables trompeurs
flux de code peu intuitif, etc.

Cela permet d’améliorer la qualité du code au-delà des outils d’analyse statique

# 6. Passer au niveau supérieur avec des workflows multi-Claude

Au-delà de l’usage d’un seul Claude, faire tourner plusieurs instances de Claude en parallèle est une méthode extrêmement puissante
Comme plusieurs ingénieurs qui collaborent, répartir le travail entre plusieurs Claude peut améliorer à la fois l’efficacité et la qualité

a. Un Claude écrit le code, un autre le relit

Le pattern le plus simple et le plus efficace :

Claude 1 : écrit le code
Exécuter Claude 2 via /clear ou dans un autre terminal → relit le code produit
Exécuter Claude 3 ou refaire /clear → lit le code et la review, puis applique les corrections

Ou bien,

Claude 1 : écrit les tests
Claude 2 : écrit le code qui fait passer les tests

❗ Il est aussi possible que les instances de Claude partagent des scratchpads distincts entre elles,
ou de définir une répartition des rôles du type « ce Claude n’écrit que dans le fichier A, cet autre Claude ne lit que le fichier B »

📌 La séparation des tâches donne souvent de meilleurs résultats qu’un seul Claude

b. Faire plusieurs checkouts du dépôt

Au lieu d’attendre qu’un Claude ait terminé, vous pouvez créer plusieurs répertoires de checkout Git pour travailler en parallèle

Créer 3 ou 4 checkouts git dans des dossiers séparés
Ouvrir chaque dossier dans un onglet de terminal différent
Attribuer une tâche différente à chaque instance de Claude
Passer d’un onglet à l’autre pour suivre l’avancement et approuver/refuser

c. Utiliser Git worktree

git worktree est une fonctionnalité de Git qui permet de checkout plusieurs branches d’un même dépôt dans des répertoires différents
→ idéal pour traiter plusieurs tâches indépendantes en parallèle

Exemple :

un Claude refactorise le système d’authentification
un autre Claude crée séparément un composant de visualisation de données
aucune interférence entre eux → parallélisme maximal

Utilisation

Créer un worktree :
git worktree add ../project-feature-a feature-a
Lancer Claude :
cd ../project-feature-a && claude
Répéter autant que nécessaire

Conseils

Garder des noms de worktree cohérents
Maintenir un worktree par onglet de terminal
Si vous utilisez iTerm2 (Mac), configurer des notifications est recommandé
Séparer aussi l’IDE selon chaque worktree
Nettoyage une fois le travail terminé :
git worktree remove ../project-feature-a

d. Mode headless + structure d’automatisation personnalisée

Le mode headless (claude -p) permet d’intégrer Claude Code dans un workflow de manière programmable
En le combinant avec les outils propres à Claude et les prompts système, il est possible d’utiliser les deux patterns suivants

1. Fanning out : répartir les tâches de migration/analyse à grande échelle