Lundi matin. Votre développeur ouvre Claude Code, tape une instruction en trois lignes, et part prendre un café. Quand il revient, l'agent a produit 300 lignes de code, réarchitecté deux modules, et choisi JSON comme format d'export sans que personne le lui demande. La fonctionnalité fonctionne. Le diff, lui, est ingérable.
Ce n'est pas un problème de fichier CLAUDE.md trop court. C'est un problème de jugement. Andrej Karpathy l'a diagnostiqué en janvier 2026, après avoir basculé à 80 % d'agent sur son propre code : les modèles « font des suppositions à votre place et avancent sans vérifier » (Karpathy, thread X, janvier 2026). Ce comportement se corrige. Pas avec 50 règles de configuration, mais avec 4 contraintes comportementales précises dans votre CLAUDE.md.
Ce que votre CLAUDE.md ne dit probablement pas à Claude
La plupart des fichiers CLAUDE.md ressemblent à une liste de spécifications techniques : stack, conventions de nommage, commandes de build. Ces informations sont utiles. Elles ne résolvent pas le problème de jugement.
La distinction est nette. Un agent qui ignore votre format JSON de préférence commet une erreur de configuration Claude Code. Un agent qui réécrit des modules non concernés, avance sans clarifier une ambiguïté, ou sur-complique une solution de 20 lignes commet une erreur de comportement. Seule la seconde catégorie cause des diffs ingérables et des heures de revue non planifiées.
Votre CLAUDE.md dit peut-être « utilise TypeScript strict » ou « pas de console.log en production ». Mais dit-il à Claude quand s'arrêter et demander ? Jusqu'où aller dans une tâche ? Ce qu'il ne faut pas toucher même si c'est adjacent ? Si ce n'est pas explicite, l'agent décide seul. La configuration technique règle le contexte. Les contraintes comportementales règlent le jugement.
Les 4 règles comportementales pour piloter Claude Code
Ces quatre règles ciblent chacune un comportement précis, diagnostiqué par Karpathy dans un thread publié sur X en janvier 2026.
1. Demander avant d'assumer
Si une spécification est ambiguë ou incomplète, posez une question avant d'agir.
C'est la règle la plus rentable du fichier. Un agent qui demande une clarification coûte 30 secondes. Un agent qui assume et part dans la mauvaise direction coûte une session de débogage complète. Sans cette instruction explicite, Claude Code comble les vides avec l'hypothèse la plus plausible selon lui, pas la vôtre.
Formulation à intégrer dans votre CLAUDE.md :
- Si une spécification est ambiguë, pose une question avant d'agir.
- Ne choisis pas un format, une architecture ou une dépendance par défaut sans le signaler.2. Préférer la solution minimale
Implémenter la solution la plus simple qui résout le problème. Pas de construction pour des besoins futurs non exprimés.
Karpathy l'a formulé sans détour : les agents « aiment sur-compliquer le code et les APIs, gonfler les abstractions » (Karpathy, thread X, janvier 2026). Vous demandez un calculateur de remise, vous obtenez un pattern Strategy avec classe abstraite et 40 lignes de setup. Le code fonctionne. Il est illisible et démesuré.
- Préfère la solution la plus simple.
- Pas de pattern ou d'abstraction supplémentaire si ce n'est pas demandé.
- Si une approche plus complexe te semble justifiée, explique-la avant de l'implémenter.3. Ne modifier que le périmètre demandé
Ne pas toucher au code en dehors de ce qui est explicitement dans le scope de la tâche.
Vous corrigez un bug. Le diff ajoute des types non demandés, reformate les guillemets, réécrit une fonction adjacente. La correction tenait en 3 lignes. Le PR en fait 40. C'est la règle la plus souvent absente des CLAUDE.md, et celle qui génère le plus de friction dans les équipes qui utilisent Claude Code au quotidien.
- Ne modifie que les fichiers et fonctions concernés par la tâche.
- Si tu identifies du code adjacent à améliorer, signale-le en commentaire. Ne le modifie pas.4. Opérer sur des critères de succès
La quatrième règle va au-delà de la discipline. Karpathy l'a formulé ainsi : « Les LLMs sont exceptionnellement bons pour boucler jusqu'à un objectif précis. Ne leur dites pas quoi faire. Donnez-leur des critères de succès. » (Karpathy, thread X, janvier 2026).
Pour les tâches complexes, reformulez vos demandes en termes de résultat attendu plutôt qu'en étapes à suivre.
- Pour les tâches de plus de 3 étapes, décris le résultat attendu et propose une approche avant de l'exécuter.Cette reformulation donne à Claude Code la latitude de trouver le chemin optimal, dans un périmètre que vous contrôlez.
Les best practices Claude Code : construire un CLAUDE.md en 80 lignes
Au-delà de 80 lignes, les modèles commencent à diluer leur attention sur les instructions. C'est l'effet lost in the middle : plus le fichier est long, moins chaque règle est appliquée. La tendance naturelle est d'accumuler des instructions après chaque erreur de l'agent. C'est contre-productif. Un CLAUDE.md de 200 lignes résout moins bien les problèmes qu'un CLAUDE.md de 70 lignes bien structuré.
La structure qui fonctionne :
- Comportement général (les 4 règles ci-dessus), en tête du fichier
- Stack technique (framework, langage, package manager)
- Conventions de code (nommage, structure, règles vérifiables)
- Commandes (build, test, lint)
- Garde-fous (ce que Claude ne doit jamais modifier)
Les règles comportementales en premier. Un fichier dont les 30 premières lignes sont lues attentivement vaut plus qu'un fichier de 200 lignes survolé.
Pour démarrer : la commande /init dans Claude Code génère un squelette à partir de votre projet existant. Gardez-le comme base technique, ajoutez les 4 règles comportementales au-dessus. C'est tout.
Dernier critère de qualité : si vous ne pouvez pas tester si une règle est respectée ou non, elle est trop vague pour être utile. « Écris du code propre » ne signifie rien de vérifiable. « Ne modifie que le périmètre demandé » se vérifie à chaque diff.
Ce que la configuration ne remplace pas
Un CLAUDE.md bien construit réduit significativement les erreurs de jugement. Il ne dit pas à l'agent quels processus méritent d'être délégués dans votre contexte, ni dans quel ordre les adresser pour un impact mesurable.
Les 4 règles comportementales sont universelles. Les cas d'usage qui créent de la valeur dans votre organisation dépendent de vos workflows réels : la façon dont votre équipe gère les revues de code, votre cycle de livraison, vos conventions internes. Cette cartographie ne se fait pas depuis un fichier Markdown. Elle se fait en regardant vos processus.
C'est précisément ce travail d'identification qui distingue une équipe qui utilise Claude Code d'une équipe qui le fait travailler. Arynor propose un accompagnement sur mesure et un diagnostic gratuit de 30 minutes pour identifier les processus où le gain est immédiat dans votre organisation. Aucun engagement.
Quatre règles. Une section de 15 lignes. Le problème de jugement identifié par Karpathy n'est pas fondamentalement difficile à résoudre. Il est rarement adressé directement dans les fichiers de configuration. Commencez par là, observez les diffs lors des deux premières semaines, et ajustez uniquement ce qui ne tient pas.
