Best Practices

Recommandations consolidées à partir des 10 projets actifs avec Claude Code dans mon lab.

1. Structure du fichier CLAUDE.md

Un fichier CLAUDE.md efficace contient ces sections clés :

CLAUDE.md
# Nom du Projet

## Description
Brève description du projet et de son objectif.

## Stack Technique
- Frontend: [...]
- Backend: [...]
- Base de données: [...]

## Mode de Fonctionnement
- Mode Autonome activé (/autopilot)
- Ne jamais demander autorisation si confiance établie
- Workflow: implement → test → commit → repeat

## Règles Obligatoires
- Toujours lancer les tests avant commit
- Utiliser les conventional commits (feat:, fix:, etc.)
- TDD: Red → Green → Refactor

## Token Optimization
- Utiliser `/clear` entre tâches indépendantes
- Utiliser `/compact` proactivement
- Préférer haiku pour recherches, sonnet pour analyse

## Commandes Fréquentes
```bash
npm run test        # Lancer les tests
npm run build       # Build production
npm run lint        # Vérification code
```

2. Workflow de développement

Cycle recommandé

1

Comprendre

Lire les specs, explorer le code existant

2

Tester (Red)

Écrire les tests qui échouent

3

Implémenter (Green)

Code minimal pour faire passer les tests

4

Refactor

Améliorer le code sans casser les tests

5

Valider

Lint, build, tests complets

6

Commiter

Conventional commit avec message clair

Règle d'or

3. Gestion du contexte

Commandes essentielles

Commande Quand l'utiliser Impact tokens
/clear Entre tâches indépendantes Reset complet
/compact Proactivement (avant 80%) -50% environ
mgrep Pour toute recherche -80% vs Grep/Glob

Choix des modèles subagents

haiku

$

  • Recherches dans le code
  • Explorations
  • Tâches légères
Défaut recommandé

sonnet

$$

  • Analyse de code
  • Code review
  • Refactoring

opus

$$$

  • Architecture
  • Décisions complexes
  • Nouveaux patterns

4. Conventional Commits

Structure obligatoire pour tous les commits :

feat:

Nouvelle fonctionnalité

fix:

Correction de bug

docs:

Documentation

test:

Ajout/modification tests

refactor:

Refactoring sans changement fonctionnel

chore:

Maintenance, dépendances

# Exemples de bons messages de commit
feat: add user authentication with JWT
fix: resolve race condition in WebSocket handler
docs: update API documentation for v2 endpoints
test: add integration tests for payment flow
refactor: extract validation logic to separate module

5. Fichiers de suivi

Structure recommandée du dossier .claude/

.claude/
├── CLAUDE.md          # Instructions projet (obligatoire)
├── session.md         # État courant, contexte de travail
├── decisions.md       # Décisions architecturales (ADR)
└── backlog/           # Gestion stories (sans GitLab)
    ├── SPEC-001.md
    ├── SPEC-002.md
    └── ...

session.md

Fichier de persistance du contexte entre sessions :

session.md
# Session courante

## Dernière tâche
- Implémentation de SPEC-007 (authentification OAuth)

## En cours
- [ ] Tests d'intégration OAuth
- [ ] Documentation API

## Blocages
- Aucun

## Notes
- Utiliser la librairie passport.js
- Token refresh toutes les 15min

6. Anti-patterns à éviter

❌

Demandes trop larges

"Refais tout le module" → Préférer des tâches atomiques

❌

Ignorer les erreurs de tests

"Les tests échouent mais ça marche" → Non acceptable

❌

Commit sans validation

Push immédiat sans lancer les tests → Risque de régression

❌

/autopilot non supervisé

Mode autonome sur code critique sans review → Dangereux

❌

Contexte saturé

Attendre 95% pour /compact → Perte de qualité

❌

Over-engineering

Abstractions prématurées → YAGNI

7. Signaux de qualité

Au-delà du TDD et des conventional commits, ces signaux permettent de mesurer et maintenir la qualité du code généré par Claude Code :

Analyse statique

ESLint / Clippy

Linter configuré en mode strict. Exécution obligatoire avant chaque commit. Claude Code doit corriger tous les warnings.

# TypeScript
npx eslint . --max-warnings 0

# Rust
cargo clippy -- -D warnings

Complexité cyclomatique

Surveiller la complexité des fonctions générées. Seuil recommandé : max 10 par fonction. Outils : eslint-plugin-complexity, cargo-geiger.

Imports et dépendances

Détecter les imports inutiles et dépendances non utilisées. Outils : knip (TS), cargo-udeps (Rust).

Audit de sécurité

Scanner les dépendances pour les vulnérabilités connues. Exécution régulière en CI.

# Node.js
npm audit --audit-level=moderate

# Rust
cargo audit

Tests et couverture

Couverture de code

Viser 80%+ sur le code métier. Ne pas viser 100% (rendements décroissants). Outils : vitest --coverage, cargo-llvm-cov.

Tests de mutation

Vérifier que les tests détectent réellement les bugs. Si une mutation passe les tests, le test est insuffisant. Outil : stryker-mutator.

Temps d'exécution

Les tests doivent rester rapides (<30s pour les unitaires). Surveiller les régressions de performance des tests.

Ratio test/code

Indicateur de couverture structurelle. Ratio recommandé : 1:1 minimum pour le code métier critique.

Audits et métriques continues

Signal Outil Seuil recommandé Fréquence
Ratio fix/feat Analyse git log < 0.3 (excellent), < 0.5 (bon) Hebdomadaire
Rollbacks git log --grep="revert" 0 (objectif) Continue (CI)
Couverture vitest/cargo-llvm-cov > 80% code métier Chaque commit
Vulnérabilités npm audit / cargo audit 0 critical, 0 high Quotidienne (CI)
Bundle size bundlesize / size-limit Selon projet Chaque MR
Complexité eslint-plugin-complexity Max 10/fonction Chaque commit

8. Checklist projet