KI-Coding

MISTAKES.md und Claude Code: Wiederholte Fehler in Regeln verwandeln

Leitfaden für knappe MISTAKES.md-Einträge, Null-Secrets, die Beförderung zu Tests oder Regeln und die Prüfung von Claude-Code-Leitplanken.

BT

BetterToken

Redaktion
3 Min. Lesezeit

Bei komplexen Repositories trifft Claude Code unvermeidlich auf nicht offensichtliche Eigenheiten: veraltete TypeScript-Definitionen, versteckte Laufzeitabhängigkeiten oder bundler-spezifisches Verhalten. Dieselbe Korrektur immer wieder im Chat vorzunehmen verschwendet Kontext und Zeit. Mehrseitige Sitzungsprotokolle in Anweisungen zu kopieren verursacht dagegen Prompt-Müll und schwächere Modellaufmerksamkeit.

Ein praktisches Muster ist eine schlanke MISTAKES.md im Repository-Root. Sie hält nur reproduzierbare Vorfälle, bestätigte Ursachen und Vorbeugungen fest. Anschließend werden sie in Projekttests, Linter-Regeln und dauerhafte Konfiguration überführt.

1. MISTAKES.md statt Sitzungsprotokoll

Verwechseln Sie ein Incident-Log nicht mit einem rohen Terminaltranskript:

DimensionSitzungsprotokollMISTAKES.md-Incident-Log
UmfangTausende Zeilen Tool-Aufrufe und Zwischenschritte5–10 strukturierte Zeilen pro Vorfall
ZweckEinmaliges Debugging und AuditReferenz zur Vermeidung künftiger Wiederholung
SecretsKann rohe Umgebungsvariablen oder Tokens enthaltenStrikt verboten: keine Credentials oder Secrets
LebensdauerVergängliches ArtefaktDauerhafte Dokumentation bis zur Automatisierung

MISTAKES.md muss kurz bleiben, damit Claude Code sie zu Sitzungsbeginn einlesen kann, ohne unnötig Context Tokens zu verbrauchen.

2. Aufbau eines Incident-Eintrags

Jeder Eintrag hat vier Pflichtfelder:

  1. Incident: Was brach unter welchen Bedingungen genau—Fehlercode, Befehl, Tool?
  2. Impact: Nachgelagerte Wirkung, beispielsweise fehlerhafter Build, beschädigte Migration oder abgebrochene Tests.
  3. Root Cause: Bestätigte technische Ursache; ist sie unbewiesen, ausdrücklich als [Hypothesis] markieren.
  4. Prevention: Konkrete Regel oder Prüfung gegen die Wiederholung.

Beispiel für einen Incident-Eintrag

ERR-014: PostgreSQL-Migration bei DROP COLUMN ohne CASCADE fehlgeschlagen

  • Incident: Claude Code führte in Migration 0042 ALTER TABLE orders DROP COLUMN customer_ref; aus.
  • Impact: Das Staging-Deployment scheiterte an der abhängigen View v_active_orders.
  • Root Cause: Views, die Basistabellen referenzieren, brauchen eine explizite Neuerstellung mit Cascade oder vorherige View-Updates.
  • Prevention: Jede DDL-Migration zum Entfernen einer Spalte muss vor der Ausführung abhängige Views über pg_depend prüfen.

> [!IMPORTANT]
> **Null-Secrets-Richtlinie:** Niemals echte Datenbank-Verbindungsstrings, private Schlüssel, Tokens oder `.env`-Ausschnitte in `MISTAKES.md` committen. Claude-Code-API-Keys über lokale Umgebungsvariablen verwalten.

Für eine zuverlässige Claude-Code-Konfiguration mit API-Provider verwenden Sie Ihren eigenen API-Key und folgen der [BetterToken-Claude-Code-Integration](https://docs.bettertoken.ai/ai-tools/claude-code).

---

3. Beförderung vom Log zu Test oder Regel

Nicht jeder einmalige Tippfehler verdient eine permanente Regel. Eine klare Schwelle überführt Einträge in automatisierte Gates:

Vorfall eingetreten
  │
  ├─> Erstes Mal: 4-Felder-Eintrag in MISTAKES.md
  │
  └─> Zweites Mal (Wiederholung):
        │
        ├─> Mechanisch prüfbar?
        │     └─> JA: Unit-Test, ESLint-Regel oder Pre-Commit-Hook ergänzen
        │
        └─> NEIN: Strikte negative Anweisung in CLAUDE.md / AGENTS.md ergänzen
  1. Erstes Auftreten: Einen knappen Eintrag in MISTAKES.md ergänzen.
  2. Zweites Auftreten: Ist das Problem deterministisch prüfbar, Test oder Linter-Regel schreiben. Automatische Gates sind Textprompts überlegen.
  3. Nicht-mechanische Prüfungen: Eine ausdrückliche negative Regel in CLAUDE.md formulieren, etwa „Jest in CI nie ohne --runInBand ausführen“.
  4. Archivierung: Sobald Test oder Hook eingesetzt ist, den Eintrag archivieren oder aus MISTAKES.md entfernen, damit die Datei nicht anwächst.

4. Beim nächsten Task verifizieren

So prüfen Sie die neue Leitplanke:

  1. Eine frische Claude-Code-Sitzung starten.
  2. Einen Prompt geben, der den früheren Fehler ausgelöst hat.
  3. Prüfen, ob der Agent die neue Regel einhält oder der Pre-Commit-Hook ihn stoppt.
  4. Umgeht der Agent Textanweisungen, die Einschränkung in einen strikten Command-Wrapper oder eine automatische Prüfung überführen.

Diese Rückkopplung verwandelt zufällige Entwicklungsfehler in eine robuste, sich selbst verbessernde Engineering-Grundlage.

Bereit, Ihren LLM-Workflow zu optimieren?

Verbinden Sie Modelle über eine API, verwalten Sie Schlüssel und behalten Sie KI-Kosten im Blick.