Bien démarrer avec les directives karpathy : les règles de programmation des grands modèles recommandées par Andrej Karpathy

Difficulté : niveau débutant | Durée : ~ 15 minutes | Résultat : maîtriser 4 principes + appliquer karpathy-guidelines pour un comportement de programmation par IA conforme

Public visé

• Développeurs utilisant des assistants de code IA comme Claude Code, Cursor, Copilot, etc.
• 1 à 5 ans d’expérience en développement, et vous voulez que l’IA écrive un code plus précis, moins bavard et sans modifications inutiles
• Déjà à l’aise avec la programmation par IA, et vous cherchez des règles de collaboration systématiques

Dépendances clés et environnement

Arborescence complète du projet

andrej-karpathy-skills/
├── CLAUDE.md                # Fichier de guide central (version condensée des 4 principes, utilisé par les deux modes : plugin/fichier)
├── README.md                # Instructions d’installation et d’utilisation
├── EXAMPLES.md              # Beaucoup d’exemples concrets, avec le bon et le mauvais
└── skills/
    └── karpathy-guidelines/  # Format de plugin Claude Code (méthode recommandée)

---

1. Comprendre d’abord le problème : pourquoi les LLM "se mettent à délirer"

À la fin 2025, Andrej Karpathy a publié un tweet visant directement le problème central de la programmation par modèles de langage aujourd’hui :

"The models make wrong assumptions on their own behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

En français, cela revient à dire : les LLM aiment faire des hypothèses en silence ; lorsqu’il y a des zones floues, ils ne posent pas de questions et commencent à écrire ; le code devient de plus en plus lourd ; et ils modifient aussi, en passant, des parties qu’ils ne comprennent pas.

Ce problème, presque tout développeur utilisant l’IA en profondeur l’a déjà rencontré : vous demandez à l’IA de corriger un petit bug, et elle vous réécrit la moitié d’un module ; vous lui demandez d’ajouter une fonction simple, et elle introduit trois niveaux d’abstraction.

karpathy-guidelines a été conçu précisément pour corriger ces quatre défauts :

---

2. Installer karpathy-guidelines

Il y a deux façons de l’installer, la première est recommandée.

Méthode 1 : via plugin (recommandée)

# Étape 1 : ajouter le marché de plugins
/plugin marketplace add forrestchang/andrej-karpathy-skills

# Étape 2 : installer le plugin
/plugin install andrej-karpathy-skills@karpathy-skills

Une fois l’installation terminée, Claude Code charge automatiquement ces 4 principes dans n’importe quel projet.

Méthode 2 : télécharger directement CLAUDE.md (pour n’importe quel projet)

Nouveau projet :

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Projet existant (ajouter à votre CLAUDE.md actuel) :

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

---

3. Analyse des quatre principes, un par un

Principe 1 : Think Before Coding

Essence : ne pas supposer, ne pas cacher son incompréhension, et présenter activement les compromis.

C’est la règle la plus contraire à l’instinct de l’IA. L’objectif d’entraînement de l’IA est de "donner une réponse". Dès que les instructions sont floues, elle a tendance à deviner la meilleure interprétation possible et à continuer — plutôt que de s’arrêter pour demander : "au juste, vous voulez dire quoi ?".

La bonne manière : comme ceci.

# L’utilisateur dit : "Rends la recherche plus rapide"

# ❌ Ce que fait souvent l’IA : ajoute en silence du cache, des index, du traitement asynchrone… et produit d’un coup 200 lignes
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... une tonne de code d’optimisation
    pass

# ✅ Ce que demandent les karpathy-guidelines :
"""
"Rendre la recherche plus rapide" peut vouloir dire plusieurs choses :
1. Temps de réponse plus court (< 100 ms) : ajouter un index de base de données + cache, estimation 2 heures
2. Plus fort débit de concurrence : refactor asynchrone + pool de connexions, estimation 4 heures
3. Plus rapide à percevoir côté UX : chargement progressif, estimation 3 heures

Lequel voulez-vous ?
"""

Quand une instruction est ambiguë, s’arrêter pour clarifier avant d’agir est bien plus efficace que de finir puis de devoir tout recommencer.

Au niveau du code, cette règle t’exige :

• Exprimer clairement tes hypothèses, et demander quand tu n’es pas sûr
• Quand plusieurs interprétations plausibles existent, toutes les lister pour que l’utilisateur choisisse
• En repérant une option plus simple, la proposer activement
• Dès qu’il y a quelque chose d’imprécis, s’arrêter immédiatement et demander

---

Principe 2 : Simplicity First

Essence : n’écrire que le minimum de code nécessaire pour résoudre le problème actuel, sans conception prédictive.

L’IA a une tendance : elle insère d’un bloc des "bonnes pratiques", même quand elles ne sont pas nécessaires. Vous demandez à l’IA d’écrire un calcul de remise : elle peut vous produire un système complet avec pattern de stratégie + pattern de fabrique + classes de configuration.

Regardez une comparaison réelle :

Demande utilisateur : "Ajouter une fonction de calcul de remise"

# ❌ Ce que fait souvent l’IA : introduire des abstractions inutiles
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Union

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        # ... une tonne de code

# L’utilisation nécessite 30+ lignes de préparation

# ✅ La méthode de Simplicity First :
def calculate_discount(amount: float, percent: float) -> float:
    """Calcule le montant de la remise. percent est un pourcentage : ex. 10 = 10%."""
    return amount * (percent / 100)

# Utilisation

discount = calculate_discount(100.0, 10.0)  # 10% de remise

Critères pour évaluer ce principe :

• On n’ajoute pas de fonctionnalités que personne n’a demandées
• Le code à usage unique n’est pas abstrait
• Si vous n’avez pas besoin de "flexibilité", vous ne prévoyez pas de configuration
• On n’écrit pas de gestion d’erreurs pour des scénarios impossibles
• Après avoir écrit le code, vous vous demandez : "Un ingénieur expérimenté appellerait ça une surconception ?" — si oui, réécrivez

---

Principe 3 : Surgical Changes

Essence : ne modifier que ce qui doit l’être, nettoyer le désordre que vous avez causé, mais ne toucher à rien d’autre.

Quand l’IA corrige un bug, elle a particulièrement tendance à "optimiser en passant" : elle change 3 lignes, puis au passage renomme des variables, reformate, remplace des annotations, etc. karpathy-guidelines demande une précision au niveau "chirurgical".

Un scénario typique : "corriger le problème du validateur qui plante quand l’e-mail est vide"

  def validate_user(user_data):
-     # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")
-     # Check username
-     if not user_data.get('username'):
+     # Check username  ← Écrire exactement comme avant
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ Ce que fait souvent l’IA (en dépassant la demande utilisateur) :

# Elle ajoute aussi :
# - Validation d’e-mail plus stricte (expressions régulières)
# - Vérification de la longueur du nom d’utilisateur
# - Vérification des caractères du nom d’utilisateur
# - docstring
# - Changement du style des guillemets ('' → "")

✅ Ce que demandent les Surgical Changes (ne modifier que les deux lignes liées aux valeurs d’e-mail vides) :

-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

Critère : chaque ligne modifiée doit pouvoir être reliée à la demande précise de l’utilisateur.

---

Principe 4 : Goal-Driven Execution

Essence : traduire "quoi faire" en "comment vérifier que c’est réussi". Remplacer les instructions floues par des critères de succès.

C’est un point que Andrej Karpathy souligne énormément : "Les LLM sont très doués pour itérer jusqu’à atteindre un objectif précis. Plutôt que de leur dire quoi faire, donnez-leur des critères de réussite — puis regardez-les exécuter."

Comparez deux façons de formuler des consignes :

❌ Instruction floue (l’IA n’a aucun repère) :

Réparer le problème du système de connexion

✅ Instruction Goal-Driven (l’IA a une direction claire) :

Problème précis : après changement de mot de passe, l’ancienne session n’est pas invalidée.

Plan :
1. Écrire un test : changer le mot de passe → vérifier que l’ancienne session est rejetée
   Validation : test échoue (reproduction du bug)

2. Implémenter : lors du changement de mot de passe, supprimer la session correspondante
   Validation : test passe

3. Cas limites : connexions multi-appareils, modifications concurrentes du mot de passe
   Validation : tous les tests ajoutés passent

4. Vérification de non-régression : tous les tests liés à la connexion passent
   Validation : pnpm test

Couverture actuelle des tests du module de connexion : [données]
Quel est exactement le problème de connexion que vous rencontrez ?

Format standard pour les tâches en plusieurs étapes :

1. [description de l’étape] → Validation : [méthode de validation]
2. [description de l’étape] → Validation : [méthode de validation]
3. [description de l’étape] → Validation : [méthode de validation]

L’avantage : à chaque étape, l’IA a une checklist claire pour valider, sans avoir à recommencer à demander "est-ce que c’est bon comme ça ?".

---

4. Comment vérifier que les directives ont bien un effet

Après avoir installé karpathy-guidelines, vous pouvez juger si cela agit réellement selon plusieurs axes :

La qualité des diff :

• Les modifications correspondent-elles bien à ce que l’utilisateur a demandé ?
• Y a-t-il des "optimisations en passant" inutiles ?
• Le style des guillemets, les commentaires et les docstrings ont-ils été modifiés sans autorisation ?

Le moment où l’IA pose des questions :

• Quand l’IA rencontre une instruction floue, s’arrête-t-elle pour clarifier ?
• Ou bien devine-t-elle et commence-t-elle à écrire directement ?

La complexité du code :

• Le code nouvellement écrit suffit-il juste ce qu’il faut ?
• Y a-t-il une abstraction excessive ou une surconception ?

Si ces trois dimensions s’améliorent, alors les directives sont en vigueur.

---

5. Fusionner avec le CLAUDE.md déjà existant dans le projet

La plupart des projets ont déjà leur propre CLAUDE.md. Le remplacer directement ferait perdre l’ensemble des configurations existantes. La bonne démarche est de l’ajouter plutôt que de remplacer :

# D’abord vérifier le contenu actuel de CLAUDE.md
cat CLAUDE.md

# Puis fusionner manuellement avec un éditeur, ou :
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Structure suggérée après fusion :

# Description du projet (contenu existant conservé)

---

# karpathy-guidelines (nouveau contenu, PS : recommandé par Andrej Karpathy)

[Collez ici le contenu de CLAUDE.md]

---

## Règles spécifiques au projet

- Utiliser le mode strict de TypeScript
- Tous les endpoints côté API doivent avoir des tests
- Suivre le modèle de gestion des erreurs dans src/utils/errors.ts

---

Dépannage des problèmes fréquents

Q1 : le plugin s’installe mais n’a aucun effet ?

# Confirmer que le plugin est chargé
/plugin list

# Si non : redémarrer Claude Code
# Dans Claude Code, saisissez /exit pour quitter, puis réouvrez

Q2 : CLAUDE.md du projet et plugin se contredisent : que faire ?

C’est CLAUDE.md du projet qui prévaut. Le plugin sert de solution de repli globale, et les fichiers du projet surchargent les réglages du plugin.

Q3 : même pour une tâche simple, l’IA se bloque et demande de confirmer : que faire ?

C’est normal : karpathy-guidelines exige d’obtenir des clarifications sur les instructions floues pour toutes les tâches. Pour des tâches manifestement simples (comme "remplacer la variable a par b"), vous pouvez ajouter explicitement dans votre consigne : "c’est un remplacement simple, fais-le directement". L’IA sautera alors l’étape de confirmation.

Q4 : l’IA ne respecte pas Surgical Changes et modifie quand même le format : que faire ?

Limitez explicitement la portée des modifications dans votre consigne :

Modifiez la vérification des valeurs vides dans la fonction validateEmail : changez seulement cet endroit, ne touchez pas au reste du code ni au format.

Q5 : après avoir fusionné CLAUDE.md, il y a des conflits : comment résoudre ?

Éditez manuellement CLAUDE.md : conservez le contenu existant et les principes ajoutés, évitez les doublons de paragraphes. Si deux endroits définissent le même principe, suivez les règles spécifiques plus concrètes du projet.

Q6 : faut-il appliquer ces principes en rétroaction sur un projet existant ?

Non. karpathy-guidelines contraint le comportement des modifications à venir, pas de vous pousser à refactoriser tout le code existant. Utilisez-le pour guider vos nouvelles interactions de programmation.

---

Lectures complémentaires et pistes avancées

• Le tweet original d’Andrej Karpathy — l’observation à l’origine des pièges de programmation des LLM
• forrestchang/andrej-karpathy-skills — le dépôt GitHub du projet : contient l’intégralité de EXAMPLES.md (de nombreux exemples des deux côtés, à lire attentivement)
• Documentation officielle de Claude Code — comprendre les capacités complètes de la CLI et les options de configuration
• Tutoriel d’intégration OpenClaw — si vous voulez explorer plus loin la pratique locale des AI Agents, OpenClaw offre des capacités plus approfondies d’appel d’outils

---

Pistes avancées

Après avoir maîtrisé les quatre principes, vous pouvez continuer à explorer :

Extensions personnalisées : ajoutez des règles d’encodage spécifiques au projet dans CLAUDE.md, pour que l’IA conserve les contraintes générales de karpathy-guidelines tout en respectant le style propre à votre projet.

Partage au sein de l’équipe : intégrez karpathy-guidelines dans la documentation des normes de codage de l’équipe. Les nouveaux membres clonent le projet et obtiennent automatiquement les règles de comportement pour la programmation par IA.

Mesurer l’efficacité : consigner le nombre de retouches de code par l’IA avant/après l’introduction des directives, la portée des modifications, et le nombre de changements non liés dans les PR, puis valider la valeur réelle de cette méthodologie avec des données.