Version : 1.0 — Mars 2026 Scope : Tout projet utilisant Claude Code Objectif : Documenter les comportements récurrents problématiques de Claude Code et les garde-fous à intégrer dans les instructions projet
Chaque entrée vient d'une expérience réelle, pas d'une doc recopiée. Ce fichier est conçu pour la progressive disclosure : il est référencé dans le CLAUDE.md des projets, pas importé via @import.
Format d'une entrée
Chaque anti-pattern suit ce format :
- Comportement observé : ce que Claude fait de travers
- Pourquoi c'est un problème : l'impact concret
- Garde-fou : la règle ou l'instruction à donner à Claude pour éviter ça
Anti-patterns documentés
Ajout de dépendances sans vérifier l'existant
- Comportement : Claude installe une nouvelle librairie pour résoudre un problème alors qu'une dépendance existante couvre déjà le besoin.
- Pourquoi : Gonfle le bundle, crée des conflits de versions, complexifie la maintenance.
- Garde-fou : Avant d'ajouter une dépendance, vérifier dans
package.json/requirements.txtsi une lib existante ne couvre pas déjà le besoin.
Refactoring opportuniste pendant un fix
- Comportement : Claude corrige un bug et en profite pour refactorer le code autour, modifiant des fichiers non liés à la correction.
- Pourquoi : Mélange les changements, rend la PR illisible, risque d'introduire des régressions.
- Garde-fou : Un commit = un objectif. Ne pas mélanger fix et refactoring. Si du refactoring est nécessaire, le signaler pour une tâche séparée.
Patterns modernes dans un codebase legacy
- Comportement : Claude introduit des patterns récents (async/await, hooks React, etc.) dans un codebase qui utilise des patterns plus anciens (callbacks, classes).
- Pourquoi : Crée une incohérence de style, complique la lecture pour l'équipe.
- Garde-fou : Respecter les conventions existantes du projet. Adopter les patterns déjà en place, même s'ils sont plus anciens.
Dernière mise à jour : mars 2026 Prochaine entrée à ajouter quand un pattern se répète sur ≥2 projets.