Bonnes pratiques¶

Gestion du contexte, workflow Git et erreurs courantes.

Gestion du contexte¶

Le contexte est la ressource la plus précieuse de Claude Code. Chaque token compte.

Le CLAUDE.md doit rester concis¶

graph LR
    A["CLAUDE.md<br/>petit & précis"] -->|"Claude suit<br/>les instructions"| B["Code cohérent"]
    C["CLAUDE.md<br/>énorme & vague"] -->|"Claude ignore<br/>uniformément"| D["Instructions<br/>non suivies"]

    style A fill:#4caf50,color:#fff
    style C fill:#f44336,color:#fff

Quand compacter, quand reset¶

Directive de compaction¶

Ajoutez ceci dans votre CLAUDE.md :

Quand tu compactes, préserve :
- La liste complète des fichiers modifiés
- Le statut actuel des tests
- La phase et la feature en cours
- Les décisions architecturales prises dans cette session

Workflow Git¶

Un workflow Git discipliné pour tirer le meilleur de Claude Code.

Toujours une branche¶

Ne travaillez jamais directement sur main. Demandez :

Crée une branche feature/auth et implémente le système d'authentification.

Claude crée la branche, implémente, et peut ouvrir une PR si gh est installé.

Isoler avec des worktrees¶

Un worktree Git permet de travailler sur plusieurs branches en parallèle depuis des dossiers distincts, sans git stash ni changement de branche dans le workspace principal.

graph LR
    M["main<br/>(workspace principal)"] --> W1["worktree<br/>feat/auth"]
    M --> W2["worktree<br/>feat/profil"]
    M --> W3["worktree<br/>fix/bug-123"]

    style M fill:#4caf50,color:#fff
    style W1 fill:#2196f3,color:#fff
    style W2 fill:#2196f3,color:#fff
    style W3 fill:#2196f3,color:#fff

Superpowers fournit le skill using-git-worktrees qui automatise la création, le choix du dossier et les vérifications de sécurité :

Crée un worktree isolé pour la feature auth et démarre l'implémentation.

Nettoyer les worktrees terminés¶

Après un merge ou l'abandon d'une branche, supprimez le worktree pour libérer l'espace disque et garder git worktree list lisible :

/clean_gone

Cette commande (plugin commit-commands) supprime toutes les branches locales marquées [gone] et leurs worktrees associés.

Pas de Co-Authored-By¶

Ne jamais ajouter de ligne Co-Authored-By dans les messages de commit.

Conventional Commits¶

Review avant merge¶

Fais une code review complète de la branche courante vs main.
Utilise le code revieweur de Superpowers.
Si tout est bon, propose un squash merge.

Paralléliser avec des sous-agents¶

Pour les features larges, Claude peut déléguer :

Utilise des sous-agents pour paralléliser :
- Agent 1 : composants UI (utilise frontend-design)
- Agent 2 : logique serveur + API routes
- Agent 3 : tests unitaires et d'intégration

Modifie directement, pas besoin de sous-agent.

Erreurs courantes¶

Les pièges les plus fréquents et comment les éviter.

Prompt trop vague¶

Ce qu'il ne faut pas faire :

Fais-moi un joli site.

Résultat générique, aucune direction.

Ce qu'il faut faire :

Phase 2, feature 6 : page de profil utilisateur.
Layout asymétrique, section hero avec avatar large à gauche.
Utilise Superpowers pour le plan, Context7 pour les docs Prisma
(requête user avec relations), frontend-design pour l'UI.

Tout demander d'un coup¶

Ce qu'il ne faut pas faire :

Implémente toutes les features de la Phase 2.

Contexte saturé, qualité dégradée, oublis.

Ce qu'il faut faire :

Phase 2, feature 5 : système de notifications.
Quand c'est terminé et commité, on passera à la feature 6.

Ignorer le score de confiance¶

Forcer une librairie où Claude est marqué 🔵 sans insister sur Context7.

Résultat : API hallucinées, code qui ne compile pas.

Ce qu'il faut faire :

Pour cette feature on utilise NextAuth v5 (marqué 🔵 dans le PROMPT).
Consulte Context7 pour CHAQUE appel d'API NextAuth avant de coder.

Ressources¶