Le Guide Complet de Configuration Claude Code (2026)

Tu viens d'installer Claude Code. Tu as tapé claude dans ton terminal et... ça marche. Il peut lire tes fichiers, exécuter des commandes, écrire du code. Plutôt cool.

Mais voilà le truc : tu n'utilises que 10% de sa puissance.

Dans notre analyse de plus de 800 configurations sur jeanclaudecode.ai, le score moyen est de 3.2 sur 10. La plupart des gens installent Claude Code, écrivent deux-trois lignes d'instructions, et s'arrêtent là. Dix minutes de configuration séparent un chatbot basique d'un véritable partenaire de développement.

Corrigeons ça tout de suite.

Le fichier qui change tout

Crée un fichier appelé CLAUDE.md à la racine de ton projet. C'est tout. C'est la chose la plus importante que tu feras aujourd'hui.

touch CLAUDE.md

CLAUDE.md est la première chose que Claude lit quand tu démarres une session. Pense à ça comme un briefing — tu dis à Claude avec qui il travaille, à quoi ressemble le projet, et quelles sont les règles.

Voici un fichier minimal pour commencer. Ouvre CLAUDE.md et colle ça :

# Mon Projet

## Stack Technique
- Next.js 15, TypeScript, PostgreSQL

## Commandes
- `npm run dev` — serveur de dev
- `npm run test` — lancer les tests
- `npm run build` — build de production

## Règles
- Toujours lancer les tests avant de dire qu'une tâche est terminée
- Ne jamais modifier les fichiers dans src/legacy/

Cinq lignes de stack technique. Trois commandes. Deux règles. C'est tout ce qu'il faut pour démarrer.

Essaie maintenant. Ouvre Claude Code et demande : « Lis mon CLAUDE.md et dis-moi quel est ce projet. » Claude devrait te décrire ton projet. S'il le fait, c'est bon. Sinon, vérifie que le fichier est bien à la racine (pas dans un sous-dossier).

Tu viens de donner à Claude quelque chose que 68% des setups n'ont pas : une connaissance basique du projet.

On monte en gamme : le CLAUDE.md des meilleurs setups

Ce fichier minimal marche. Mais les setups qui scorent 7+ dans notre analyse vont plus loin. Voici ce qu'ils ajoutent — et pourquoi chaque section compte.

Section architecture (dans 78% des meilleurs setups)

Claude ne sait pas où vivent tes fichiers. Sans carte, il devine — et il devine mal. Ajoute ça :

## Architecture
- src/app/ — Pages et routes API App Router
- src/lib/ — Utilitaires partagés et client base de données
- src/components/ — Composants React (tests colocalisés)

Maintenant, quand tu dis « crée une nouvelle route API », Claude la met dans src/app/api/ au lieu d'inventer un emplacement au hasard.

Section conventions (65% des meilleurs setups)

Tu as des avis sur l'apparence du code. Claude ne les connaît pas si tu ne les exprimes pas :

## Conventions
- Messages de commit impératifs, minuscules, sans point
- Un composant par fichier, exports nommés uniquement
- Toutes les routes API valident les entrées avec des schémas zod

Sois précis. « Écris du code propre » ne donne rien à Claude. « Utilise zod pour toute validation d'entrée API » lui donne une règle concrète à suivre.

Section problèmes connus (seulement 34% des meilleurs setups — la plus grosse opportunité manquée)

C'est la section que la plupart des gens sautent, et c'est celle qui t'évite le plus de frustration :

## Problèmes Connus
- Le webhook Stripe nécessite un parsing `raw` du body — pas de middleware express.json() sur /api/webhooks/stripe
- Safari ne supporte pas `structuredClone` dans les workers — utiliser le polyfill dans src/lib/clone.ts
- Le CI a 4 Go de RAM — les tests qui dépassent cette limite échouent silencieusement (OOM)

Chaque fois que Claude fait une erreur que tu as déjà vue, ajoute-la ici. Avec le temps, cette section devient la plus précieuse du fichier — un historique vivant de « ne marche pas sur cette mine ».

Section	Impact	Présente dans les meilleurs setups
Stack technique	Moyen	92%
Architecture / plan de fichiers	Élevé	78%
Conventions	Élevé	65%
Commandes	Moyen	71%
Règles / contraintes explicites	Très élevé	84%
Patterns d'erreurs / problèmes connus	Élevé	34%

Maintenant les permissions (pour que Claude arrête de te demander confirmation pour tout)

Par défaut, Claude demande la permission avant d'exécuter la moindre commande shell. À chaque. Fois. Ça devient vite pénible.

La solution : créer un fichier de configuration qui dit à Claude ce qu'il peut faire sans demander.

mkdir -p .claude

Maintenant crée .claude/settings.json :

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run build)",
      "Bash(npm run lint*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

La liste allow dit « vas-y, ne demande pas ». La liste deny dit « ne fais jamais ça, même si je te le demande par erreur ».

Important : Ne mets jamais "Bash(*)" dans la liste allow. Ça donne à Claude un accès shell complet sans garde-fou. Sois précis sur ce qui est autorisé.

Essaie de lancer Claude Code maintenant. Demande-lui de vérifier le git status ou de lancer les tests. Tu vois comment il le fait tout seul ? Pas de popup de permission. Ce flow est ce qui sépare les setups que les gens abandonnent de ceux qu'ils utilisent vraiment chaque jour.

Ajouter des rules qui s'activent automatiquement

Tu te demandes peut-être : « Je devrais mettre toutes mes conventions dans CLAUDE.md ? » Tu pourrais. Mais il y a plus malin.

Les rules sont des fichiers markdown qui s'activent selon les fichiers sur lesquels Claude travaille. Quand Claude modifie un .tsx, il charge tes règles frontend. Quand il touche un fichier de migration, il charge tes règles base de données. Quand il travaille sur du CSS, il ne perd pas de temps à lire tes conventions SQL.

Crée le répertoire des rules :

mkdir -p .claude/rules

Voici une règle frontend. Enregistre-la dans .claude/rules/frontend.md :

---
globs: ["*.tsx", "*.jsx", "*.css"]
---

- Utiliser des exports nommés, pas des exports par défaut
- Chaque composant doit avoir un fichier .test.tsx correspondant
- CSS modules uniquement — pas de styles inline sauf pour les valeurs dynamiques
- Toutes les images ont besoin d'un texte alt (exigence d'accessibilité)

Et une règle base de données — enregistre dans .claude/rules/database.md :

---
globs: ["*.sql", "**/migrations/**", "**/prisma/**"]
---

- Ne jamais modifier les fichiers de migration existants
- Toutes les requêtes doivent utiliser des entrées paramétrées — jamais de concaténation de chaînes
- Inclure une logique de rollback dans chaque migration

La ligne globs en haut est le déclencheur. Quand Claude lit ou modifie un fichier correspondant à ce pattern, la rule se charge automatiquement. Pas de tokens gaspillés quand ce n'est pas pertinent.

Regarde ce que tu as construit

Voici à quoi ton projet devrait ressembler maintenant :

ton-projet/
├── CLAUDE.md                          # Ton briefing projet
├── .claude/
│   ├── settings.json                  # Permissions (commité, partagé avec l'équipe)
│   └── rules/
│       ├── frontend.md                # S'active pour .tsx, .jsx, .css
│       └── database.md                # S'active pour .sql, migrations
├── .gitignore
└── src/
    └── ...

Un dernier truc — ajoute cette ligne à ton .gitignore :

# Paramètres locaux Claude Code
.claude/settings.local.json

Le fichier settings.local.json est pour tes préférences personnelles (comme ton modèle préféré). Il ne devrait pas être dans le contrôle de version. Le settings.json normal ? Commite-le — c'est de la configuration d'équipe partagée.

Vérifie que tout marche

Ouvre Claude Code et essaie ça :

> Lis mon CLAUDE.md et dis-moi quel est ce projet. Quelles rules vois-tu ?

Claude devrait décrire ton projet, lister les rules trouvées dans .claude/rules/, et confirmer les permissions de settings.json. S'il y arrive, c'est bon. S'il manque quelque chose, vérifie que tes fichiers sont au bon endroit.

Tu peux aussi analyser ton setup avec notre outil — il vérifie les quatre couches (CLAUDE.md, settings, rules, structure de répertoires) et te dit exactement ce qui fonctionne et ce qui manque.

Les erreurs qui plombent les setups

Après avoir analysé des centaines de setups, voici les patterns qui obtiennent systématiquement des scores bas :

Des instructions vagues. « Écris du code propre » et « suis les bonnes pratiques » ne donnent strictement rien à Claude. Compare : « valide les entrées correctement » (inutile) vs « Utilise zod pour toute validation d'entrée API » (actionnable).

Pas de liste de permissions. Chaque appel d'outil nécessite une approbation manuelle, le développeur se frustre, abandonne Claude Code, et conclut que ce n'est pas productif. Cinq minutes de settings.json règlent ce problème.

Tout fourré dans CLAUDE.md. Tes conventions base de données ne servent à rien quand Claude modifie du CSS. Déplace les instructions spécifiques aux fichiers dans des fichiers rules — ça garde le contexte concentré et économise des tokens.

Pas de section architecture. Sans carte des fichiers, Claude met les fichiers dans les mauvais répertoires, utilise les mauvais chemins d'import, et génère du code qui ne correspond pas à ton projet. Une section architecture de 5 lignes évite ça.

Pas de .gitignore pour les paramètres locaux. Les membres de l'équipe écrasent les préférences des autres, ou pire, des clés API finissent dans le contrôle de version.

Et maintenant ?

Tu as une base solide. Ton CLAUDE.md informe Claude sur ton projet, tes settings le gardent productif, et tes rules le gardent sur les rails.

Prêt pour la suite ? Voici où aller :

• Automatise le travail répétitif — les hooks qui formatent le code automatiquement, les skills qui lancent des workflows multi-étapes avec une commande slash, et quand utiliser quoi
• Connecte Claude à tes outils — les serveurs MCP qui permettent à Claude d'interroger ta base de données, chercher dans tes issues GitHub, et récupérer les erreurs Sentry directement
• Maîtrise ta facture — les vrais chiffres de coût, l'astuce /compact, et quand Opus vaut le premium

Questions fréquentes

Où doit aller CLAUDE.md — à la racine du projet ou dans le répertoire .claude ?

À la racine du projet. Claude Code cherche CLAUDE.md à la racine de ton répertoire de travail en premier. Tu peux aussi créer ~/.claude/CLAUDE.md pour des instructions globales qui s'appliquent à tous tes projets. Si les deux existent, les deux sont chargés — global d'abord, puis spécifique au projet.

Toute l'équipe peut partager un CLAUDE.md ?

Oui, et elle devrait. CLAUDE.md appartient à ton dépôt. C'est du contexte partagé — architecture du projet, conventions, commandes. Pour les préférences personnelles (comme ton modèle préféré ou tes alias), utilise .claude/settings.local.json qui reste gitignored.

CLAUDE.md doit faire combien de lignes ?

Les meilleurs setups que nous avons analysés font entre 100 et 500 lignes. En dessous de 100, il te manque probablement du contexte critique (architecture, conventions, problèmes connus). Au-dessus de 500, tu inclus probablement des choses qui devraient être dans des fichiers rules. L'objectif, c'est des instructions concentrées et à fort signal.

Claude Code marche sans tout ce setup ?

Techniquement oui, mais mal. Sans CLAUDE.md, Claude n'a aucune connaissance de la structure de ton projet, de tes conventions ou de tes contraintes. Il génère quand même du code, mais il met les fichiers aux mauvais endroits, utilise les mauvais patterns, et ignore les règles spécifiques à ton projet. Nos données montrent que les setups non configurés ont un score moyen de 1.8/10. Le setup n'est pas optionnel si tu veux de vrais gains de productivité.

À quelle fréquence mettre à jour CLAUDE.md ?

Quand ton projet change : nouvelles conventions, nouveaux outils, nouveaux problèmes connus. Une bonne habitude est d'ajouter une entrée « Problèmes Connus » chaque fois que Claude fait une erreur qui ne devrait pas se reproduire. Avec le temps, CLAUDE.md devient un document vivant qui empêche les mêmes erreurs de revenir — et c'est l'un des usages les plus précieux du fichier.