Un matin, j'ai collé quatre principes dans mon CLAUDE.md, le fichier d'instructions globales que Claude Code lit à chaque session. « Réfléchir avant de coder », « la simplicité d'abord », ce genre de maximes vues passer sur X, attribuées à Andrej Karpathy. Je me suis senti malin pendant à peu près une journée.
Puis j'ai regardé Claude lire le fichier, acquiescer, et continuer exactement comme avant. Un CLAUDE.md, c'est une boîte à suggestions. Le modèle hoche la tête, puis fait ce qu'il veut. Si je voulais qu'il code à ma façon, l'écrire n'allait pas suffire. Il fallait l'imposer.
Ce qui suit, c'est ce que cette frustration est devenue : une config en quatre couches, réinstallable en une commande, et une découverte qui traverse tout le reste. La seule rigueur qui compte est celle qu'un modèle ne peut pas s'accorder lui-même.
Quatre couches, et une seule change vraiment le comportement
Ma config tient en quatre étages, du plus mou au plus dur.
Le cerveau, c'est CLAUDE.md : ma façon de travailler, pas la doc de mon code. La règle qui le résume est dedans : « quoi ne pas ajouter : ce que Claude redécouvre en lisant le code. » On y trouve mes principes de conception, ma posture d'orchestration des sous-agents (j'estime, je dimensionne, je délègue, je vérifie : « je reste le cerveau, eux les bras »), et une ligne qui deviendra le fil rouge de tout l'édifice.
Les références, un fichier go-best-practices.md que le cerveau pointe en texte brut quand on touche du Go.
Les compétences, dix skills. Un skill, c'est un dossier avec un mode d'emploi que Claude charge à la demande pour une tâche précise : relire du code, écrire un article, distiller un livre. Les miens sont packagés en marketplace, sur un dépôt GitHub public, avec changelog et numéro de version. C'est le vrai différenciateur : de l'outillage versionné, pas juste des règles griffonnées.
Les garde-fous, enfin. Et c'est la seule couche qui modifie le comportement de façon fiable. Les trois premières, le modèle peut les lire et les ignorer. La quatrième, non.
De l'« INTERDIT » qu'on ignore au blocage qu'on subit
Mon CLAUDE.md disait, en majuscules : interdit de lire les fichiers .env. Une suggestion. Le modèle la respectait quand ça l'arrangeait.
Alors j'ai écrit un hook. Un hook, c'est un script que Claude Code lance automatiquement à un moment précis de son cycle. guard.sh s'accroche en PreToolUse, intercepte chaque Read et chaque Bash avant exécution, et tranche :
case "$tool" in
Read)
is_secret_path "$path" && block "lecture d'un fichier de secrets ($path)."
;;
Bash)
printf '%s' "$cmd" | grep -Eq -- '--no-verify|core\.hooksPath=' \
&& block "contournement des hooks git interdit."
;;
esacblock sort en code 2. Pour Claude Code, un hook PreToolUse qui sort en 2, c'est un veto : l'outil n'est jamais lancé. Lire un .env, contourner les hooks git avec --no-verify : ce ne sont plus des choses que je demande de ne pas faire, ce sont des choses qui n'arrivent pas.
Le hook est fail-open. La moindre incertitude, un jq absent, un JSON malformé, et il autorise. Un bug du garde-fou n'a jamais bloqué un outil légitime. Il ne ferme la porte que sur une violation confirmée.
La preuve est dehors, jamais dans le modèle
Voici la ligne du CLAUDE.md qui irrigue tout le reste :
Rigueur externe : la seule preuve qui compte est vérifiable du dehors (test, commande, grep, sortie réelle), jamais l'auto-évaluation du modèle. « Tu es sûr ? » → un LLM dit toujours oui ; exiger un fait, pas une affirmation.
Demande à un modèle s'il est sûr, il répond oui. Toujours. Du coup mes skills sont construits pour que la preuve soit exécutable, pas déclarée.
feature-loop livre une feature en boucle, mais avant de croire un test critique, il le mute, vérifie qu'il rougit, puis le restaure. Un test resté vert après mutation ne teste rien : il est réécrit. La raison est chiffrée dans le skill : 76 % des tests écrits par un LLM ratent le passage rouge-vert. Un test qui passe toujours rassure autant qu'il ment.
rediger-cir, mon skill de dossier de crédit d'impôt recherche, pousse la même logique à l'extrême. Aucune référence n'entre dans un dossier sans résolution via une API de métadonnées : le DOI doit résoudre, la revue ne doit pas être prédatrice, le papier doit dire ce qu'on lui fait dire. La règle d'or tient en une phrase : ne jamais demander au modèle qui vient d'halluciner une citation si cette citation est réelle. C'est précisément à lui qu'il ne faut pas poser la question.
Pourquoi le relecteur n'est jamais l'auteur
S'il fallait garder une seule décision de toute cette config, ce serait celle-là.
senior-review relit du code avant merge. Le piège évident serait de demander au modèle qui vient d'écrire le code de se relire. Sauf qu'un modèle qui juge sa propre sortie se surnote : le self-preference bias est documenté et causal (Panickssery, 2024). Un relecteur honnête doit donc être aveugle. Mes agents reviewers tournent en contexte vierge, ne voient jamais le prompt d'implémentation, et quand l'auteur est un modèle connu, sont d'une famille différente. Le nom du développeur n'entre jamais dans le prompt.
Ensuite vient le gate qui fait le ménage : pas de finding sans reçu. Chaque alerte cite un fichier:ligne et passe une vérification, un grep, une exécution en sandbox, un test qui échoue. Un finding non vérifiable est droppé en silence. Les modèles sur-signalent par réflexe ; ancrer chaque alerte dans une exécution réelle élimine environ 60 % des faux positifs. Le but n'est pas de trouver le plus de problèmes. C'est de ne remonter que les vrais.
Dix skills, du cadrage à la clôture
feature-loop, senior-review et rediger-cir, je les ai déjà disséqués. Mais ils ne vivent pas seuls. Les dix skills forment une chaîne : quatre couvrent le cycle de vie d'une tâche de dev, du cadrage au commit, et chacun sait quand passer la main au suivant. Les six autres sont orthogonaux, je les dégaine au besoin.
| Skill | Sa moelle |
|---|---|
issue-mr | Cadrer. Transforme une tâche floue en issue propre, branche et PR. Un mode analyse tranche le design avant d'écrire une ligne. |
feature-loop | Implémenter. Boucle qualité où l'auteur, le testeur et le relecteur sont des agents séparés : gate objectif (build, tests, red-check) avant toute revue, smoke test live obligatoire. |
senior-review | Relire. Relecteurs aveugles par dimension, aucun finding sans reçu, panel adverse sur les critiques. |
branch-wrap-up | Clôturer. Commit conventionnel proposé, push et PR, capture mémoire. Ne commit jamais sans mon feu vert. |
code-mentor | Enseigner. Ralentit à chaque décision, explique le pourquoi, me fait prédire avant de révéler. L'inverse du copier-coller. |
skill-builder | Concevoir. Les principes pour qu'un skill se déclenche vraiment et reste focalisé : un mot-ancre, un process prévisible. |
tech-article | Rédiger. Un article qui sonne humain, pas IA. Celui que tu lis est sorti de là. |
book-distill | Distiller. Une fiche de lecture fidèle d'un livre, chaque citation vérifiée mot à mot contre le texte. |
rediger-cir | Justifier. Un dossier de crédit d'impôt recherche dont chaque référence est résolue via une API, zéro hallucination. |
vide-contexte | Mémoriser. Avant un reset de contexte, persiste les insights non-déductibles dans des fichiers mémoire. |
Un fil les traverse tous : l'auteur n'est jamais le relecteur, le gate objectif passe avant le jugement du modèle, et rien ne se commit sans mon accord. Ce ne sont pas dix outils, c'est une seule façon de travailler, déclinée dix fois.
Ma manière de travailler, tenue par le CLAUDE.md
Le cerveau de la config tient en quelques règles que je m'applique à moi-même autant qu'au modèle.
- La matrice mère. Je n'exécute pas tout. J'estime la difficulté, je dimensionne, et je délègue à des sous-agents calibrés : un Haiku pour le mécanique, un Opus pour le raisonnement dur. Je reste le cerveau, eux les bras.
- Exposer, pas deviner. Avant de coder, j'énonce mes hypothèses. Plusieurs lectures possibles, je les pose toutes au lieu d'en choisir une en silence.
- Chirurgical. Chaque ligne modifiée trace vers la demande. Pas de refacto opportuniste sur du code qui n'est pas cassé, pas de style qui dérive au passage d'un fix.
- La solution la plus simple qui marche. YAGNI. Une interface à une seule implémentation, une abstraction « au cas où », un fichier de plus sans raison : autant de signaux d'arrêt.
- Le commentaire pour un dev senior. Il déduit le quoi en cinq secondes. Un commentaire ne survit que s'il porte un pourquoi non-évident, un piège, un invariant.
La sixième règle, tu la connais déjà : la preuve est externe. C'est elle qui transforme tout le reste de bonnes intentions en garanties.
222 793 étoiles ne prouvent rien
En montant cette config, j'ai étudié les gros dépôts du domaine. Les chiffres, vérifiés via l'API GitHub le jour où j'écris ces lignes, donnent le vertige. « Everything Claude Code » culmine à 222 793 étoiles. À côté, un dépôt de skills très propre signé Matt Pocock en compte 148 737, et un autre, vendu comme « les skills de Karpathy », 183 652.
Ce dernier mérite un avertissement, parce qu'il illustre le thème mieux que n'importe quel test. Ce dépôt n'a rien d'officiel : c'est la reconstruction, par un tiers, d'un unique tweet, dupliquée en quatre formats. Le label dit Karpathy. La source dit un tweet recopié. Croire le label, c'est exactement l'erreur que toute ma config cherche à rendre impossible.
Quant au mastodonte à 222 793 étoiles, sa traction vient de la distribution, pas du code : un hackathon Anthropic gagné, des threads à millions de vues, un nom-parapluie, un README transformé en landing page. Sous le capot, deux ou trois hooks solides, dont j'ai d'ailleurs repris l'idée du blocage .env et du --no-verify, une boucle d'« apprentissage » désactivée par défaut, et des compteurs internes qui se contredisent d'une section à l'autre.
Mon dépôt à moi, lui, affiche zéro étoile. Et ses garde-fous sont plus stricts que la moyenne de celui qui en a 222 793. La leçon n'est pas amère, elle est utile : les étoiles mesurent une histoire bien racontée, pas une rigueur. Les deux n'ont presque rien à voir.
La vérif qu'un LLM ne peut pas s'accorder
Avant de publier, j'ai fait auditer mes propres skills. Le verdict : les références scientifiques étaient réelles à 98 %, mais quatre chiffres faussement précis et une citation mal attribuée s'étaient glissés dans le lot. Corrigés. Même un auteur qui se croit rigoureux ne peut pas se certifier seul.
Cet article en est la dernière preuve. Je l'ai fait écrire par l'un des dix skills, à partir du dépôt public, sur la foi d'un brief que j'avais rédigé moi-même. Ce brief affirmait qu'« Everything Claude Code » était un outlier solitaire, cinq fois plus gros que tout le reste. La vérification contre l'API GitHub, juste avant d'écrire, a montré qu'il existe en réalité tout un peloton de dépôts à six chiffres. Mon propre brief se trompait, et seul un appel à une source externe l'a attrapé.
C'est tout le sujet. Le modèle ne sait pas qu'il a tort. Moi non plus, la moitié du temps. La seule chose qui le sait, c'est le test qui rougit, le DOI qui résout, le fichier:ligne qu'on peut ouvrir. Une config Claude Code qui vaut le coup, ce n'est pas une liste de bonnes intentions. C'est l'endroit où la preuve cesse d'être une affirmation.