CLAUDE.md indispensable pour Claude Code ? J’ai testé Karpathy Skills sur 10 tickets réels

Les chiffres d’abord. Pour savoir si Karpathy Skills (règles CLAUDE.md consolidées par la communauté) tiennent la route, j’ai pris 10 tickets réels, fixé Claude Opus 4.8, et la seule variable était les quatre principes Karpathy activés ou non. En une semaine, ce qui reste :

Il y a aussi des déceptions — sur un ticket « une constante », les règles n’ont presque rien aidé et ont ajouté un tour de « confirmation d’hypothèses ». Succès et échecs sont détaillés ci-dessous, avec ma version finale de CLAUDE.md (recherches Claude Code Rules / Claude Code Prompt).

Pourquoi Claude Code touche tout ?

Ce n’est pas que le modèle soit « bête » : l’objectif par défaut n’est pas celui d’un ingénieur — livrer vite un patch « qui a l’air fini ». Abstractions en plus, fichiers voisins retouchés, ambiguïtés non posées. Andrej Karpathy a résumé sur X quatre symptômes chroniques : coder avant d’avoir demandé, sur-ingénierie sur des besoins simples, retouches « au passage » sur ce qu’il ne fallait pas toucher, remplacer un objectif vérifiable par un « c’est bon ».

Au printemps 2026, la communauté a compressé tout ça en quelques dizaines de lignes de CLAUDE.md (forrestchang/andrej-karpathy-skills, dit Karpathy Skills). Pas de nouveau runtime — quatre contrats de comportement que Claude Code relit à chaque session. La question : I tested it — combien en chiffres ?

Karpathy Skills, c’est quoi ?

Le nom dit Skills, mais la forme est un fichier d’instructions projet — pas un Skill OpenAI GPT, ni un plugin OpenHuman SKILL.md. Au démarrage, Claude Code lit CLAUDE.md à la racine (et l’équivalent injecté par les plugins globaux) et contraint réflexion et diff avant votre première ligne de demande.

Les quatre principes correspondent au CLAUDE.md amont :

• Think Before Coding : énoncer les hypothèses, exposer l’ambiguïté, proposer une voie plus simple — pas choisir en silence une interprétation.
• Simplicity First : le minimum de code pour résoudre le problème ; refuser abstractions, config et couches « pour plus tard » non demandées.
• Surgical Changes : uniquement les lignes utiles à la tâche ; pas de « rangement » ou formatage voisin ; signaler le code mort legacy sans le supprimer sauf demande.
• Goal-Driven Execution : bug ou validation → objectif vérifiable (test rouge d’abord si possible) ; tâches multi-étapes avec verify par étape.

Deux entrées : plugin /plugin install andrej-karpathy-skills@karpathy-skills, ou fusion du CLAUDE.md amont à la racine — la version finale ci-dessous est copiable telle quelle.

Méthode de test

Variables maîtrisées (essai sur Mac mini M4 en Mac cloud pour tmux long et xcodebuild sans coupure ; les chiffres se reproduisent sur Mac local) :

• 10 tickets réels : 4 petites features Swift, 2 renommages multi-fichiers, 2 ajouts de tests, 2 scripts CI.
• Modèle fixe : claude-opus-4-8, Effort high, pas de micro-mise à jour la même semaine.
• Seule variable : contrôle = ancien CLAUDE.md (sans Karpathy) ; expérience = quatre principes + 2 règles d’équipe ci-dessous.
• Chaque ticket deux fois (A puis B ou alternance jour par jour) pour éviter le biais « bonne journée ».

Cinq métriques alignées sur ce qui coûte en revue :

Résultats sur 10 tickets

Tableau en médianes (n=10, pas un benchmark officiel). Un seul chiffre à retenir : diff hors périmètre −78 %.

Le passage 18 % → 4 % : l’agent touche encore beaucoup de fichiers, mais le « formatage au passage du module Payment » disparaît du diff — courbe Surgical Changes. 5/10 → 8/10 au premier CI vert vient surtout de Goal-Driven Execution : plus souvent un test rouge avant l’implémentation.

Où le gain est maximal

• Renommage multi-fichiers / changement de signature : −78 % ressenti au maximum ; la revue n’est plus un champ de mines.
• Petite feature à spec un peu floue : Think Before Coding force les hypothèses en amont ; retours 3 → 1 (PAY-1842, AUTH-901).
• Tests + implémentation : hausse du premier vert ; écrire « rouge → vert » dans CLAUDE.md stabilise l’exécution.

Orthogonal au graphe de connaissance du code : le graphe dit où toucher, CLAUDE.md dit où ne pas toucher.

Où ça ne sert presque pas (avec échec)

Un ticket décevant : une constante. Ticket CFG-77 : maxRetryCount de 3 à 5, chemin déjà indiqué. Avec Karpathy, l’agent a quand même demandé : « faut-il aussi changer la stratégie de backoff et les défauts des tests unitaires ? » — +1 tour de clarification, diff aussi propre qu’en l’absence de règles, +4 min au total. Sur une modification ponctuelle ultra claire, la prudence des quatre principes apporte quasi zéro gain.

Autres cas quasi nuls :

• CLAUDE.md d’équipe déjà long et redondant avec Karpathy — rendements décroissants.
• Pas de tests / xcodebuild — Goal-Driven ne boucle pas, l’agent « a l’air fini » quand même.
• Discussion en chat sans écriture dans le dépôt — CLAUDE.md jamais chargé.

Ma version finale de CLAUDE.md (copiable)

Les recherches CLAUDE.md, Claude Code Rules, Claude Code Prompt visent un fichier prêt à coller. Ci-dessous : quatre principes Karpathy + 2 règles iOS d’équipe (corps en anglais pour le modèle ; explications en français autour) :

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

Installation amont :

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

# or per-project:
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# do not overwrite existing CLAUDE.md — merge paragraphs

Côté Cursor : synchroniser .cursor/rules/karpathy-guidelines.mdc avec la même sémantique. Pour mesurer Karpathy, fixer claude-opus-4-8 et ne pas mélanger avec une montée de version — voir le guide Opus 4.8 en longue durée.

Mac cloud en longue durée (Claude Code → tmux → Mac mini)

Cet article parle plus naturellement de Mac cloud qu’OpenHuman : la chaîne se ferme — session longue Claude Code → tmux résistant aux coupures → xcodebuild sur la même machine → Mac mini dédié. A/B, agent de nuit, revue à distance : la mise en veille du portable fait peur. Ici, le cloud ne sert qu’à stabiliser l’environnement ; les chiffres se reproduisent en local.

• tmux + Claude Code : la session survit à une coupure SSH (exemples dans l’article Opus 4.8).
• CLAUDE.md sur volume persistant : règles et monorepo ensemble, pas de perte de config.
• Validation dure Goal-Driven : Build Verification dans CLAUDE.md, l’agent lance le Scheme avant de dire « terminé ».
• Avec la CI Mac cloud, modifier puis vérifier sur le même hôte.

Extraits de script pour l’A/B

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# chemins hors périmètre : manuel ou comparaison allowlist
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

Dans Claude Code, formuler la demande en objectif vérifiable pour activer le quatrième principe :

Objectif : ajouter une validation des montants non positifs dans CheckoutViewModel.validateAmount.
Vérification : 1) tests unitaires pour 0, négatifs et NaN ; 2) xcodebuild test -scheme YourApp doit passer ;
Périmètre : uniquement Sources/Checkout/ et les Tests/ associés — pas de thème UI ni d’autres modules.

FAQ

Karpathy a-t-il écrit le fichier lui-même ? Les règles viennent de ses observations sur X ; le CLAUDE.md est une consolidation communautaire (Forrest Chang, etc.). Il a retweeté des dépôs liés — se fier au README du dépôt.

Conflit avec memory / description de projet Claude Code ? Il faut fusionner : quatre principes en tête, puis conventions d’équipe (nommage, branches, commandes de test).

Remplace-t-on la code review ? Non. Moins de bruit dans le diff, mais garde-fous de merge, revue humaine et scans sécurité restent obligatoires.

Utilisateurs Cursor ? Copier dans .cursor/rules/ ; sur le même git, aligner la sémantique avec Claude Code.

Peut-on citer les pourcentages ? Citez votre propre A/B. Le tableau ici est un pilote Vuncloud (n=10, pas de double aveugle strict).

Conclusion

J’ai mesuré Karpathy Skills — pas un « ça marche / ça marche pas » vague. Dix tickets, Opus 4.8 fixé : diff hors périmètre ≈ −78 %, premier CI vert +30 pp ; changer une constante n’aide presque pas. Ce qui compte, c’est un CLAUDE.md dans le dépôt — quatre principes Karpathy + vos règles de build et de chemins. Pour faire tourner Claude Code 7×24, Mac mini en cloud + tmux est plus direct qu’OpenHuman : agent, terminal et Xcode vivent sur le même macOS.