Sept erreurs dans CLAUDE.md qui détériorent silencieusement les résultats de Claude Code

C’est précisément dans ce doute que résident les mauvaises configurations. Aucune erreur, aucun avertissement, seulement du code vaguement générique et légèrement incorrect, session après session. Un fichier flou ou surchargé ne se contente pas d’être inutile : il consomme des ressources et empêche l’exécution de la tâche réelle. Ainsi, avant de modifier ne serait-ce qu’une seule ligne, examinez attentivement son contenu, puis corrigez les problèmes un par un.

Erreur 1 : une description vague de la pile d’exécution

Une phrase comme We use React and a database. ne dit presque rien à Claude. Il devinera le routage Next.js, choisira au hasard une bibliothèque de gestion d’état et écrira des tests dans un framework que vous n’utilisez pas. Le résultat se compile, mais reste inadapté à votre codebase.

Précisez plutôt :

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Seules les versions exactes et les conventions bien définies permettent de transformer un résultat générique en du code qui semble correspondre à votre répertoire. Donnez-leur des noms.

Erreur 2 : pas de contraintes, pas d’interdits

C’est l’échec silencieux le plus courant. Les gens décrivent le projet sans établir de limites claires. Sans contraintes, Claude exécute npm dans un projet pnpm, modifie les fichiers générés et refactore du code que vous n’avez jamais mentionné. Ce ne sont pas des hallucinations : ce sont des suppositions logiques faites parce qu’aucune règle ne l’interdit.

Ajoutez un bloc de contraintes :

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Les règles indiquant ce qu’il ne faut pas faire vous apportent plus que des simples descriptions, car elles empêchent des erreurs coûteuses avant même qu’elles ne se produisent.

Erreur 3 : ignorer les agents et les sous-agents

La plupart des fichiers CLAUDE.md sont rédigés comme s’un seul modèle fonctionnait seul, sans aucune indication concernant les sous-agents spécialisés qui s’exécutent en parallèle de la session principale. Si vous utilisez des sous-agents pour les tests, la documentation ou le déploiement, précisez-le dans le fichier : listez chaque agent, la zone pour laquelle chacun est responsable, ainsi que les situations dans lesquelles l’agent principal doit transférer le travail.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Si vous êtes encore en train de concevoir le modèle de délégation, il est utile de comprendre les différences entre les compétences, les sous-agents, les commandes slash et MCP avant de choisir une structure.

Erreur 4 : un fichier encombré qui épuise votre budget de contexte

Plus n’est pas toujours mieux. Un fichier CLAUDE.md de 2 000 lignes, rempli de guides de style complets, de documents API et de journaux des modifications, charge tout cela à chaque session, que ce soit pertinent ou non. Cela empêche d’accomplir la tâche réelle, et comme l’attention diminue face à un contexte encombré, on se retrouve avec un modèle qui a techniquement lu vos règles mais ne les applique pas de manière fiable.

Réduisez à l’essentiel. Faites référence aux fichiers ou compétences concernées pour obtenir les détails, plutôt que de les coller directement. Une règle relative à un seul package doit se trouver dans un fichier ciblé, et non dans le répertoire racine. Comptez les tokens du fichier avant et après suppression pour vous assurer que la modification a eu un effet.

Erreur 5 : instructions que Claude ne peut pas mettre en œuvre

Prenons l’exemple Écrivez du code propre, maintenable et de haute qualité. Claude pense déjà le faire, donc des adjectifs vagues n’ont aucun effet. Remplacez-les par des règles que vous pouvez vérifier :

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Les règles opérationnelles donnent au modèle un objectif mesurable. Les phrases ambitieuses n’en fournissent aucun.

Erreur 6 : règles obsolètes qui contredisent le code

Le problème du CLAUDE.md est réel. Imaginons que le fichier indique encore « use Redux » six mois après que l’équipe soit passée à Zustand. Cette règle n’est pas inoffensive : elle met en conflit votre configuration avec votre code réel, et Claude alterne entre la confiance dans l’une ou l’autre.

Vérifiez le fichier chaque fois que les dépendances changent significativement, et inscrivez cette vérification dans votre liste de contrôle pour les PR. Conservez-la dans Git afin de savoir quand chaque règle a été modifiée pour la dernière fois. Un CLAUDE.md obsolète est souvent pire que rien du tout.

Erreur 7 : un seul fichier plat géant

Dans un monorepo, un CLAUDE.md non structuré unique amène Claude à appliquer des règles de frontend au code backend et vice versa. Lorsque tout est regroupé en un seul bloc indifférencié, il n’y a aucun moyen de définir précisément le contexte.

Placer les règles globales dans un fichier CLAUDE.md racine et ajouter des fichiers ciblés par package ou service. À l’intérieur du fichier racine, utiliser des en-têtes de section clairs :

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

La structure indique à Claude quelles règles s’appliquent où.

Un audit rapide et une liste de contrôle

Cessez de deviner et évaluez le fichier selon quatre critères : spécificité, contraintes, structure et taille. Comparer avec un modèle bien structuré est également utile, car il montre à quoi ressemble un bon fichier en pratique.

Répondez aux questions suivantes :

• Précise-t-il les versions exactes du framework et des bibliothèques ?
• Y a-t-il un bloc de contraintes avec des règles strictes du type « ne faites jamais ceci » ?
• Énumère-t-il quels agents existent et ce que chacun gère ?
• A-t-il moins de 200 lignes, avec les détails reportés dans des compétences ou des fichiers liés ?
• Toutes les instructions sont-elles opérationnelles plutôt que purement souhaitables ?

Quelqu’un a-t-il vérifié s’il y avait des règles obsolètes au cours des 30 derniers jours ?

Est-il organisé par en-têtes, ou par fichiers spécifiques à chaque package si vous utilisez un monorepo ?

Répondez non à plus de deux de ces questions, et votre CLAUDE.md vous coûte probablement plus qu’il ne vous économise.