Maîtriser Claude Code Partie 3 : Configuration de projet

Voici un piège dans lequel tombent presque tous les débutants avec Claude Code : ils commencent à l'utiliser sur un projet, obtiennent des résultats médiocres et en concluent que l'outil n'est pas terrible. Puis ils voient quelqu'un d'autre obtenir des résultats incroyables sur une base de code similaire. Quelle est la différence ?

La configuration.

Une session Claude Code bien configurée ne comprend pas seulement ton code — elle comprend tes patterns, tes conventions, les préférences de ton équipe. Elle sait que tu utilises Bun au lieu de npm, que les routes API vivent dans app/api/, et que ton équipe a des opinions bien tranchées sur la gestion d'erreurs. Ce chapitre te montre comment mettre tout ça en place.

CLAUDE.md : la mémoire de ton projet

CLAUDE.md est automatiquement chargé au démarrage de Claude Code. Pense à ce fichier comme le manuel d'instructions que tu donnes à un nouveau développeur le premier jour — sauf que Claude le lit à chaque session.

Où le placer

Claude Code utilise un système hiérarchique pour charger les fichiers CLAUDE.md :

Racine du projet (le plus courant) :

Ton-projet/CLAUDE.md

Commite-le dans git. Partage-le avec ton équipe. C'est ce que tu veux dans 90 % des cas.

Emplacement alternatif :

Ton-projet/.claude/CLAUDE.md

Même effet, mais garde la racine de ton projet plus propre.

Global (s'applique à tous les projets) :

~/.claude/CLAUDE.md

Préférences personnelles qui te suivent partout. Idéal pour des choses comme « je préfère les tabs aux espaces » ou « toujours utiliser le mode strict de TypeScript ».

Variante locale (gitignorée) :

Ton-projet/CLAUDE.local.md

Réglages personnels que tu ne veux pas commiter. Clés API, paramètres expérimentaux, ou ce style de code controversé que ton équipe ne partage pas.

Support monorepo

C'est là que ça devient malin. Dans un monorepo, tu pourrais avoir :

Monorepo/
├── CLAUDE.md              # Chargé pour tout
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Chargé quand tu travailles dans web/
│   └── api/
│       └── CLAUDE.md      # Chargé quand tu travailles dans api/
└── packages/
    └── shared/
        └── CLAUDE.md      # Chargé quand tu travailles dans shared/

Quand tu lances claude depuis monorepo/apps/web, le CLAUDE.md racine et celui spécifique à web sont tous deux chargés. Les fichiers CLAUDE.md des sous-répertoires sont récupérés à la demande lorsque tu travailles avec des fichiers dans ces répertoires.

Que mettre dans CLAUDE.md

Un bon CLAUDE.md répond à trois questions :

QUOI — Qu'est-ce que ce projet ? Quelle est la stack technique ? Quelle est la structure des dossiers ?

POURQUOI — Quel est l'objectif ? Quel problème résout-il ? Quels sont les concepts métier clés ?

COMMENT — Comment y travaille-t-on ? Quelles commandes lancent les tests ? Quel est le processus de déploiement ? Comment vérifie-t-on les changements ?

Un template pratique

# Nom du Projet

Une phrase : ce que c'est et ce que ça fait.

## Stack Technique

- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma + PostgreSQL
- Jest pour les tests

## Structure des Dossiers

Src/
├── app/           # Routes Next.js
├── components/    # Composants UI réutilisables
├── lib/           # Utilitaires et helpers
├── services/      # Logique métier
└── types/         # Interfaces TypeScript

## Commandes

- `bun dev` - Lancer le serveur de développement (port 3000)
- `bun test` - Lancer les tests Jest
- `bun lint` - Vérification ESLint
- `bun build` - Build de production
- `bunx prisma studio` - Interface graphique de la base de données

## Conventions de Code

- Utiliser les alias de chemins (@/components, @/lib, @/services)
- Server components par défaut, 'use client' seulement quand c'est nécessaire
- Toutes les fonctions doivent avoir des paramètres et types de retour typés
- Garder les méthodes courtes avec une responsabilité unique
- Tests colocalisés avec les composants (Component.test.tsx)

## Notes Importantes

- Ne jamais commiter les fichiers .env
- Lancer `bunx prisma generate` après les changements de schéma
- Les routes API utilisent Zod pour la validation à l'exécution
- L'authentification utilise NextAuth avec stratégie JWT

Exemples spécifiques aux frameworks

Next.js App Router :

## Conventions Next.js

- Server Components par défaut
- Utiliser 'use client' seulement pour useState, useEffect, les event handlers
- Récupération de données : appels DB directs dans les Server Components, SWR dans les Client
- Routes API : app/api/[route]/route.ts
- Nommage : PascalCase pour les composants, camelCase pour les utilitaires

Python FastAPI :

## Conventions FastAPI

- Type hints sur toutes les fonctions
- Async/await pour les opérations I/O
- Modèles Pydantic v2 pour la validation requête/réponse
- Injection de dépendances pour les services
- Alembic pour les migrations : `alembic upgrade head`

Go :

## Conventions Go

- Layout de projet standard (cmd/, internal/, pkg/)
- Utiliser les interfaces pour la testabilité
- Wrapping d'erreurs avec fmt.Errorf et %w
- Tests dans le même package avec suffixe _test.go
- Lancer `go test ./...` avant les commits

Le système d'imports

Les fichiers CLAUDE.md peuvent importer d'autres fichiers avec la syntaxe @chemin/vers/fichier. Ça garde ton fichier principal léger tout en fournissant un contexte complet.

# Aperçu du Projet

Voir @README.md pour la description détaillée du projet.
Voir @docs/api-patterns.md pour les conventions d'API.
Voir @docs/testing-guide.md pour les exigences de test.

## Référence Rapide

@package.json montre les scripts npm disponibles.

Comment fonctionnent les imports :

• Les chemins relatifs sont résolus depuis l'emplacement du fichier CLAUDE.md
• Les imports peuvent être récursifs (jusqu'à 5 niveaux de profondeur)
• Les blocs de code sont exclus (les imports dans les ``` ne sont pas évalués)
• Les imports ultérieurs prennent le dessus sur les précédents

Organisation avec un répertoire rules :

Pour les projets plus importants, tu peux découper les instructions en plusieurs fichiers :

.claude/
├── CLAUDE.md           # Fichier principal
└── rules/
    ├── coding-style.md
    ├── testing.md
    ├── security.md
    └── deployment.md

Tous les fichiers .md dans .claude/rules/ sont automatiquement chargés comme mémoire de projet.

Le raccourci clavier

Voici une astuce de productivité que la plupart des gens ignorent : pendant n'importe quelle session Claude Code, appuie sur # pour ajouter des instructions à ton CLAUDE.md à la volée.

Tu te retrouves à répéter la même instruction ? Appuie sur # et ajoute-la de façon permanente. Claude s'en souviendra la prochaine fois.

Settings.json : permissions et automatisation

Au-delà de CLAUDE.md, tu peux configurer le comportement de Claude avec des fichiers de paramètres.

Emplacements des fichiers

~/.claude/settings.json           # Global (tous les projets)
.claude/settings.json             # Projet (commité dans git)
.claude/settings.local.json       # Local (gitignoré)

Les paramètres fusionnent par ordre de priorité : local > projet > global.

Configuration des permissions

Contrôle ce que Claude peut faire sans demander :

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Read(./tests/**)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(bun test:*)",
      "Bash(bun lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm *)",
      "Bash(git push *)"
    ]
  }
}

Comment les règles sont évaluées :

1. Les règles deny sont vérifiées en premier (bloquent quoi qu'il arrive)
2. Les règles allow sont vérifiées ensuite (autorisent si elles correspondent)
3. Tout le reste demande une approbation

La liste deny est ta frontière de sécurité. Les fichiers correspondant aux patterns deny deviennent complètement invisibles pour Claude — il ne peut même pas voir qu'ils existent.

Hooks : actions automatisées

Les hooks exécutent des commandes à des moments spécifiques du cycle de vie de Claude :

PreToolUse — Avant que Claude utilise un outil (peut bloquer l'action)

PostToolUse — Après la fin d'un outil (idéal pour les formateurs)

SessionStart — Au démarrage d'une session (configuration de l'environnement)

Notification — Quand Claude envoie des notifications

Stop — Quand Claude finit de répondre

Exemple : formater automatiquement les fichiers Python après modification :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then black \"$CLAUDE_FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

Exemple : empêcher les modifications aux configs de production :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write(./config/production.*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Blocked: Cannot modify production config' && exit 1"
          }
        ]
      }
    ]
  }
}

Astuce : Tu peux aussi configurer les hooks de manière interactive avec la commande /hooks pendant une session.

Configuration d'équipe

Pour les équipes, voici ce qu'il faut commiter vs gitignorer :

Commite ces fichiers (partagés avec l'équipe) :

• CLAUDE.md — Instructions de projet que tout le monde doit suivre
• .claude/settings.json — Permissions et hooks partagés
• .claude/rules/ — Fichiers d'instructions organisés
• .claude/commands/ — Commandes slash d'équipe (couvert dans la Partie 4)

Gitignore ces fichiers (personnels) :

• CLAUDE.local.md — Tes préférences personnelles
• .claude/settings.local.json — Tes surcharges locales

Ça permet aux équipes d'imposer des standards tout en laissant chacun personnaliser son expérience.

Bonnes pratiques qui comptent vraiment

Reste concis

La recherche suggère que les LLMs de pointe peuvent suivre de manière fiable environ 150-200 instructions. Au-delà, l'adhérence diminue. Les modèles plus petits en gèrent encore moins.

Ne fais pas ça :

## Directives Générales
- Écrire du code propre
- Suivre les meilleures pratiques
- Utiliser des noms de variables parlants
- Garder les fonctions courtes

Claude sait déjà tout ça. Tu gaspilles un espace d'instruction précieux sur des conseils génériques.

Fais plutôt ça :

## Règles Spécifiques au Projet
- Les réponses d'erreur utilisent la classe ApiError de @/lib/errors
- Toutes les dates stockées en UTC, affichées dans le fuseau de l'utilisateur
- Feature flags vérifiés via @/lib/features.isEnabled()
- Format de log : [LEVEL] [SERVICE] [REQUEST_ID] message

N'inclus que ce qui est unique à ton projet.

Itère comme un prompt

Ton CLAUDE.md fait partie du prompt de Claude. Traite-le comme tel.

• Teste si les instructions changent réellement le comportement
• Ajoute de l'emphase pour les règles critiques : « IMPORTANT : » ou « TU DOIS »
• Supprime les instructions qui ne sont pas suivies
• Passe-le de temps en temps dans l'améliorateur de prompts de Claude

Chez Anthropic, ils peaufinent les fichiers CLAUDE.md de la même façon qu'ils peaufinent les prompts — itération continue basée sur ce qui fonctionne vraiment.

Utilise /init comme point de départ

Lancer /init génère un CLAUDE.md en analysant ton projet. Mais c'est un point de départ, pas un produit fini.

La version auto-générée capture les patterns évidents (stack technique, structure des dossiers, commandes courantes) mais passe à côté du savoir tribal de ton équipe. Revois ce que Claude produit et ajoute ce qui compte le plus dans ta façon de travailler au quotidien.

Relance /init après des fonctionnalités majeures ou des refactors pour capter les nouveaux patterns.

Tester ta configuration

Après avoir configuré ton CLAUDE.md, vérifie que ça a fonctionné :

Claude

Puis demande :

Résume la configuration du projet et les conventions que tu comprends.
Quelle est la stack technique ? Quelles commandes dois-tu utiliser pour les tests ?

Si Claude rate quelque chose d'important, ton CLAUDE.md a besoin d'être retravaillé.

La suite

Tu sais maintenant comment configurer Claude Code pour ton projet spécifique. Mais la configuration a ses limites — la vraie puissance vient de l'extension de Claude avec des commandes personnalisées.

Dans la Partie 4 : Commandes Personnalisées, nous allons construire des commandes slash qui encodent tes workflows en actions réutilisables. Pense à ça comme enseigner à Claude les raccourcis de ton équipe.