Material: Teil 20. Anti-Patterns SDD

Lektion 1 von 5 im Modul «Teil 20. Anti-Patterns SDD»

Sie sehen die Lektion ohne Anmeldung an. Anmelden, um Ihren Fortschritt zu speichern und Tests zu absolvieren.

Quelle

Teil 20. SDD-Antipatterns

Ein Antipattern ist eine Gewohnheit, die wie ein korrekter Prozess aussieht, aber das Ergebnis zerstört. Bei SDD sind solche Fehler besonders heimtückisch: Die Dateien existieren, die Prüfungen existieren, der Agent arbeitet schnell, aber der Mensch verliert nach und nach die Kontrolle.

Dieser Teil dient als diagnostische Karte. Wenn der Prozess schwerfällig, laut oder nutzlos geworden ist, fangen Sie hier an.

Spezifikation nach dem Code

Symptom: Der Agent implementiert zuerst ein Feature und schreibt dann requirements.md, plan.md und validation.md für den bereits fertigen Code.

Warum schlecht: Die Spezifikation hört auf, die Arbeit zu steuern, und wird zu einem Bericht. In diesem Modus schützt sie nicht vor überflüssigen Entscheidungen des Agents.

Wie beheben:

vor der Implementierung mindestens eine Entwurfsspezifikation committen;
dem Agenten verbieten, Produktcode in der Sitzung zur Erstellung der Spezifikation zu schreiben;
im Merge-Request explizit den Commit der Spezifikation vor dem Commit der Implementierung zeigen.

Riesiges `requirements.md`

Symptom: Eine einzelne Anforderungsdatei enthält Dutzende Punkte, mehrere Szenarien, zukünftige Phasen und umstrittene Entscheidungen.

Warum schlecht: Der Agent fängt an auszuwählen, was als wichtig gilt. Auch der Mensch hört auf, die Grenzen zu sehen.

Wie beheben:

das Feature in Phasen aufteilen;

zukünftige Ideen nach roadmap.md auslagern;
in requirements.md nur das belassen, was für den aktuellen Branch benötigt wird;
umstrittene Entscheidungen als Fragen markieren, nicht als Anforderungen.

`validation.md`, das niemand ausgeführt hat

Symptom: In der Prüfung gibt es schöne Fakten, aber keine Spuren ihrer Ausführung.

Warum schlecht: Eine solche Datei erzeugt ein falsches Gefühl der Fertigkeit. Sie sieht streng aus, lässt aber den Branch nicht zum Merge zu.

Wie beheben:

neben jedem obligatorischen Fakt einen Befehl oder manuelles Szenario speichern;
im Bericht des Agents eine Liste der bestandenen, durchgefallenen und ungeprüften Fakten verlangen;
einen Fakt nicht als bestätigt betrachten, wenn er nicht reproduzierbar ist.

Abschwächung von Fakten nach einem Fehler

Symptom: Ein Test fällt durch, danach ändert der Agent das erwartete Ergebnis in validation.md, nicht den Code.

Warum schlecht: Der Prozess fängt an, die Implementierung des Agents zu schützen, nicht die Produktabsicht.

Wie beheben:

den Agenten zuerst bitten, die Abweichung ohne Korrekturen zu zeigen;
Änderungen an validation.md besonders aufmerksam zu reviewen;
den Grund für die Änderung eines Fakts in der Spezifikation oder im Merge-Request speichern;
das Löschen obligatorischer Fakten ohne menschliche Entscheidung verbieten.

Rituelles `/clear`

Symptom: /clear wird zwischen Phasen aufgerufen, aber danach erhält der Agent trotzdem eine lange Erklärung aus dem Chat.

Warum schlecht: Der Befehl erzeugt den Anschein einer Überprüfung der Übertragbarkeit. Tatsächlich hängt der Prozess weiterhin vom Gedächtnis des Menschen ab.

Wie beheben:

nach /clear dem Agenten nur Dateireferenzen geben;
prüfen, ob eine neue Sitzung die nächste Aufgabe aus dem Repository verstehen kann;
wenn nicht, Spezifikationen ergänzen, nicht den Prompt erweitern.

Skill als Zauberknopf

Symptom: Das Team ruft den Skill Qwen Code auf, aber niemand liest SKILL.md und versteht nicht, welche Entscheidungen er trifft.

Warum schlecht: Der Skill wird zu einem versteckten Prozess. Bei einem Ausfall wissen die Menschen nicht, was zu korrigieren ist.

Wie beheben:

projektspezifische Skills im Repository speichern;
SKILL.md wie Prozesscode reviewen;
im Skill nicht nur Befehle, sondern auch Einschränkungen schreiben;
keinen Skill vor 2–3 Wiederholungen des manuellen Prozesses erstellen.

`QWEN.md` als Müllhalde

Symptom: In QWEN.md werden Produktanforderungen, Stack, persönliche Präferenzen, temporäre Aufgaben und Fehlernotizen abgelegt.

Warum schlecht: Der Agent hört auf, dauerhafte Regeln vom temporären Kontext zu unterscheiden.

Wie beheben:

Produktentscheidungen in specs/ speichern;

Agent-Verhaltensregeln in QWEN.md speichern;
temporäre Erkenntnisse in den Speicher oder die Retrospektive überführen;
veraltete Regeln regelmäßig löschen.

Hook, der heimlich das Projekt ändert

Symptom: Ein Hook formatiert, überschreibt oder löscht Dateien ohne expliziten Schritt im Plan.

Warum schlecht: Ein Teil der Änderungen entsteht außerhalb der Kontrolle des Agents und des Menschen. Später ist es schwer zu verstehen, wer das Verhalten geändert hat.

Wie beheben:

Hooks sollten standardmäßig prüfen oder loggen, nicht Dateien ändern;
automatische Formatierung nur als explizite Befehlsregel erlauben;
alle Dateiänderungen müssen im normalen git diff landen;
bei einer Blockade muss der Hook den Grund erklären.

Speicher als versteckte Wahrheitsquelle

Symptom: Der Agent trifft Entscheidungen auf Basis des Speichers, aber diese Entscheidungen existieren nicht in specs/, QWEN.md oder AGENTS.md.

Warum schlecht: Ein neues Teammitglied sieht die Grundlage der Entscheidung nicht. Ein anderer Agent erhält sie möglicherweise auch nicht.

Wie beheben:

den Speicher als Hinweis, nicht als Regel betrachten;
wiederkehrende Erkenntnisse in reviewbare Dateien überführen;
veralteten Speicher löschen;
im Konflikt zwischen Speicher und Spezifikation die Spezifikation wählen.

MCP ohne Aufgabe

Symptom: Mehrere MCP-Server werden zum Projekt „für die Zukunft" angebunden.

Warum schlecht: Der Agent erhält überflüssige Befugnisse und mehr Möglichkeiten, Fehler zu machen. Das Team hört auf zu verstehen, welche externen Aktionen überhaupt möglich sind.

Wie beheben:

MCP nur für ein konkretes Szenario anbinden;
die Werkzeugliste einschränken;
die Konfiguration an einem reviewbaren Ort speichern;
experimentelle Server nach der Prüfung deaktivieren.

Zu großer MVP

Symptom: Die erste funktionierende Version umfasst Autorisierung, Rollen, Analytik, schöne Benutzeroberfläche, Migrationen, Datenimport und Integrationen.

Warum schlecht: Der Agent erstellt schnell viele Dateien, aber der Mensch schafft es nicht, die Qualität der Entscheidungen zu verstehen.

Wie beheben:

die erste Phase muss ein einziges Risiko beweisen;
die Arbeit zeitlich begrenzen;
zum letzten grünen Zustand zurückkehren, wenn der Branch ausgeufert ist;
Features nur nach Fakten hinzufügen, die bereits prüfbar sind.

Halluzinationen im Agent-Code

Symptom: Der Agent verweist selbstbewusst auf eine Funktion, Methode oder ein Paket, die nicht existieren. Der Import zeigt auf ein nicht existierendes Modul; der Aufruf verwendet eine API, die erst in der nächsten Major-Version erschien; in package.json wird eine Abhängigkeit hinzugefügt, die es im Registry nicht gibt oder die fast wie ein Bekannter heißt (zum Beispiel requests-py statt requests).

Warum schlecht: Halluzinierte Imports können in der Typ-Phase nicht fallen, wenn der Agent selbst eine Stub hinzugefügt hat. Besonders gefährlich sind nicht existierende Paketnamen: Ein Angreifer kann einen solchen Namen vorab im Registry registrieren (Attacke slopsquatting), und npm install zieht stillschweigend schädlichen Code heran.

Wie beheben:

eine Liste erlaubter Abhängigkeiten in tech-stack.md führen;
jede Abhängigkeitshinzufügung als separater Review-Schritt behandeln, nicht als Teil von „implementiere Feature“;
beim ersten Typ- oder Laufzeitfehler die Paketversion mit package.json abgleichen;
vor npm install den Paketnamen mit eigenen Augen prüfen; ein Name, der sich vom Gewohnten um einen Buchstaben unterscheidet, ist ein Stoppsignal;
wenn der Agent auf eine Funktion verweist, die es vorher im Code nicht gab, eine Referenz verlangen: „zeige die Definition oder sage, wo sie erscheinen soll".

Test-Illusionen

Symptom: npm test ist grün, aber der Bug bleibt. Es gibt Tests, aber sie prüfen nicht das, was behauptet wird.

Typische Unterarten:

tautologischer Test: Der Test vergleicht das Ergebnis einer Funktion mit dem gleichen Ausdruck wie in der Funktion — eine Umbenennung der Variable zerstört alles, aber die Logik wird nie geprüft;
Test-Spiegel: Der Test prüft, dass die Funktion das zurückgibt, was sie zurückgab, ohne unabhängigen Erwartungswert;
Täuschung durch Snapshot: Der erste Lauf erzeugt einen Snapshot, der zweite vergleicht mit ihm selbst; der Fehler wird im Snapshot festgehalten und gilt als „richtig“;
Test, der bei jedem Fehler nicht fällt: Die einzige Behauptung ist, dass die Funktion keine Ausnahme geworfen hat.

Warum schlecht: Die grüne Testsuite hört auf, ein Fakt der Fertigkeit zu sein. Die Spezifikation ist formal erfüllt („90% Abdeckung“), aber es gibt keine echten Garantien.

Wie beheben:

in validation.md einen Fakt-Repro verlangen: einen Befehl, der vor dem Fix fällt und danach besteht (besonders für Bugfixes, siehe Teil 11);
beim Review die Tests selbst lesen, nicht nur die Abdeckungszahl;

für kritische Stellen Mutation-Testing anwenden (für Vitest gibt es Stryker): Der Service führt kleine Änderungen im Code ein und prüft, ob die Tests sie bemerken. Wenn keine Mutation gefangen wird, prüfen die Tests nichts;
Snapshots für Geschäftslogik verbieten; Snapshots sind nur dort erlaubt, wo das Ergebnis ein menschenlesbares Rendering ist.

Entwickler versteht seinen PR nicht

Symptom: Der Autor öffnet einen Merge-Request, kann aber nicht erklären, warum eine konkrete Entscheidung getroffen wurde; auf die Frage des Reviewers fragt er erneut den Agenten und leitet die Antwort weiter.

Warum schlecht: Die Verantwortung für den Code wird verwässert. In einem halben Jahr wird niemand im Team sagen können, warum hier genau diese Fehlerbehandlung ist und ob es eine bewusste Wahl war. Wenn der Autor seinen PR nicht versteht, kann der Reviewer nicht auf sein Urteil bauen, und der zukünftige Leser wird in Hypothesen irren.

Wie beheben:

eine Regel einführen: Der PR-Autor muss in der Beschreibung in einem Absatz mit eigenen Worten erklären, was und warum gemacht wurde (siehe Vorlage in Anhang C);

der Reviewer stellt mindestens eine Frage, auf die nur der Mensch eine Antwort hat („warum ist hier das Lesen aus der Datenbank außerhalb der Transaktion?"); wenn der Autor nicht antwortet oder mit einem Chat-Auszug antwortet, wird der PR zur Überarbeitung zurückgegeben;
im Team das Muster „Paar-SDD" fördern: Einer schreibt die Spezifikation, der zweite reviewed sie vor der Implementierung (Teil 22, Paar-Prüfung);
für sich selbst — nach dem Merge git diff nochmals durchlesen und laut formulieren: „ich habe X gemacht, weil Y". Wenn es sich nicht erklären lässt, im nächsten Feature vom Agenten nicht nur Code, sondern auch eine Erklärung in den PR-Kommentaren verlangen.