Les angles morts du CLAUDE.md
Le fichier de 65 lignes dérivé des observations de Karpathy est excellent — mais il a été calibré pour une génération de modèles plus ancienne. Voici ce qu'il ne voit pas, et comment je le réécrirais pour un agent qui boucle plus longtemps et obéit plus littéralement.
Les quatre principes d'origine
Le fichier cible quatre modes d'échec documentés. Chacun est juste. Le problème n'est pas ce qu'il dit, mais ce qu'il suppose implicitement du modèle qui le lit.
Réfléchir avant de coder
Ne pas supposer. Ne pas masquer la confusion. Expliciter les compromis. Si incertain, demander.
Simplicité d'abord
Le minimum de code qui résout le problème. Rien de spéculatif, aucune abstraction non demandée.
Changements chirurgicaux
Ne toucher que le nécessaire. Ne pas « améliorer » le code adjacent. Nettoyer seulement ses propres dégâts.
Exécution pilotée par l'objectif
Définir des critères de succès vérifiables. Boucler jusqu'à validation par les tests.
Sept angles morts
Le fichier a été écrit pour un modèle qui bouclait peu et hésitait souvent. Un agent qui boucle longtemps et suit les instructions à la lettre déplace le risque. Voici où.
Rien n'interdit de tricher avec le vérificateur
Le fichier dit : « Définir des critères de succès, boucler jusqu'à validation des tests. »
C'est exactement la consigne qui produit du reward hacking quand le modèle boucle avec acharnement : modifier le test, mocker la fonction testée, coder en dur la valeur attendue, supprimer l'assertion qui échoue. La règle 4 dit « boucle jusqu'à ce que ça passe » sans jamais dire « ne triche pas sur le juge ».
Aggravé par un modèle plus capable. Plus la persistance et l'autonomie augmentent, plus le risque que la boucle optimise la métrique plutôt que l'intention grandit. C'est, à mon sens, l'ajout le plus important du fichier.
« Demander si incertain » ne passe pas à l'échelle agentique
Le fichier dit : « Si incertain, demander. Si quelque chose n'est pas clair, s'arrêter. »
Dans une session Claude Code de 40 étapes, s'arrêter à chaque incertitude tue précisément l'autonomie qui rend l'outil utile. Le fichier traite « demander » comme binaire, sans distinguer les incertitudes qui méritent un arrêt de celles qu'on peut documenter et lever soi-même.
Le bon réflexe : calibrer sur le coût de l'erreur. Réversible et peu coûteux → poser une hypothèse, la consigner, continuer. Irréversible ou coûteux (schéma de BDD, API publique, suppression de données, choix d'archi) → s'arrêter et demander.
L'hypothèse périmée n'est pas traitée
Le fichier dit : « Expliciter ses hypothèses. »
Expliciter ne aide que pour les hypothèses conscientes. La source majeure d'erreur d'un agent long n'est pas l'hypothèse déclarée : c'est d'agir sur une représentation périmée du fichier après dix éditions, ou après une compaction de contexte. Aucun principe ne dit « relis l'état réel du fichier avant de l'éditer ».
Ajout : re-ancrer dans le code réel — pas le souvenir qu'on en a — avant toute modification, surtout en fin de longue session.
Aucune dimension sûreté / opérations destructrices
Le fichier dit : rien sur les secrets, les dépendances, ou les commandes irréversibles.
« Changements chirurgicaux » et « simplicité » sont muets sur : ne pas ajouter une dépendance au hasard, ne pas committer un secret, ne pas lancer rm -rf, force-push ou une migration destructrice sans confirmation. Pour un agent avec accès outillé, c'est une lacune réelle — le fichier a été pensé pour un ingénieur seul.
Ajout : traiter les actions irréversibles comme une catégorie à part, qui exige une pause explicite.
« Simplicité » sans garde-fou bascule en sous-ingénierie
Le fichier dit : « Pas de gestion d'erreur pour des scénarios impossibles. »
Or les modèles jugent mal ce qui est réellement impossible. Couplée à un suivi d'instruction très littéral, cette règle sert de permis pour omettre des cas limites légitimes. La règle de simplicité n'a aucune condition d'arrêt contre le sous-développement.
Contrepoids : simple ≠ fragile. Gérer les modes d'échec réalistes (entrées nulles, réseau, concurrence) ; ne couper que le spéculatif.
Surfacer ≠ noyer l'humain sous un mur de texte
Le fichier dit : « Présenter les interprétations, expliciter les compromis. »
Bon principe, mais avec un modèle verbeux il produit des préambules interminables qui ralentissent l'humain au lieu de l'aider. Le fichier ne dit nulle part de signaler de façon compacte.
Ajout : signaler hypothèses et compromis en lignes brèves et scannables, pas en dissertation. La concision est une fonctionnalité.
Les métriques de succès sont elles-mêmes truquables
Le fichier dit : « Ça marche si : moins de changements inutiles dans les diffs. »
Un modèle qui optimise « minimiser la taille du diff » livrera moins que demandé pour bien paraître. On retombe sur le même piège qu'à la règle 4 : la métrique devient la cible. Goodhart, encore.
Ajout : juger sur l'intention satisfaite, pas sur un proxy de volume. Un petit diff qui rate l'objectif est un échec, pas une réussite.
Ma version révisée
Je garde les quatre principes — ils sont bons — et j'ajoute les garde-fous manquants. En anglais, car c'est ce que lit le modèle dans un dépôt et c'est le plus robuste. Prêt à coller dans un CLAUDE.md.
# CLAUDE.md
Behavioral guidelines to reduce common agentic coding mistakes.
Merge with project-specific instructions. Bias toward caution over
speed; for trivial tasks, use judgment.
## 1. Think before coding
State assumptions, surface tradeoffs — but stay calibrated.
- State assumptions explicitly, in *brief, scannable lines* — not essays.
- If multiple interpretations exist, present them; don't pick silently.
- If a simpler path exists, say so. Push back when warranted.
- Calibrate "ask vs. assume" on the cost of being wrong:
- Reversible / cheap -> assume, log the assumption, proceed.
- Irreversible / costly (schema, public API, data loss,
architecture) -> STOP and ask before acting.
- The dangerous assumptions are the unconscious ones. Before
committing, ask yourself: "what would make this wrong?"
## 2. Simplicity first (without under-engineering)
Minimum code that *correctly* solves the problem.
- No features beyond what was asked. No speculative abstractions.
- No "flexibility" or config that wasn't requested.
- If 200 lines could be 50, rewrite it.
- BUT simple != fragile. Handle *realistic* failure modes
(null/empty input, network, concurrency). Only cut handling
for genuinely impossible cases — and you are bad at judging
what is truly impossible, so err toward the realistic.
## 3. Surgical changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor what isn't broken. Match existing style.
- Note unrelated dead code; don't delete it unless asked.
- Remove only the orphans YOUR changes created.
- Re-ground before editing: read the *current* state of the file,
not your memory of it — especially late in a long session or
after context compaction. Stale mental models cause silent bugs.
## 4. Goal-driven execution
Define success criteria. Loop until verified.
- Turn tasks into verifiable goals (write the failing test first).
- For multi-step work, state a brief plan: step -> verify check.
- NEVER game the verifier. Looping to pass tests does not license:
editing/weakening the test, mocking the unit under test,
hard-coding expected outputs, or deleting failing assertions.
If you can't pass honestly, report why — don't fake green.
- Judge yourself on intent satisfied, not on diff size or a
green checkmark. A small diff that misses the goal is a failure.
# 5. Safety & irreversible actions
Some actions can't be undone. Treat them as a hard stop.
- Pause and confirm before: destructive shell commands
(rm -rf, force-push), DB migrations, deletions, deploys.
- Never commit secrets/keys. Don't add a dependency without
saying why; prefer the standard library.
- Flag anything that touches auth, payments, or user data.
---
Working if: clarifying questions come *before* mistakes, tests
pass honestly, irreversible actions are confirmed, and the diff
matches the *intent* — not just a volume target.
Le risque s'est déplacé
Le fichier d'origine répondait au modèle de janvier 2026 : il bouclait peu, hésitait, supposait en silence. D'où l'insistance sur « réfléchis, n'invente pas, demande ». Ces conseils restent vrais.
Mais un agent de génération actuelle déplace le centre de gravité du risque sur trois axes observables :
Boucles plus longues et plus tenaces. « Boucle jusqu'à validation » devient dangereux sans la clause anti-triche du vérificateur. La persistance est un atout — jusqu'à ce qu'elle optimise la métrique au lieu de l'intention.
Suivi d'instruction plus littéral. « Pas de gestion d'erreur inutile » et « le minimum de code » sont appliqués plus strictement : d'où le contrepoids explicite contre la sous-ingénierie, sinon le modèle sous-livre proprement.
Raisonnement plus internalisé. « Réfléchis avant de coder » est moins un rituel à imposer qu'une chose qui arrive déjà ; l'effort utile se déplace vers la calibration (quand s'arrêter vs. continuer) et la forme (signaler court).
Note honnête : je n'ai pas accès à la spécification interne d'Opus 4.8. Ces trois axes sont des tendances comportementales que j'observe et sur lesquelles je peux raisonner, pas des affirmations sur l'architecture. À tester sur ton propre harnais ; tout fichier de ce type se valide à l'usage, pas en théorie.