mattpocock Skills Leitfaden für den Einstieg: Lass KI TDD lernen und strukturiertes Debugging durchführen

Projektüberblick

mattpocock/skills ist ein „Engineering-Methoden“-Skillset für KI-Programmierwerkzeuge. Die Grundidee ist sehr einfach: KI-Programmierwerkzeuge sind schnell – aber nicht automatisch zuverlässig.

Bei intensiver Praxis hat Matt Pocock vier häufige Fehlmuster im KI-Programmieren entdeckt:

• Anforderungs-Fehlausrichtung: Du glaubst, die KI versteht es – tatsächlich läuft sie in die falsche Richtung
• Zu viel Redundanz im Output: Die KI verwendet 20 Wörter, um etwas zu erklären, das mit 1 Wort klar wäre
• Code funktioniert nicht: Ohne Feedback-Loop schreibt die KI im „Black Box“-Modus blind
• Architektur verrottet schnell: Die KI beschleunigt die Entwicklung – und ebenso schnell wächst die Software-„Entropy“

Diese vier Probleme sind kein Bug der Tools, sondern ein Fehlen der Methodik. mattpocock/skills liefert die passende Antwort: Es komprimiert Jahrzehnte Engineering-Erfahrung in eine Reihe kombinierbarer Fähigkeiten (Skills), sodass die KI – unabhängig vom Modell – dieselbe Engineering-Disziplin befolgt.

Schwierigkeit / Dauer / Nutzen

Schwierigkeit: Einsteigerfreundlich – keine TDD-Erfahrung nötig; nur Befehlszeile und ein KI-Programmierwerkzeug verwenden
Dauer: ca. 30 Minuten, um den Prozess einmal vollständig durchzugehen
Nutzen: Ein vollständiger Arbeitsablauf von Anforderungs-Alignment → testgetriebener Entwicklung → strukturiertem Debugging → Architektur-Reflexion

Zielgruppe

• Backend-/Full-Stack-Entwickler mit 1–5 Jahren Erfahrung
• Nutzt bereits Claude Code, Codex oder ähnliche KI-Programmierwerkzeuge
• Hat den Eindruck, dass von der KI generierter Code zwar „läuft, aber instabil ist“, und möchte einen kontrollierbaren Entwicklungsrhythmus aufbauen
• Interessiert sich für TDD, hat aber nie den richtigen Einstieg gefunden

Wichtige Abhängigkeiten und Umgebung

Vollständige Projektstruktur (Tree)

skills/
├── CLAUDE.md                          # Vorgaben für das Skill-Verzeichnis
├── README.md                          # Übersicht und Nutzungsdokumentation
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # Strukturierter Debugging-Workflow
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # Tiefengespräche mit Zusatzdokumentation
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # Diagnose zur Architekturverbesserung
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # Einstieg für die Initialisierung
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # TDD als vertikaler Slice-Workflow
│   │   │   ├── tests.md               # Beispiele für „gut / schlecht“ Tests
│   │   │   ├── mocking.md             # Best Practices für Mocking
│   │   │   ├── refactoring.md         # Zeitpunkt für Refactoring beurteilen
│   │   │   ├── deep-modules.md        # Prinzipien für Deep-Modul-Design
│   │   │   └── interface-design.md    # Testsichere Schnittstellengestaltung
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # Anforderungen in GitHub Issues aufteilen
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # PRD-Generierung
│   │   ├── triage/
│   │   │   └── SKILL.md               # Issue-Triage als Zustandsmaschine
│   │   └── zoom-out/
│   │       └── SKILL.md               # Globale Perspektive auf den Code
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # Komprimierte Kommunikationsform, spart 75% Token
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # Tiefengespräch über Anforderungen
│   │   └── write-a-skill/
│   │       └── SKILL.md               # Leitfaden zum Schreiben eigener Skills
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Git-Sicherheitsleitplanken
│       └── scaffold-exercises/
│           └── SKILL.md               # Übungs-Verzeichnis als Gerüst (Scaffold)
└── .claude-plugin/
    └── plugin.json                    # Plugin-Metadaten

Schritt-für-Schritt-Anleitung

Schritt 1: mattpocock Skills installieren

In einem KI-Programmierwerkzeug, das Skills unterstützt, führe den folgenden Befehl aus, um die Installation abzuschließen:

npx skills@latest add mattpocock/skills

Das Installationsskript führt dich durch die Auswahl, welche Skills aktiviert werden sollen und an welches KI-Tool diese Skills gebunden sind. Schlüsselschritt: Stelle sicher, dass du /setup-matt-pocock-skills auswählst – das ist der Initialisierungspunkt für alle nachfolgenden Skills.

Schritt 2: Konfiguration initialisieren

Nach Abschluss der Installation führe in deinem KI-Programmierwerkzeug aus:

/setup-matt-pocock-skills

Dieser Skill fragt dich nacheinander:

1. Issue Tracker: Welches Tool du zur Verwaltung von Issues nutzt (GitHub / Linear / lokale Dateien)
2. Triage-Labels: Welche Begriffe du zum Labeln von Issues verwendest (der /triage Skill wird das nutzen)
3. Dokument-Speicherpfad: Wo die generierten ADRs und Dokumente abgelegt werden

Nach dem Abschluss der Konfiguration wird im Projekt-Root ein CONTEXT.md erzeugt, der als „gemeinsames Sprachwörterbuch“ zwischen der KI und dir dient. Diese Datei ist sehr wichtig – sie vereinheitlicht, wie Begriffe im Projekt verwendet werden. Danach werden alle Benennungen und Kommentare von der KI darauf basieren.

Schritt 3: Mit /grill-me Anforderungen ausrichten

Wenn du eine neue Anforderung oder eine Design-Idee hast, die du der KI geben möchtest, lege nicht einfach los. Führe zuerst aus:

/grill-me

Die KI fragt dich nacheinander und deckt jeden Zweig des Entscheidungsbaums vollständig ab. Wenn du z. B. planst, „dem Zahlungsmodul eine Refund-Funktion hinzuzufügen“, fragt die KI nach:

• Sind Refunds vollständige Beträge oder Teilbeträge?
• Was sind die Auslösekriterien für Refunds (vom Nutzer aktiv / automatisch per Risk-Control / manuell durch den Support)?
• Wie wird der Bestand nach einem Refund behandelt?
• Soll der Refund-Log persistent gespeichert werden?

Jede Frage liefert dir eine empfohlene Antwort – du musst nur bestätigen oder korrigieren. Der Prozess ist wie ein strukturiertes Interview: Damit wird sichergestellt, dass die KI wirklich versteht, was du tun willst – und nicht „wörtlich missverstanden“ in die falsche Richtung läuft.

Schritt 4: Mit /tdd vertikale Slices testgetrieben umsetzen

Nach der Ausrichtung der Anforderungen geht es in die Entwicklungsphase. Hier kommt der Kern von mattpocock/skills – horizontales Slice-Testing ist verboten.

Was ist ein horizontales Slice? Erst alle Tests fertig schreiben, dann erst alle Codes. Das ist der Bereich, in dem TDD besonders häufig missverstanden wird. KI macht das besonders leicht – mit dem Ergebnis, dass die Tests „das testen, was man sich ausgedacht hat“, nicht das reale Verhalten.

Korrekt ist: Immer nur einen vertikalen Slice auf einmal.

RED:   Einen Test schreiben, der das erste Verhalten beschreibt → Test schlägt fehl
GREEN: Minimalen Code schreiben, damit der Test durchläuft → Test ist grün
REFACTOR: Refactoring (optional)

Diesen Loop wiederholen. Nachdem die KI einen Test fertiggeschrieben hat, hat sie „die Implementierung bereits gesehen“ – daher testet sie das reale Verhalten, nicht das erwartete.

Schauen wir uns ein konkretes Beispiel an. Angenommen, wir sollen eine Checkout-Funktion für einen Warenkorb implementieren:

// Erste Runde: Nur testen „Warenkorb kann Artikel hinzufügen“
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript Einstieg', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — minimale Implementierung, damit der Test durchläuft
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// Zweite Runde: Teste „Warenkorb kann den Gesamtpreis berechnen“
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript Einstieg', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React Praxis', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — totalPrice-Methode hinzufügen
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Jede Runde folgt demselben Muster: Test schlägt fehl → minimaler Code macht ihn grün → nächste Runde. Das ist der Kern des vertikalen Slice-Rhythmus.

Schritt 5: Mit /diagnose strukturiertes Debugging durchführen

Wenn der Code kaputt ist, lass die KI nicht einfach „bitte hilf mir, den Bug zu fixen“. Baue zuerst eine Feedback-Loop auf, indem du ausführt:

/diagnose

/diagnose zwingt die KI dazu, die Debugging-Loop in sechs Phasen vollständig durchzugehen:

Warum ist dieser Ablauf wichtig? Denn die häufigste Debugging-Art der KI ist: „einfach raten und ändern, dann das Ergebnis prüfen; wenn es nicht passt, wieder raten“. Ohne Feedback-Loop ist das gleichbedeutend damit, im Dunkeln Darts zu werfen. /diagnose macht Debugging zu einer Engineering-Disziplin – nicht zu Magie.

Ein typisches Szenario: Angenommen, deine Zahlungs-API liefert plötzlich 500 zurück:

// Phase 1: Feedback-Loop aufbauen — schreibe einen fehlschlagenden Test, der auf eine konkrete API abzielt
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // aktuell fehlschlagend, real wird 500 zurückgegeben
  });
});

In Phase 3 wird eine Hypothesenliste generiert:

1. Wenn es „Timeout des Inventory-Services führt zu nicht abgefangenem Exception“ ist, dann sollte ein Mock der Inventory-Services auf Erfolg das 500 beseitigen
2. Wenn es „DB-Transaktion wird nicht committet“ ist, dann zeigt die Prüfung, ob transaction.commit() aufgerufen wird, das Problem
3. Wenn es „Parsing-Fehler im Payment-Gateway-Format“ ist, dann kann man mit validierter Mock-Gateway-Datenformatigkeit das Problem reproduzieren

Die KI validiert Hypothese für Hypothese – statt alle Änderungen auf einmal zusammenzustapeln.

Schritt 6: Mit /write-a-skill eigene Skills bauen

Wenn du in einem bestimmten Projekt eine wiederkehrende, eigene Arbeitsweise aufgebaut hast, kannst du sie als Skill kapseln – sodass die KI diesen Skill in diesem Projekt jederzeit aufrufen kann:

/write-a-skill

Die KI fragt dich nacheinander:

1. Welches Gebiet deckt dieser Skill ab?
2. Welche konkreten Use-Cases gibt es?
3. Soll er zusätzliche Skripte mitbringen oder nur reine Befehle?
4. Gibt es Referenzmaterial?

Anschließend erstellt sie die Standardstruktur:

my-custom-skill/
├── SKILL.md              # Haupt-Befehlsdatei (erforderlich)
├── REFERENCE.md          # Detaillierte Dokumentation (wird ab >100 Zeilen aufgeteilt)
├── EXAMPLES.md           # Nutzungsszenarien
└── scripts/
    └── helper.ts         # Hilfsskript (optional)

Das description-Feld in SKILL.md ist der einzige Einstiegspunkt, über den die KI diesen Skill wahrnimmt – mit strikt vorgegebenem Format:

---
name: my-custom-skill
description: Generiere typesichere API-Clients aus einem JSON-Schema und injiziere Mock-Daten.
              Use when user mentions "API client", "generate types", or "mock data".
---

die erste Zeile von description sagt „was es macht“, die zweite Zeile sagt „wann es ausgelöst wird“; Trigger-Wörter führen die KI dazu, den Skill automatisch zu laden.

Häufige Probleme beheben

1. KI führt keine Tests aus und schreibt stattdessen Code direkt

Erscheinungsbild: Du rufst /tdd auf, aber die KI springt direkt zur Implementierung und überspringt die RED-Phase.

Fehlersuche:

• Prüfe, ob CONTEXT.md das Testframework des Projekts und die Test-Konventionen bereits definiert
• Starte /tdd und sage explizit: „Schreibe nur einen Test; schreibe keinen weiteren Code“
• Wenn die KI weiterhin überspringt, gib im Chat manuell ein: „Schreibe zuerst einen fehlgeschlagenen Test“, damit sie zurück zu RED geführt wird

Root Cause: KI versteht TDD rein wörtlich – sie glaubt, „Tests schreiben“ sei TDD. Sie versteht nicht, dass „Test schlägt fehl“ selbst ein Signal ist.

---

2. Gefahr horizontaler Slices — alle Tests auf einmal schreiben

Erscheinungsbild: Die KI generiert in /tdd auf einmal 10 Testdateien und schreibt dann auch alle Implementierungen auf einmal.

Fehlersuche:

• Direkt eingreifen: Sag der KI „Schreibe nur den ersten Test und implementiere dann nur dafür“
• Ergänze in CONTEXT.md einen Hinweis gegen Anti-Patterns: „Horizontale Slices sind verboten; arbeite immer nur vertikale Slices einzeln ab“

Root Cause: KI hat eine Vorliebe für die Illusion „alles auf einmal erledigen“. Horizontales Slicing fühlt sich zwar vollständig an, produziert aber tatsächlich spröden Output.

---

3. Debug-Loop ohne Feedback-Signale

Erscheinungsbild: Du rufst /diagnose auf, aber die KI verändert nur wieder und wieder den Code, ohne ein wiederholbares Fehlersignal aufzubauen.

Fehlersuche:

• Wenn Phase 1 nicht besteht, gehe nicht zu Phase 2 über. Sag der KI klar: „Es gibt noch kein wiederholbares Fehlersignal – baue die Feedback-Loop weiter auf“
• Versuche, mit node-fetch und echten HTTP Requests ein End-to-End-Signal aufzubauen, statt das komplette Modul zu mocken

Root Cause: Die Feedback-Loop ist das Herzstück des Debuggings – ohne sie sind alle folgenden Schritte blind.

---

4. Skill-Beschreibung funktioniert nicht — Skill wird nicht automatisch getriggert

Erscheinungsbild: Du hast einen Custom Skill geschrieben, aber die KI lädt ihn nicht.

Fehlersuche:

• Prüfe, ob der Skill in plugin.json registriert ist
• Bestätige, dass die description Trigger-Wörter enthält (Begriffe, die Nutzer tatsächlich sagen)
• Bestätige, dass die name- und description-Formate in SKILL.md den Anforderungen entsprechen (YAML Frontmatter)

Root Cause: Das Laden von Skills hängt von Keyword-Matches in der description ab; ungenaue Beschreibungen verhindern, dass der Skill ausgelöst wird.

---

5. /grill-me wird zu einseitigem Reporting

Erscheinungsbild: Wenn du /grill-me ausführst, erhält die KI nur deine Informationen, fragt aber nicht proaktiv nach.

Fehlersuche:

• Lass die KI erst beim Nachfragen erklären, dass sie in den Interview-Modus gewechselt ist – dann weiter antworten, nicht abbrechen
• Wenn die KI nach über 3 Runden schweigt, sag manuell: „Bitte frag weiter, ich habe noch mehr Informationen“
• Die Ursache liegt typischerweise darin, dass die KI „es bereits verstanden“ glaubt, obwohl sie es nur wörtlich verstanden hat

Root Cause: KI tendiert dazu, schnell zu einem Zustand zu konvergieren, der „so wirkt, als hätte sie es verstanden“ – statt alle Zweige wirklich durchzuspielen.

---

6. CONTEXT.md wird zu groß und führt zu Token-Explosion

Erscheinungsbild: Mit Fortschritt des Projekts wird CONTEXT.md immer größer, und die KI bekommt Kontext-Überläufe oder antwortet deutlich langsamer.

Fehlersuche:

• Refaktoriere CONTEXT.md regelmäßig: „stabile allgemeine Begriffe“ behalten, aber „temporäre Entscheidungsnotizen“ nach docs/adr/ verschieben
• /improve-codebase-architecture kann dabei helfen, zu erkennen, welche Inhalte aus CONTEXT.md extrahiert werden sollten

Root Cause: CONTEXT.md ist dynamisch wachsend. Wenn man es nicht pflegt, wird es schnell zum zweiten Monorepo.

Weiterführende Lektüre / Fortgeschrittene Richtungen

Methodik-Erweiterung: Matt Pocock selbst ist ein Befürworter von TypeScript-Type-Tuning. Sein Kurs Total TypeScript ist eine hervorragende Ergänzung, um type-getriebenes Entwickeln zu verstehen.

Von TDD zur Architekturverbesserung: Nachdem dein Codebase mehrere Runden von TDD-Refactoring durchlaufen hat, kannst du /improve-codebase-architecture für eine Architekturdiagnose verwenden. Es basiert auf der Domänensprache in CONTEXT.md und den Decision Records in docs/adr/, um „flache Module“ (komplexe Interfaces, aber wenig Funktionalität) sowie Refactoring-Chancen zu identifizieren.

Ökosystem eigener Skills: Die Designphilosophie von mattpocock/skills lautet „klein und gut kombinierbar“. Du musst nicht alle bereitgestellten Skills verwenden – du kannst nur /tdd und /diagnose installieren und die Skills schrittweise in den Alltag einführen. In der Community gibt es außerdem weitere Entwickler, die auf diesem Framework eigene Skill-Sets gebaut haben – es lohnt sich, das im Blick zu behalten.