Publié le 26/04/2026 •Temps de lecture : 9 minutes
Description

Maîtriser Claude Code

Introduction

Quand j’ai commencé à utiliser Claude Code, j’ai fait comme beaucoup de développeurs : je posais des questions, je lançais des refactors, puis j’attendais un résultat.

Le constat était mitigé. Les réponses étaient parfois bonnes, parfois incohérentes, souvent peu alignées avec mon architecture. Non pas parce que Claude Code était mauvais, mais parce que je l’utilisais comme un simple chatbot alors qu’il fonctionne comme un environnement agentique capable de lire le code, modifier des fichiers, exécuter des commandes et orchestrer plusieurs étapes de travail.

Le déclic est venu quand j’ai compris une idée simple : Claude Code n’est pas juste un outil de génération de texte. C’est un agent de développement. Et comme tout agent, il a besoin de trois choses :

  • Un contexte propre,

  • Des règles explicites,

  • Une méthode de travail.

Bien configuré, Claude Code ne sert plus seulement à "coder plus vite". Il devient un véritable copilote d’ingénierie : il comprend le projet, respecte les conventions, suit l’architecture, et aide à travailler de façon plus structurée.

1. Installation et intégration

La manière la plus simple de commencer est de suivre la documentation officielle https://code.claude.com/docs/en/overview#terminal.

Pour mon cas, Sur Windows, Anthropic recommande une installation native, avec des commandes distinctes selon qu’on est dans PowerShell ou dans CMD. Il faut aussi avoir Git for Windows installé, car Claude Code s’appuie dessus sur Windows.

Exemples :

Une fois installé, il suffit d’ouvrir un terminal à la racine du projet et de lancer :

claude

Claude Code est disponible dans le terminal, mais aussi dans des environnements intégrés selon l’outil utilisé. La logique reste la même : il travaille mieux quand il part du bon répertoire, avec le bon contexte de projet.

2. Le vrai changement de posture : Claude Code n’est pas un chatbot

C’est probablement l’erreur la plus fréquente.

Beaucoup de développeurs utilisent Claude Code comme une version améliorée d’un assistant conversationnel : ils donnent une instruction vague du type “refactor this code” ou “improve this project”, puis jugent le résultat. En pratique, ce mode d’utilisation produit souvent des sorties inconstantes.

Pourquoi ? Parce que Claude Code est conçu pour agir. Il explore, lit les fichiers, propose des plans, exécute des modifications, appelle des outils, et avance de manière semi-autonome. Cette autonomie est précieuse, mais elle doit être cadrée.

La bonne posture n’est donc pas de “lancer une requête”. La bonne posture est de lui donner un cadre de travail.

3. CLAUDE.md : la pièce maîtresse du projet

Le fichier CLAUDE.md est l’un des éléments les plus importants de Claude Code. C’est là que l’on pose le cadre stable du projet : architecture, conventions, stack, règles de conception, attentes sur les tests, workflow, contraintes métier, etc. La documentation officielle précise que ces fichiers sont lus au démarrage de chaque session et servent de mémoire persistante pour guider Claude.

Autrement dit, CLAUDE.md joue le rôle d’un contrat de collaboration entre le projet et l’agent.

Sans lui, Claude improvise. Avec lui, il comprend l’architecture et s’y conforme.

Exemple de CLAUDE.md :

# Projet : Core Spring

## Contexte
Application Java 25 basée sur Spring Boot.

## Architecture
- Architecture hexagonale (Ports / Adapters)
- Respect des principes SOLID
- Aucune logique métier dans les controllers (oui car j’ai déjà rencontré ce cas 😊)

## Stack technique
- Java 25
- Spring Boot
- Maven
- JUnit 5
- Mockito

## Règles de développement
- Favoriser l'injection de dépendances par constructeur
- Ne pas instancier les dépendances métier avec `new`
- Les exceptions techniques ne doivent pas remonter dans le domaine
- Préférer des services métiers petits et spécialisés

## Tests
- Générer des tests unitaires pour toute logique métier
- Éviter les tests inutiles sur getters/setters

Ce qu’il faut y mettre

Un bon CLAUDE.md contient surtout des éléments stables :

  • l’architecture cible,

  • les conventions de code,

  • les règles de refactor,

  • le style de tests,

  • les commandes utiles,

  • les décisions structurantes du projet.

Ce qu’il ne faut pas y mettre : Il ne doit pas devenir une décharge de documentation interminable. Plus il est long, plus il consomme de contexte et moins il reste efficace. La doc officielle insiste d’ailleurs sur l’importance d’instructions spécifiques et concises.

En pratique, CLAUDE.md doit contenir les invariants du projet, pas tout l’historique de l’équipe.

Il arrive que CLAUDE.md ne soit pas chargé automatiquement : on peut faire un test simple. Dans mon cas, je lui demande quelle architecture utilise mon projet ?

  • Réponse vague → contexte non chargé → redémarrer la session avec la commande /clear, puis relancer claude

  • Réponse précise → configuration correcte

4. Comprendre le contexte : la vraie ressource rare

À chaque requête, Claude Code reconstruit une fenêtre de contexte avec ce qu’il juge nécessaire : conversation en cours, instructions, mémoire, extraits de fichiers, résultats d’outils, etc. La documentation rappelle qu’une session commence avec une fenêtre fraîche, puis se remplit progressivement à mesure que le travail avance.

Le point clé, ce n’est pas seulement “combien de tokens le modèle supporte”, mais comment ce contexte est utilisé au fil de la session.

Quand une session devient trop longue :

  • des résumés automatiques peuvent apparaître,

  • certaines informations deviennent moins saillantes,

  • la qualité de suivi peut se dégrader,

  • des détails importants peuvent être compactés.

La bonne pratique est simple : une session = un objectif clair.

Par exemple :

  • une session pour analyser une architecture,

  • une session pour préparer un refactor,

  • une session pour implémenter une étape précise,

  • une session pour déboguer un bug complexe.

Claude Code fournit justement des commandes utiles pour surveiller et gérer cela, comme /context, /compact et /clear. /context permet de visualiser l’utilisation du contexte, /compact résume l’historique en conservant l’essentiel, et /clear repart sur une conversation neuve.

Aujourd’hui, le modèle Opus 4.8 a environ 1 million de tokens, soit approximativement 750 000 mots.

Les retours des utilisateurs font état d’une dégradation de la qualité des réponses et d’hallucinations de Claude aux environs de 200k tokens utilisés.

5. SKILL.md : quand CLAUDE.md ne suffit plus

Quand on découvre Claude Code, on a tendance à vouloir tout mettre dans CLAUDE.md. C’est une erreur.

La documentation officielle introduit les skills, définies via un fichier SKILL.md. Une skill sert à encapsuler une procédure réutilisable : audit de sécurité, check-list de release, protocole de debugging, workflow de migration, génération de documentation, etc. Claude peut les charger quand elles deviennent pertinentes, ou on peut les invoquer directement. Surtout, le contenu complet d’une skill n’est chargé qu’au moment de son utilisation, ce qui évite d’alourdir inutilement le contexte principal.

Règle simple

  • CLAUDE.md = faits stables et règles globales

  • SKILL.md = procédures, playbooks, workflows récurrents

Exemple de cas d’usage On peut créer une skill debug-prod/SKILL.md qui décrit comment :

  1. collecter les logs,

  2. vérifier les endpoints,

  3. lancer les tests ciblés,

  4. proposer des hypothèses,

  5. produire un plan de correction minimal.

C’est beaucoup plus propre que de répéter la même méthode dans chaque session.

6. Plan Mode vs exécution : la pratique qui change tout

Une autre excellente pratique consiste à ne pas demander immédiatement à Claude d’éditer le code.

Claude Code dispose d’un Plan Mode dédié à l’analyse et à la planification en lecture seule. La documentation le recommande pour les changements multi-fichiers, les explorations de codebase et les refactors complexes. En Plan Mode, Claude pose aussi des questions de clarification avant de proposer un plan.

On peut l’activer en lançant la session avec :

claude --permission-mode plan

Ou en basculant de mode pendant une session.

Pourquoi c’est si puissant

Parce que cela force une séparation saine entre :

  • la compréhension du problème,

  • la stratégie,

  • l’exécution.

Au lieu de dire :

Refactor this authentication module.

on obtient de meilleurs résultats avec :

Analyse l’implémentation actuelle de l’authentification, identifie les dépendances,
propose un plan de migration vers une architecture hexagonale,
puis attends ma validation avant toute modification.

Cette approche apporte plusieurs bénéfices :

  • meilleur contrôle,

  • moins de changements hasardeux, et de rollback et donc une meilleure gestion des token, car les tokens c’est de l’argent 😊

  • meilleure conformité à l’architecture,

  • collaboration plus proche d’une revue technique que d’une génération brute.

7. La configuration : comprendre les vrais niveaux de priorité

Claude Code repose sur une configuration hiérarchique. C’est indispensable pour distinguer ce qui relève :

  • de préférences personnelles,

  • des règles d’équipe,

  • des ajustements locaux,

  • des contraintes d’organisation.

Les niveaux utiles au quotidien :

Les configurations sont appliquées selon l’ordre de priorité suivant : local > project > global

La doc officielle indique notamment :

  • user settings : ~/.claude/settings.json sur le poste

  • project settings : .claude/settings.json

  • local project settings : .claude/settings.local.json

Donc oui, dans l’usage courant :

  • le local écrase le projet,

  • le projet écrase le global utilisateur,

mais ce n’est pas toute l’histoire.

Structure recommandée

project-root/
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   └── skills/
├── src/
├── tests/
└── README.md

Bon usage des trois niveaux

Le niveau utilisateur sert aux préférences personnelles réutilisables partout. Le niveau projet sert aux règles communes de l’équipe, versionné sur git. Le niveau local sert aux ajustements non partagés, aux expérimentations ou à des permissions temporaires. La doc précise d’ailleurs que settings.local.json est destiné à ne pas être versionné.

8. Permissions : la sécurité avant tout

Claude Code peut lire des fichiers, exécuter des commandes et modifier le code. Il faut donc appliquer un principe simple : le moindre privilège.

La documentation officielle recommande d’utiliser permissions.deny pour empêcher l’accès à des fichiers sensibles comme les secrets, fichiers d’environnement ou credentials. Les exemples actuels utilisent une syntaxe explicite du type Read(…​) ou Bash(…​), et non de simples chemins nus.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}

Pourquoi c’est important

Parce qu’un agent efficace est aussi un agent potentiellement dangereux si on lui ouvre trop largement le périmètre.

Il faut protéger :

  • les secrets,

  • les certificats,

  • les clés privées,

  • les configurations de production,

  • les dumps de base,

  • les données personnelles,

  • certaines commandes shell trop risquées.

9. Choisir le bon modèle

Claude Code permet de changer de modèle via les commandes intégrées, notamment /model, parmi d’autres commandes slash comme /clear, /compact, /context ou /config.

En pratique, le choix dépend du niveau de complexité :

  • Opus pour les sujets complexes, les raisonnements délicats, les arbitrages d’architecture,

  • Sonnet pour l’usage quotidien,

  • Haiku pour des tâches rapides et légères. Les documents Anthropic sur le prompting et les modèles actuels mentionnent notamment Opus 4.6, Sonnet 4.6 et Haiku 4.5.

Le vrai conseil n’est pas de “toujours prendre le plus gros modèle”, mais de choisir un modèle cohérent avec la tâche et d’éviter de changer en permanence au milieu du même workflow.

Autrement dit, le modèle a son importance, mais la qualité de la collaboration avec l’agent en a probablement davantage.

Ce qui nous amène au point suivant.

10. Les prompts : apprendre à collaborer avec Claude plutôt qu’à lui donner des ordres

Lorsqu’on découvre Claude Code, on a souvent tendance à penser que tout se joue dans le modèle utilisé.

En réalité, l’un des facteurs qui influence le plus la qualité des réponses est beaucoup plus simple : la manière de formuler les demandes.

Un même modèle peut produire une réponse médiocre ou au contraire une analyse remarquable, simplement selon la façon dont le problème est présenté.

Le vrai changement de perspective consiste à comprendre qu’un prompt n’est pas une commande. C’est une manière de collaborer avec l’agent.

Le piège du prompt trop court

L’erreur la plus fréquente consiste à écrire des instructions très vagues :

Refactor this code

ou :

Improve this project

ou encore :

Fix the bug

Ces demandes paraissent simples, mais elles laissent énormément de place à l’interprétation. Claude doit alors deviner :

  • ce qui doit être amélioré ;

  • quelles contraintes respecter ;

  • jusqu’où modifier le code ;

  • quels compromis effectuer.

Parfois le résultat sera excellent, parfois beaucoup moins.

Donner un objectif, un cadre et une limite

En pratique, Claude travaille beaucoup mieux lorsqu’on lui fournit :

  • l’objectif recherché ;

  • les contraintes à respecter ;

  • les étapes attendues ;

  • les limites de son intervention.

Par exemple, au lieu de :

Refactor this authentication module.

on obtient souvent de meilleurs résultats avec :

Analyse le module d’authentification actuel.

Identifie les dépendances importantes et les violations éventuelles des principes SOLID.

Propose plusieurs options de refactor compatibles avec une architecture hexagonale.

Compare les avantages et les inconvénients de chaque solution.

Attends ma validation avant toute modification.

Cette manière de travailler se rapproche davantage d’une discussion avec un collègue expérimenté que d’une simple génération automatique de code.

Séparer l’analyse de l’exécution

Une autre bonne pratique consiste à ne pas demander immédiatement du code.

Très souvent, il est préférable de commencer par :

Explique-moi le fonctionnement de ce module.

puis :

Identifie les problèmes potentiels.

ensuite :

Propose un plan de migration.

et enfin :

Exécute uniquement la première étape.

Cette approche réduit considérablement les modifications hasardeuses et permet de garder le contrôle sur les changements effectués.

Demander à Claude de raisonner

Claude n’est pas seulement capable d’écrire du code. Il est particulièrement performant lorsqu’on lui demande d’expliquer son raisonnement.

Quelques formulations donnent souvent d’excellents résultats :

Explique ton raisonnement étape par étape.
Propose plusieurs solutions et compare-les.
Quels sont les risques de cette approche ?
Cherche les effets de bord possibles.
Quelle serait la solution la plus simple à maintenir ?

Cette manière de travailler transforme progressivement Claude Code en partenaire d’analyse et non plus seulement en générateur de code.

Le pattern "Analyse → Plan → Exécution"

Avec l’expérience, un schéma revient très souvent :

  1. Comprendre ;

  2. Planifier ;

  3. Exécuter ;

  4. Vérifier.

Par exemple :

Analyse cette classe.

Explique les problèmes de couplage et de testabilité.

Propose un plan de refactor en plusieurs étapes.

N'effectue aucune modification avant ma validation.

Puis :

Exécute uniquement l’étape 1.

Enfin :

Explique les changements réalisés et les tests à lancer.

Cette approche apporte plusieurs bénéfices :

  • moins de régressions ;

  • davantage de contrôle ;

  • une meilleure conformité à l’architecture ;

  • des réponses plus cohérentes ;

  • une collaboration plus proche d’une revue technique que d’une génération brute.

Le meilleur prompt est souvent le plus structuré

Il n’existe pas de "prompt magique".

En revanche, on constate qu’un bon prompt contient généralement quatre éléments :

  • le contexte ;

  • l’objectif ;

  • les contraintes ;

  • le résultat attendu.

Autrement dit, au lieu de demander :

Optimise cette classe.

on peut préciser :

Analyse cette classe Java.

L'objectif est d'améliorer sa testabilité et de réduire le couplage.

Respecte les principes SOLID et l'architecture hexagonale du projet.

Propose plusieurs solutions et attends ma validation avant toute modification.

La différence ne vient pas seulement du modèle utilisé.

Elle vient surtout de la qualité de la collaboration mise en place avec l’agent.

Au fond, écrire un bon prompt revient moins à savoir parler à une IA qu’à savoir formuler clairement un problème d’ingénierie.

Et c’est probablement cette compétence, plus que n’importe quelle autre, qui fait réellement la différence dans l’utilisation quotidienne de Claude Code.

11. Anti-patterns à éviter

Il y a quelques erreurs récurrentes qui dégradent fortement les résultats.

Le premier anti-pattern, c’est le prompt flou. Quand la demande est vague, Claude doit compléter les trous lui-même. Il le fait parfois bien, parfois mal.

Le deuxième, c’est l’exécution directe sans plan, surtout sur des refactors multi-fichiers.

Le troisième, c’est la session trop longue, où l’on mélange architecture, bugfix, documentation, revue, tests et brainstorming dans la même conversation.

Le quatrième, c’est un CLAUDE.md absent ou mal conçu : trop court, trop vague, ou au contraire énorme et illisible.

Le cinquième, c’est la sécurité négligée, avec des permissions trop larges et aucun filtrage des fichiers sensibles.

12. Quelques conseils pratiques qui changent vraiment le quotidien

Un bon réflexe consiste à ouvrir une nouvelle session pour chaque objectif important. Cela garde le contexte propre et évite les dérives.

Autre astuce très utile : utiliser /context pour comprendre ce qui consomme la fenêtre de contexte, puis /compact quand il faut préserver l’essentiel sans tout perdre. La doc recommande aussi d’ajouter des instructions de compaction ciblées quand on veut conserver certains points en priorité.

Enfin, dès qu’une pratique revient souvent, il faut se demander : est-ce que cela doit vivre dans CLAUDE.md, dans une skill ? C’est ce passage d’un usage improvisé à un usage structuré qui fait vraiment monter en qualité.

13. Conclusion

Claude Code n’est pas magique. Il est même assez exigeant.

Sa qualité dépend directement de la qualité du cadre fourni : le contexte, les règles, les permissions, la structure du workflow, la clarté des objectifs.

Utilisé de façon naïve, il produit parfois du code acceptable. Utilisé de façon rigoureuse, il devient autre chose : un véritable copilote d’architecture et de développement.

La différence ne vient pas seulement du modèle. Elle vient surtout de la manière de travailler avec lui.

← Article précédent