karpathy-guidelines Einstieg: die empfohlenen Programmierregeln für große Sprachmodelle von Andrej Karpathy

Schwierigkeitsgrad: Einsteigerlevel | Dauer: ca. 15 Minuten | Nutzen: 4 Prinzipien beherrschen + AI-Programmierung nach karpathy-guidelines regelkonform gestalten

Zielgruppe

• Entwicklerinnen und Entwickler, die bereits Claude Code, Cursor, Copilot o.ä. als KI-Code-Assistenz nutzen
• 1–5 Jahre Erfahrung in der Entwicklung und möchten, dass die von der KI generierten Codes präziser sind, weniger „Blabla“ enthalten und nichts ungewollt verändert wird
• Haben bereits praktische Erfahrung mit KI-Programmierung und suchen nach klaren, systematischen Kooperationsregeln

Wichtige Abhängigkeiten & Umgebung

Vollständige Projektstruktur (Tree)

andrej-karpathy-skills/
├── CLAUDE.md                # Kern-Guide-Datei (4 Prinzipien kompakt; gemeinsame Nutzung für Plugin-/Datei-Variante)
├── README.md                # Installations- und Nutzungsanleitung
├── EXAMPLES.md              # Viele praxisnahe Beispiele (inkl. „so nicht“-Beispiele)
└── skills/
    └── karpathy-guidelines/  # Claude-Code-Pluginformat (empfohlen als Installationsmethode)

---

1. Erst das Problem verstehen: Warum LLMs „im eigenen Kopf leben“

Andrej Karpathy hat Ende 2025 einen Tweet veröffentlicht, der das Kernproblem beim Programmieren mit aktuellen großen Sprachmodellen direkt anspricht:

"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."

Übersetzt heißt das sinngemäß: LLMs machen stillschweigend Annahmen zu ihrem eigenen Vorgehen, prüfen nicht nach, gehen bei Unklarheiten nicht in die Klärung, legen keine Widersprüche offen, stellen keine Abwägungen dar und wehren sich nicht, wenn sie es sollten.

Dieses Problem begegnet praktisch jeder Person, die KI tief im Entwicklungsalltag nutzt: Du lässt die KI einen kleinen Bug fixen – und sie schreibt dir gleich ein halbes Modul neu. Du bittest um eine simple Funktion – und sie führt gleich drei Ebenen von Abstraktion ein.

karpathy-guidelines wurde genau für diese vier Probleme entwickelt:

---

2. karpathy-guidelines installieren

Es gibt zwei Installationsarten – empfohlen ist die erste.

Variante 1: Plugin-Variante (empfohlen)

# Schritt 1: Plugin-Marktplatz hinzufügen
/plugin marketplace add forrestchang/andrej-karpathy-skills

# Schritt 2: Plugin installieren
/plugin install andrej-karpathy-skills@karpathy-skills

Nach der Installation lädt Claude Code diese vier Prinzipien automatisch in jedem Projekt.

Variante 2: CLAUDE.md direkt herunterladen (für jedes Projekt)

Neues Projekt:

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

Vorhandenes Projekt (an die bestehende CLAUDE.md anhängen):

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

---

3. Die vier Prinzipien im Detail, Schritt für Schritt

Prinzip 1: Think Before Coding

Kern: Keine Annahmen treffen, keine Verwirrung verstecken, sondern Abwägungen aktiv offenlegen.

Das ist die mit Abstand größte Abweichung von der „AI-Intuition“. Das Trainingsziel von KI ist es, „eine Antwort zu liefern“. Wenn die Anweisung unklar ist, neigt sie dazu, eine möglichst plausible Interpretation zu raten und einfach weiterzumachen – statt stehenzubleiben und zu fragen: „Was genau meinst du damit?“

Der richtige Umgang damit sieht so aus:

# Der Nutzer sagt: „Mach die Suche ein bisschen schneller“

# ❌ Typisches AI-Verhalten: stillschweigend Cache, Index und asynchrones Processing hinzufügen und direkt 200 Zeilen schreiben
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... eine Menge Optimierungscode
    pass

# ✅ karpathy-guidelines verlangt das hier:
"""
„Schneller machen“ kann mehrere Bedeutungen haben:
1. Schneller bei der Antwortzeit (< 100 ms): Datenbankindex + Cache, Schätzung 2 Stunden
2. Höherer Durchsatz bei gleichzeitigen Anfragen: asynchrones Umbauen + Connection Pool, Schätzung 4 Stunden
3. Schnellere wahrnehmbare Geschwindigkeit (UX): schrittweises Laden, Schätzung 3 Stunden

Welche Variante meinst du?
"""

Wenn eine Anweisung unklar ist, zuerst kurz stoppen und nachfragen – das ist deutlich effizienter, als nachher nachbessern zu müssen.

Auf Code-Ebene heißt diese Regel für dich:

• Nenne deine Annahmen explizit; Unklarheiten müssen abgefragt werden
• Wenn es mehrere sinnvolle Interpretationen gibt, liste alle auf und lass den Nutzer auswählen
• Wenn du eine einfachere Lösung findest, schlag sie proaktiv vor
• Sobald etwas unklar ist: sofort stoppen und nachfragen

---

Prinzip 2: Simplicity First

Kern: Nur so viel Code wie nötig, um das aktuelle Problem zu lösen – keine vorausschauende Konstruktion.

KI hat eine Tendenz: sie packt „Best Practices“ ungefragt gleich in einem Rutsch hinein, selbst wenn man sie gerade gar nicht braucht. Wenn du eine KI bittest, eine Rabattberechnung zu schreiben, könnte sie dir ein vollständiges System aus Strategy-Pattern + Factory-Pattern + Konfigurationsklasse bauen.

Ein echtes Gegenbeispiel:

Anfrage des Nutzers: „Füge eine Rabattberechnungsfunktion hinzu“

# ❌ Häufig: unnötige Abstraktionen einführen
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:
        # ... eine Menge Code

# Für die Nutzung brauchst du 30+ Zeilen Vorbereitung

# ✅ So macht man es mit Simplicity First:
def calculate_discount(amount: float, percent: float) -> float:
    """Berechnet den Rabattbetrag. percent ist ein Prozentwert, z. B. 10 = 10%."""
    return amount * (percent / 100)

# Verwendung

discount = calculate_discount(100.0, 10.0)  # 10% Rabatt

Kriterien für dieses Prinzip:

• Funktionen hinzufügen, die niemand verlangt hat: nein
• Code für eine einmalige Nutzung nicht abstrahieren
• Keine „Flexibilität“ vorsehen, wenn man sie nicht braucht
• Keine Fehlerbehandlung schreiben, für die keine fehlerhaften Szenarien zu erwarten sind
• Nach dem Schreiben fragen: „Würde ein erfahrener Engineer sagen, das sei Overengineering?“ Wenn ja: neu schreiben

---

Prinzip 3: Surgical Changes

Kern: Nur das Nötigste ändern, den eigenen Müll aufräumen, aber nichts anfassen, das von Haus aus schon da ist.

KI beim Fixen von Bugs neigt besonders dazu, „nebenbei zu optimieren“: 3 Zeilen Bugfix ändern, zusätzlich Variablennamen umbenennen, Formatierung anpassen, Kommentare austauschen. karpathy-guidelines verlangt präzise Änderungen auf Skalpell-Niveau.

Ein typisches Szenario: Der Nutzer sagt „Behebe das Problem, dass der Validator beim leeren E-Mail-Feld abstürzt“

  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  ← so war es vorher auch
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ Typisches KI-Verhalten (über den angefragten Umfang hinaus):

# Nebenbei noch Folgendes hinzugefügt:
# - Strengere Validierung des E-Mail-Formats (Reguläre Ausdrücke)
# - Prüfung der Länge des Benutzernamens
# - Prüfung der erlaubten Zeichen im Benutzernamen
# - docstring
# - geänderte Quote-Styles ('' → "")

✅ Surgical Changes-Anforderung (nur die zwei Zeilen für die Behandlung leerer E-Mails ändern):

-     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")

Bewertungskriterium: Jede geänderte Codezeile muss auf die konkrete Anfrage des Nutzers zurückverfolgbar sein.

---

Prinzip 4: Goal-Driven Execution

Kern: Aus „Was soll gemacht werden?“ wird „Woran wird Erfolg gemessen?“ Übersetze unklare Anforderungen in überprüfbare Erfolgskriterien.

Das ist der Punkt, den Andrej Karpathy am stärksten betont: „LLMs sind sehr gut darin, iterativ auszuführen, bis ein bestimmtes Ziel erreicht ist. Statt ihnen zu sagen, was sie tun sollen, gib ihnen Erfolgskriterien – dann lass sie selbst loslaufen.“

Vergleich der beiden Arten von Anweisungen:

❌ Unklare Anweisung (KI weiß nicht, wohin):

Probleme im Login-System beheben

✅ Goal-Driven Anweisung (KI hat eine klare Richtung):

Konkretes Login-Problem: Nach dem Ändern des Passworts läuft die alte Session nicht ab.

Plan:
1. Tests schreiben: Passwort ändern → prüfen, dass die alte Session abgelehnt wird
   Verifikation: Test schlägt fehl (Bug reproduzieren)

2. Implementierung: Beim Passwortwechsel Sessions des betroffenen Nutzers löschen
   Verifikation: Test besteht

3. Randfälle: Login von mehreren Geräten, Passwortwechsel parallel
   Verifikation: Alle neu hinzugefügten Tests bestehen

4. Regression-Check: Alle bestehenden Login-Tests bestehen
   Verifikation: pnpm test

Aktuelle Testabdeckung im Login-Modul: [Daten]
Welches konkrete Login-Problem ist bei euch genau aufgetreten?

Standardformat für mehrstufige Aufgaben:

1. [Schrittbeschreibung] → Verifikation: [Wie wird geprüft]
2. [Schrittbeschreibung] → Verifikation: [Wie wird geprüft]
3. [Schrittbeschreibung] → Verifikation: [Wie wird geprüft]

Der Vorteil: Nach jedem Schritt gibt es eine klare Checkliste. Du musst nicht ständig wieder nachfragen „Passt das so?“, sondern kannst direkt gegen die Erfolgskriterien prüfen.

---

4. Wie du prüfst, ob die Guidelines wirklich wirken

Wenn karpathy-guidelines installiert ist, kannst du über mehrere Aspekte erkennen, ob es tatsächlich greift:

Diff-Qualität ansehen:

• Sind die Änderungen wirklich nur das, was vom Nutzer verlangt wurde?
• Gibt es überflüssige „Nebenbei-Optimierungen“?
• Wurden Quote-Styles, Kommentare, docstrings einfach so geändert?

Zeitpunkt des Nachfragens ansehen:

• Stoppt die KI bei unklaren Anweisungen von sich aus und fragt nach?
• Oder rät sie einfach und legt direkt los?

Komplexität des Codes ansehen:

• Ist der neu geschriebene Code genau so groß wie nötig?
• Gibt es Overengineering bzw. übertriebenes Design?

Wenn alle drei Dimensionen sichtbar besser werden, dann wirkt die Guideline.

---

5. Mit bestehendem CLAUDE.md des Projekts zusammenführen

Die meisten Projekte haben bereits eine eigene CLAUDE.md. Direkte Überschreibung würde die bisherigen Einstellungen verlieren. Richtig ist Anhängen statt Ersetzen:

# Erst prüfen, was bereits in der CLAUDE.md steht
cat CLAUDE.md

# Danach im Editor manuell mergen – oder:
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Empfohlene Struktur nach dem Merge:

# Projektbeschreibung (bestehender Inhalt bleibt erhalten)

---

# karpathy-guidelines (neuer Inhalt, PS: Andrej Karpathy empfiehlt das)

[Hier den Inhalt von CLAUDE.md einfügen]

---

## Projektspezifische Regeln

- TypeScript strict Mode verwenden
- Alle API-Endpunkte müssen Tests haben
- Fehlerbehandlung gemäß dem Muster in src/utils/errors.ts

---

Häufige Probleme (Troubleshooting)

Q1: Plugin installiert, aber wirkt nicht?

# Prüfen, ob das Plugin geladen wurde
/plugin list

# Falls nicht: Claude Code neu starten
# In Claude Code /exit eingeben, um zu verlassen, dann erneut starten

Q2: Projekt-CLAUDE.md und Plugin kollidieren — was tun?

Es gilt die projektbezogene CLAUDE.md. Das Plugin liefert globale Fallback-Verhalten; die Projektdatei überschreibt die Plugin-Einstellungen.

Q3: Auch einfache Aufgaben werden „abgebremst“ und verlangen Bestätigung — wie damit umgehen?

Das ist ein normales Verhalten: karpathy-guidelines verlangt bei allen Aufgaben gleichermaßen, unklare Anweisungen zu klären. Bei erkennbar einfachen Aufgaben (z. B. „die Variable a zu b ändern“) kannst du in der Anweisung explizit hinzufügen: „Das ist ein einfacher Austausch, direkt machen.“ Dann springt die KI meist über die Bestätigungs-Runde hinweg.

Q4: KI hält sich nicht an Surgical Changes und verändert trotzdem das Format wild — was tun?

Schränke den Änderungsumfang in der Anweisung explizit ein:

In der validateEmail-Funktion die Prüfung für leere Werte ändern – nur genau diese Stelle, nichts anderes anfassen und kein anderes Format ändern.

Q5: Nach dem Merge von CLAUDE.md gibt es Konflikte — wie lösen?

Bearbeite CLAUDE.md manuell: Behalte den bestehenden Inhalt und die neu hinzugefügten Prinzipien und vermeide doppelte Abschnitte. Wenn zwei Stellen dasselbe Prinzip definieren, gilt die konkrete Regel aus der projektinternen CLAUDE.md.

Q6: Muss man diese Prinzipien auf bestehende Projekte rückwirkend anwenden?

Nein. karpathy-guidelines bindet nur das zukünftige Änderungsverhalten ein – nicht dazu, bereits vorhandenen Code rückwirkend zu refaktorisieren. Nutze es, um neue Programmier-Interaktionen zu steuern.

---

Weiterführende Lektüre & nächste Schritte

• Andrej Karpathy ursprünglicher Tweet — Ausgangsbeobachtung zu den Programmier-Fallen von LLMs
• forrestchang/andrej-karpathy-skills — GitHub-Repo dieses Projekts mit vollständigem EXAMPLES.md (viele echte Beispiele pro und contra; sehr empfehlenswert)
• Offizielle Claude-Code-Dokumentation — um die vollständigen CLI-Fähigkeiten und Konfigurationsoptionen zu verstehen
• OpenClaw-Integrationstutorial — falls du lokale AI-Agent-Praxis weiter erkunden willst: OpenClaw bietet tiefere Fähigkeiten für Tool-Calls

---

Nächste Schritte

Nachdem du die vier Prinzipien beherrschst, kannst du in folgende Richtungen weiterforschen:

Individuelle Erweiterungen: Ergänze in CLAUDE.md projektspezifische Kodierkonventionen, damit die KI neben den allgemeinen karpathy-guidelines auch die Projekt-„Style“-Vorgaben übernimmt.

Teamweit teilen: Integriere karpathy-guidelines in die Teamdokumentation der Coding Rules. Neue Teammitglieder erhalten beim Klonen des Projekts automatisch die Richtlinien für AI-Programmierung.

Wirkung messen: Erfasse, wie oft AI nach Einführen der Guidelines nacharbeiten musste, wie groß der Änderungsumfang war und wie viele „unbeteiligte“ Änderungen in PRs entstanden sind. Verifiziere so mit Daten den tatsächlichen Mehrwert dieser Methodik.