grill-with-docs: Wie du die KI dazu bringst, nicht sofort zu nicken, sondern erst deinen Plan zu zerlegen

In 30 Sekunden · keine Zeit für alles? Nimm das mit

Das Problem: Die KI ist zu willfährig. Halbgarer Plan rein → sie schreibt Code → deine Unschärfe geht mit ins Projekt.

grill-with-docs macht das Gegenteil: Es nimmt dich ins Verhör. Mit dem CONTEXT.md-Glossar und dem Quellcode deines Projekts pickt es deinen Plan Punkt für Punkt auseinander.

Wie es verhört: eine Frage nach der anderen, Empfehlung zuerst; liest den Code, statt zu fragen, wenn es kann; ein Begriff steht → ab ins CONTEXT.md; eine schwer umkehrbare Entscheidung → ein ADR.

Installieren: npx skills@latest add mattpocock/skills · Benutzen: “Nimm meinen Plan mit grill-with-docs ins Verhör: ”

Am besten für: ein komplexes Feature in ein gewachsenes Projekt einbauen, wo ein paar Wörter für verschiedene Leute Verschiedenes bedeuten. Spar dir’s: leeres Repo / triviale Änderung / die Erwartung, dass es den Code für dich schreibt.

1. Eine willfährige KI ist ein stilles Risiko

Das Gefährlichste am Pair-Programming mit einer KI: Sie widerspricht dir so gut wie nie.

Du wirfst ihr einen halbgaren Plan hin – “Bau ein Feature: Nutzer sollen ein paar Artikel aus einer Bestellung stornieren können und das Geld dafür zurückbekommen” – und sie zuckt nicht mit der Wimper: “Klar!”, und schon sprudelt der Code raus. Aber in diesem einen Satz steckt ein Haufen Dinge, die du nie festgenagelt hast, und sie fragt nach keinem davon: “Stornieren” vor oder nach dem Versand? Wessen Aufgabe ist die Rückzahlung? Ist das dasselbe, was dein Code längst Cancellation nennt? Sie fragt nicht. Sie nimmt für dich an – und backt diese Annahmen in den Code.

Drei Wochen später merkst du, dass das eine Wort “stornieren” für Produkt, Code und Datenbank je etwas anderes heißt. Der Code ist Matsch.

Es liegt nicht daran, dass die KI nicht klug wäre. Sie will nur so verzweifelt helfen, dass sie nicht innehält, um dich zum Nachdenken zu zwingen.

grill-with-docs dreht den Spieß um: Es hält die KI vom Nicken ab und nimmt erst deinen Plan ins Verhör (to grill heißt löchern, über die Glut halten). Solange die Begriffe nicht scharf sind, geht es nicht weiter.

2. Wie es funktioniert: ein Verhör mit dem Gedächtnis deines Projekts

Der Mechanismus in einer Zeile: Es nutzt die eigene Sprache und die Entscheidungen deines Projekts, um deinen neuen Plan zu löchern.

Ein paar Details (Matt hat dieses Verhalten in zwei Skills zerlegt, grilling und domain-modeling – dazu unten mehr):

Eine Frage nach der anderen, Empfehlung zuerst. Es geht den Entscheidungsbaum deines Plans Abzweigung für Abzweigung durch, und jede Frage beginnt mit “Ich würde das nehmen, weil …” – statt dir einen Fragebogen mit zwanzig Punkten vor die Nase zu knallen.

Kann es den Code lesen, fragt es dich nicht. Alles, was ein kurzer Blick in den Quellcode beantwortet, schlägt es selbst nach.

Es hält dich am Glossar fest. Das CONTEXT.md im Projektwurzelverzeichnis ist sein Maßstab. Sag ein Wort, das nicht zur Definition passt, und es stoppt dich auf der Stelle: “Dein Glossar sagt, ‘void’ heißt X, aber du meinst eindeutig Y – was denn nun?”

Schwammige Wörter werden geschärft. Sag “Account”, und es fragt: “Meinst du den Customer oder den User? Das sind zwei verschiedene Dinge.”

Es gleicht mit dem Code ab. Behauptest du, ein Feature funktioniere so und so, liest es den Code zur Gegenprobe; passt es nicht, sagt es das: “Der Code storniert die ganze Bestellung, aber du sagst gerade Teilstorno – was gilt?”

Steht ein Begriff fest, wandert er sofort ins CONTEXT.md. Nicht sammeln, kein “später”.

Nur eine schwer umkehrbare Entscheidung verdient ein ADR. Mit ADRs (Architecture Decision Records) ist es geizig: Es schlägt eins nur vor, wenn alle drei Bedingungen gelten – schwer umkehrbar, ohne Kontext verwirrend, das Ergebnis eines echten Abwägens.

Im Kern sind das die zwei ernsten Gewohnheiten aus Domain-Driven Design – ubiquitous language (die durchgängige, von allen geteilte Fachsprache) und eine Entscheidungsspur hinterlassen – verpackt in ein Gespräch, aus dem du dich nicht herauswinden kannst.

Eine Änderung, die du kennen solltest: Es sind eigentlich zwei zusammengeschraubte Skills. Matt hat grill-with-docs aufgeteilt in grilling (das unerbittliche Verhör) und domain-modeling (die Disziplin um Glossar und ADRs) und grill-with-docs selbst zu einer dünnen Hülle gemacht, deren ganzer Inhalt eine Zeile ist: “Lass /grilling laufen, nutze dabei /domain-modeling.” Am Verhalten ändert sich nichts, aber du kannst die Hälften einzeln benutzen: nur das Verhör? /grilling. Nur Glossar und ADRs pflegen? /domain-modeling. Beides willst du – das ist grill-with-docs.

3. Loslegen: installieren, dann einen Plan hinreichen

Installieren. Es liegt in mattpocock/skills – ein offizieller Befehl, in der Abfrage grill-with-docs ankreuzen:

npx skills@latest add mattpocock/skills

Wegen dieser Aufteilung braucht grill-with-docs jetzt grilling und domain-modeling, um vollständig zu sein, also alle drei ankreuzen (oder gleich die beiden anderen direkt benutzen). Repo schon lokal geklont? Dann reicht es auch, diese Verzeichnisse ins .claude/skills/ deines Projekts zu kopieren.

Füttern. Hör auf mit “Implementier mir X.” Sag stattdessen:

Nimm meinen Plan mit grill-with-docs ins Verhör: <der Plan, den du noch nicht ganz durchdacht hast>

Achtung: Es ist mit disable-model-invocation markiert, taucht also nicht von selbst auf – du musst es beim Namen rufen (oder /grill-with-docs tippen), damit es startet. Dann mach dich bereit: Es stimmt dir nicht zu, es fängt an zu fragen.

Das erste echte Ergebnis ist meist seine erste Frage: etwas, das du längst geklärt glaubtest, und nach einer Frage merkst du, dass du es nicht hattest. Hier ein Lauf, den ich wirklich gemacht habe.

4. Ein echtes Verhör mitansehen

Ich habe ein kleines Projekt aufgesetzt, das es löchern sollte, mit einer absichtlich eingebauten Falle. Das Projekt hatte schon ein CONTEXT.md:

**Cancellation**:
An order is voided in full before shipping; stock returns to inventory as-is. No refund flow is involved.
_Avoid_: Refund, Return

Auch der Code in src/orders.ts spielt mit offenen Karten: cancelOrder() storniert nur ganze Bestellungen, nur vor dem Versand, fasst nie Geld an.

Dann reichte ich ihm den Plan (den vom Anfang): “Nutzer sollen ein paar Artikel aus einer Bestellung stornieren (nicht die ganze), und das Geld für diese Artikel soll zurückgezahlt werden.”

Es las den Code und das Glossar, und seine erste Zeile war nicht “Klar” – sie war:

Bevor wir anfangen, müssen zwei Begriffskonflikte angesprochen werden.

Dein “ein paar Artikel stornieren und zurückzahlen” kollidiert mit zwei bestehenden Definitionen:

CONTEXT.md definiert Cancellation = vollständige Stornierung der Bestellung + kein Rückzahlungsfluss. Du beschreibst eine Teilstornierung, dazu mit Rückzahlung – beides kollidiert.

Die _Avoid_-Liste des Glossars schließt das Wort “Return” ausdrücklich aus.

Die Aktion, die du beschreibst, hat also kein bestehendes Wort. Wir müssen dieses neue Konzept erst benennen, bevor wir weitermachen.

Ich hatte es ehrlich nicht bemerkt: Das “stornieren” in meinem Satz und die im Projekt längst festgenagelte Cancellation waren nicht dasselbe. Es hat das nicht nur erwischt – es ging hin und las den Code:

Das aktuelle cancelOrder in src/orders.ts:3 erlaubt nur Bestellungen mit status === "PLACED". Dein “ein paar Artikel stornieren” – nur vor dem Versand, oder auch danach?

Meine Empfehlung: nur vor dem Versand. Rücksendungen nach dem Versand sind betriebswirtschaftlich ein Return-Prozess, eine Größenordnung komplexer … Bau erst den Pfad vor dem Versand; die Grenze ist da am saubersten.

Ich antwortete “einverstanden, nur vor dem Versand.” Dann tat es etwas Wichtigeres – es benannte das namenlose Konzept und schrieb es direkt ins Glossar:

Partial Cancellation: vor dem Versand werden einige (nicht alle) line items aus einer Bestellung entfernt; der Bestand der entfernten Artikel geht zurück ins Inventar. Kein Rückzahlungsfluss beteiligt. _Avoid_: Partial refund, Partial return, Item cancellation

Diesen Eintrag hat es wirklich in die Datei CONTEXT.md geschrieben, nicht nur im Chat gesagt. Die Rückzahlungshälfte schob es ausdrücklich beiseite: “Die gehört zu Billing – hier nicht eingetragen.”

Während es sich weiter zu den Grenzen vorarbeitete, hielt es inne, um zu entscheiden, ob eine Spur nötig ist, und erzeugte dann tatsächlich ein ADR:

Ein ADR ist gelandet in docs/adr/0001-partial-cancellation-no-refund.md: “Partial Cancellation löst keine Rückzahlung aus; Rückzahlungen bleiben vollständig dem Billing-Kontext überlassen. … Die Alternative wäre gewesen, die Rückzahlung innerhalb von Ordering auszulösen und ‘stornieren + zurückzahlen’ zu einer atomaren Operation zu machen – wir haben sie verworfen, weil sie Ordering von Billings Interna abhängig machen und die bestehende Kontextgrenze brechen würde.”

Das Beste ist seine nächste Frage, die genau das ADR zitierte, das es eben geschrieben hatte:

Frage 3 / Woher weiß Billing, dass zurückgezahlt werden soll? Das aktuelle cancelOrder sendet überhaupt kein Event (src/orders.ts:7).

A. Ein Domain-Event senden; Billing abonniert es und zahlt zurück.

B. Ordering ruft direkt Billings Rückzahlungs-API auf.

C. Nichts senden; den Aufrufer es selbst verdrahten lassen.

Meine Empfehlung: A. Option B macht Ordering direkt von Billing abhängig – genau das, was ADR 0001 verworfen hat.

Lass diese Schleife wirken: Es zwang mich, ein Wort zu schärfen → schrieb es ins Glossar → hielt eine Grenzentscheidung als ADR fest → und nutzte dann dieses ADR, um eine spätere Option zu blockieren, die die Grenze gebrochen hätte. Es benutzt die Sprache, die du gerade gemeinsam mit ihm aufgebaut hast, um jeden folgenden Schritt zu bewachen. Das meint “ein Verhör mit dem Gedächtnis deines Projekts”.

5. Sein Temperament: wann du es einsetzt, wann du es nicht erzwingst

Es ist erfrischend, aber kein Allheilmittel und nicht immer die richtige Wahl:

Es braucht etwas zum Löchern. Mit einem CONTEXT.md und etwas Code hat es Material, an dem es dich festhält und gegen das es prüft. In einem brandneuen, leeren Repo baut es ein Glossar von Grund auf (immer noch nützlich), aber längst nicht so scharf, wie wenn es mit der Sprache löchert, die du schon hast. Am besten also für das Erweitern eines schon erwachsen gewordenen Projekts.
Es schärft Klarheit, keinen Code. Ein Verhör hinterlässt dir geschärfte Begriffe, ein paar ADRs, einen wirklich durchdachten Plan – keine Halde an Implementierung. Code schreiben ist der nächste Schritt, nachdem du klar bist; erwarte nicht, dass es das für dich erledigt.
Löchere nicht das Triviale. Eine Button-Farbe, ein nebensächliches Feld – zwing es durch den Prozess, und es spielt brav mit, reine Verschwendung. Sein Wert liegt da, wo ein schwammiges Wort endlosen Ärger züchtet: Domänenkonzepte, Kontextgrenzen, Stellen, wo sich ein paar Begriffe verheddern. Mit Kanonen auf Spatzen: dem Spatz passiert nichts, du bist erschöpft.
Es ist geizig mit ADRs – das ist ein Vorzug, ärger dich nicht. Es hält eins nur fest, wenn alle drei zutreffen: schwer umkehrbar, später verwirrend, ein echtes Abwägen. Ertappst du dich beim Wunsch, es möge mehr protokollieren, frag dich: Brauchst du die Spur wirklich, oder willst du nur das Ritual der Vollständigkeit? Mehr ADRs sind nicht besser; die festzuhalten, auf die es ankommt, schon.

In einem Satz: Ein komplexes Feature in ein gewachsenes Projekt einbauen, mit dem nagenden Gefühl, dass “manche Wörter für verschiedene Leute Verschiedenes bedeuten” – dann schalt es an. Das ist sein Heimrevier.

6. Spickzettel

Installieren: npx skills@latest add mattpocock/skills   # in der Abfrage grill-with-docs ankreuzen
Verhören:     der KI sagen "Nimm meinen Plan mit grill-with-docs ins Verhör: <Plan>"

Was es tut:
  eine Frage nach der anderen, Empfehlung zuerst
  liest den Code, statt zu fragen, wenn es kann
  hält dich am CONTEXT.md-Glossar fest; stoppt dich, wenn ein Wort nicht passt
  schärft schwammige Wörter ("Account" = Customer oder User?)
  gleicht mit dem Code ab; benennt Abweichungen
  Begriff steht -> direkt ins CONTEXT.md (Glossar, keine Implementierungsdetails)
  schwer umkehrbare Entscheidung -> ein ADR (docs/adr/, nur wenn alle drei Kriterien zutreffen)

CONTEXT.md: nur Glossar -- ein, zwei Zeilen pro Begriff, das zu nutzende Wort + _Avoid_ die zu meidenden
ADR, drei Tests: schwer umkehrbar + ohne Kontext verwirrend + ein echtes Abwägen (eins fehlt, weglassen)

Am besten für: ein komplexes Feature in ein gewachsenes Projekt, wo "manche Wörter für verschiedene Leute Verschiedenes bedeuten"
Spar dir's:    leeres Repo / triviale Änderung / die Erwartung, dass es den Code für dich schreibt

7. Weiterführend

Der Quellcode: grill-with-docs (MIT), dazu die zwei, in die es aufgeteilt wurde, grilling und domain-modeling. Die Format-Leitfäden für Glossar und ADR wohnen jetzt in domain-modeling: CONTEXT.md-Format, ADR-Format – beide einen Blick wert.
Tiefer einsteigen? Schlag im Domain-Driven Design (DDD) die Begriffe ubiquitous language (die durchgängige, von allen geteilte Fachsprache) und ADR (Architecture Decision Record) nach – grill-with-docs ist nur eine leichtgewichtige Hülle, die beides mühelos macht.
Magst du diesen Trick, “mit der KI aus einem anderen Winkel zusammenzuarbeiten”? Letztes Mal haben wir caveman auseinandergenommen (die KI dazu bringen, die Klappe zu halten und nur die Sache zu sagen) – ein perfektes Paar: das eine lässt sie die Floskeln streichen, das andere lässt sie die harten Fragen stellen. Die Serie nimmt weiter andere Skills aus Matts Repo auseinander.

Dieser Artikel ist ein Original-Tutorial von usesuperpowers.com. Der erklärte grill-with-docs-Skill stammt aus mattpocock/skills (source_commit: 6eeb81b) und steht unter dessen MIT-Lizenz. Das gezeigte Verhör ist ein echter Lauf (nebensächliche Details ausgelassen); das Copyright an den zitierten Originalregeln liegt beim ursprünglichen Autor; unsere Analyse, die Demo und der Text sind eigenständig erstellt.

Zur Versionierung: Dieser Artikel basiert auf 6eeb81b. In dieser Version hat Matt das einst einzelne grill-with-docs in zwei Skills aufgeteilt, grilling + domain-modeling, wobei grill-with-docs zum Einstiegspunkt wird, der beide kombiniert; das beschriebene Verhalten und das echte Verhör oben sind davon unberührt – es kommt nur die Schicht “du kannst die Hälften einzeln benutzen” hinzu.