Bonnes pratiques Claude Code

La plupart des développeurs traitent Claude Code comme un chatbot. Tu tapes une demande vague, tu obtiens un résultat vague, tu blâmes l'outil. Les développeurs qui obtiennent des résultats 10x font quelque chose de différent. Ils ont construit des systèmes autour de Claude Code pour que chaque session soit plus productive que la précédente.

Voici les cinq habitudes qui séparent les ingénieurs qui livrent de ceux qui galèrent. Pas de plugins, pas de configuration spéciale. Juste un meilleur modèle d'utilisation pour travailler avec l'IA agentique.

1. Le développement PRD-first

La plus grosse erreur en codage agentique, c'est de démarrer sans plan. Tu ouvres Claude Code, tu décris une fonctionnalité en deux phrases, tu le lâches. Vingt minutes plus tard tu es à trois tangentes de profondeur dans du code qui ne correspond pas à ce dont tu avais vraiment besoin.

Un Product Requirements Document règle ça. Pas un spec corporate de 50 pages. Un fichier markdown léger qui prend cinq minutes.

# Feature: User Authentication
 
## Mission
 
Add email/password authentication with session management.
 
## In Scope
 
- Sign up, login, logout flows
- Password hashing with bcrypt
- JWT session tokens with 24-hour expiry
- Protected route middleware
 
## Out of Scope
 
- OAuth providers (Phase 2)
- Two-factor authentication (Phase 3)
- Password reset flow (separate task)
 
## Architecture
 
- Auth routes: /api/auth/signup, /api/auth/login, /api/auth/logout
- Middleware: src/middleware/auth.ts
- Database: users table with email, password_hash, created_at

Sans PRD, le contexte dérive. Claude commence à prendre des décisions architecturales que tu n'as jamais discutées. Il ajoute OAuth parce que "c'est ce que la plupart des systèmes d'auth incluent." Il construit un flux de réinitialisation de mot de passe parce que ça lui semblait pertinent. Tu passes plus de temps à corriger le cap qu'à construire.

Avec un PRD, chaque session a des garde-fous. Tu dis à Claude "lis le PRD, puis implémente le flux d'inscription." Il sait exactement ce qui est dans le scope, ce qui ne l'est pas, et quels patterns suivre. Quand une section est livrée, tu demandes "d'après le PRD, qu'est-ce qu'on construit ensuite ?" et il reste sur la bonne voie.

Ça marche aussi sur les projets existants. Pour du travail greenfield, le PRD est ton brief MVP. Pour du brownfield, le PRD documente ce que tu as déjà et explique ensuite ce que tu veux ensuite. Des points de départ différents, même structure.

Le PRD résout aussi le problème multi-session. Claude Code n'a pas de mémoire entre les conversations, mais ton PRD si. Chaque nouvelle session s'ouvre avec le même document, tu reprends exactement là où tu t'es arrêté.

2. Architecture de règles modulaires

La plupart des développeurs font la même erreur avec leur CLAUDE.md : ils y mettent tout. Stack tech, conventions de codage, règles de tests, procédures de déploiement, patterns API. Un gigantesque mur d'instructions.

Le problème, c'est le gaspillage de contexte. Claude charge tout ton CLAUDE.md au démarrage de la session, et chaque token dedans se bat pour l'attention. Tes patterns React se chargent pendant que tu débogues une migration de base de données. Tes règles de déploiement se chargent pendant que tu écris des tests unitaires.

Une meilleure approche : garde CLAUDE.md léger et pointe vers des docs spécifiques aux tâches.

# CLAUDE.md
 
## Tech Stack
 
- Next.js 15 with App Router
- TypeScript strict mode
- PostgreSQL with Prisma ORM
- Tailwind CSS
 
## Standards
 
- Use path aliases (@/components, @/lib, @/utils)
- All functions require explicit return types
- Error handling: guard clauses with early returns
- Tests required for business logic
 
## Reference Docs (load when relevant)
 
- Frontend conventions: .claude/skills/react/SKILL.md
- API patterns: .claude/skills/api/SKILL.md
- Database rules: .claude/skills/postgres/SKILL.md
- Deployment: .claude/skills/infra/SKILL.md

Une quinzaine de lignes. Ça couvre les règles universelles qui s'appliquent à chaque tâche. Le savoir détaillé vit dans des fichiers séparés que Claude charge seulement quand la tâche le demande.

La structure des dossiers :

.claude/
├── skills/
│   ├── react/          # Component patterns, hooks, state
│   ├── api/            # Route conventions, validation, auth
│   ├── postgres/       # Schema patterns, query optimization
│   └── infra/          # Docker, CI/CD, deployment
└── CLAUDE.md           # Lightweight global rules

Compare ça à l'habitude "tout dans un fichier" où 200+ lignes d'instructions se trouvent dans CLAUDE.md. Ce fichier brûle du contexte à chaque session, pertinent ou non. L'approche modulaire charge le savoir domaine à la demande.

3. Transforme tout en commandes

Si tu prompts quelque chose deux fois, ça devrait être une commande.

Une commande dans Claude Code c'est un fichier markdown dans .claude/commands/ qui définit un workflow réutilisable. Quand tu tapes /commit, Claude lit le fichier de commande et suit les instructions. Pas de retape. Pas d'étapes oubliées.

Voici à quoi ressemble une commande simple :

# /commit
 
Review all staged changes with `git diff --cached`.
Write a commit message that:
 
- Starts with a verb (add, fix, update, remove)
- Summarizes the WHY, not the WHAT
- Stays under 72 characters
- Uses lowercase
 
Create the commit. Do not push.

Sauvegarde ça dans .claude/commands/commit.md et tu n'écriras plus jamais d'instructions de commit.

Cinq commandes de démarrage qui valent la peine d'être créées :

• /commit pour des commits git cohérents et bien formatés
• /review pour la revue de code selon les standards de ton projet
• /plan pour générer un plan d'implémentation structuré avant d'écrire du code
• /prime pour charger le contexte de session au début de chaque conversation
• /execute pour exécuter un document de plan créé dans une session précédente

Chaque commande prend cinq minutes à écrire et économise des centaines de prompts sur la durée de vie d'un projet. Elles imposent aussi de la cohérence. Tes commits suivent toujours le même format. Tes revues de code vérifient toujours les mêmes choses. L'effet composé est réel.

4. Le reset de contexte

C'est l'habitude qui semble contre-intuitive : la planification et l'exécution doivent se passer dans des conversations séparées.

Le flux :

1. Session de planification : recherche le problème, discute des compromis, explore les approches. Claude produit un document de plan structuré (un fichier markdown sauvegardé dans ton projet).
2. Efface le contexte : quitte entièrement la conversation. Tue la session.
3. Session d'exécution : repart de zéro. Donne à Claude seulement le document de plan de l'étape une. Rien d'autre.

Pourquoi faire ça ? Parce que la dégradation de la fenêtre de contexte est réelle.

Après une longue conversation de planification, le contexte de Claude est plein de tangentes exploratoires, d'approches rejetées, et de raisonnements intermédiaires qui ne s'appliquent plus. Quand tu dis ensuite "okay, maintenant construis-le," Claude transporte tout ce bruit dans l'exécution. Il pourrait éviter une approche que vous avez discutée et écartée, même si ton plan final la recommande. Il pourrait transporter des suppositions du début de la conversation que tu as corrigées plus tard.

Un contexte frais avec juste le plan signifie que Claude démarre l'exécution avec la tête claire. Pas de bagages de la phase de planification. Pas de suppositions obsolètes. Juste le spec. Et parce que tu ne brûles pas de tokens sur l'historique de planification, Claude a plus de place pour raisonner sur les détails d'implémentation et vérifier son travail.

Le document de plan doit se suffire à lui-même. Un bon plan inclut la description de la fonctionnalité, la user story, le contexte architectural, les références aux composants concernés, et une décomposition tâche par tâche. Si Claude a besoin de poser des questions de clarification pendant l'exécution, ton plan a des lacunes.

En pratique :

# Planning session
claude "Research auth patterns for our Next.js app and create
an implementation plan. Save it to docs/auth-plan.md"
 
# (exit, start new session)
 
# Execution session
claude "Read docs/auth-plan.md and implement Phase 1"

Le document de plan agit comme une passation entre ton cerveau de planification et ton cerveau d'exécution. Les deux sessions sont plus nettes parce qu'aucune n'essaie de faire les deux boulots.

5. L'état d'esprit d'évolution du système

Chaque bug est un échec du système, pas une erreur ponctuelle. L'écart entre le bon et le grand engineering agentique, c'est de savoir si tu corriges l'instance ou si tu corriges le système.

Trois vrais exemples :

Mauvais style d'import. Claude continue à utiliser des imports relatifs (../../components/Button) au lieu de tes path aliases. Tu pourrais corriger chacun à la main. Ou tu ajoutes une ligne à CLAUDE.md : "Always use @ path aliases for imports, never relative paths." Le bug ne revient jamais.

Oubli de lancer les tests. Tu termines une fonctionnalité, tu push vers CI, les tests échouent parce que Claude ne les a jamais lancés en local. Au lieu de te souvenir de prompter "lance les tests" à chaque fois, tu mets à jour ton template de commande /execute pour inclure une étape de test obligatoire à la fin de chaque implémentation. Maintenant chaque session d'exécution se termine par un run de tests par défaut.

Mauvais flux d'auth. Claude construit une auth JWT avec des cookies alors que ton projet utilise des bearer tokens dans les headers. C'est arrivé parce qu'il n'y a pas de document de référence pour tes patterns d'auth. Tu crées .claude/skills/auth/SKILL.md avec ton format de token, tes conventions de headers, et tes patterns de middleware. La prochaine fois que quelqu'un (y compris toi dans le futur) travaille sur l'auth, Claude charge automatiquement les bons patterns.

Le pattern est toujours le même : quelque chose se passe mal, tu remontes jusqu'à une instruction manquante ou une référence manquante, et tu l'ajoutes à ton système. Au fil des semaines, ta configuration se resserre. Claude fait moins d'erreurs parce que ton système a moins de lacunes.

Une façon pratique de créer l'habitude : après chaque fonctionnalité, demande à Claude de revoir tes règles et commandes, de comparer l'exécution au plan, et de suggérer quoi améliorer. "Read CLAUDE.md and the commands we used. What rules or process changes would have prevented the issues we hit?" Ça transforme l'évolution du système d'une réflexion après coup en une étape de routine.

C'est ça qui sépare un utilisateur de Claude Code d'un praticien de Claude Code. L'utilisateur corrige les bugs. Le praticien corrige le système qui a produit le bug.

Tout assembler

Ces cinq habitudes ne sont pas des conseils indépendants. Elles forment un système.

Le PRD cadre ton travail. Les règles modulaires gardent le contexte propre. Les commandes tuent la répétition. Les resets de contexte gardent les sessions nettes. L'évolution du système améliore tout ça avec le temps.

Rien de tout ça n'a besoin de nouveaux outils ou de configurations coûteuses. C'est un ensemble d'habitudes qui s'accumulent avec chaque projet que tu construis. Commence par celle qui répond à ta plus grande douleur aujourd'hui, et ajoute les autres au fur et à mesure.