Auf dieser Seite
Spezifikationen, gegen die sich prüfen lässt
Viele der teuersten Fehler entstehen vor der ersten Zeile Code. Eine Anforderung wird anders verstanden, als sie gemeint war, und das fällt auf, wenn die Umsetzung fertig ist. Mit KI-Agenten verschärft sich das. Ein Agent setzt eine missverstandene Aufgabe schnell, vollständig und überzeugend um.
Ich schreibe deshalb vor jeder nennenswerten Umsetzung eine kurze Spezifikation. Sie ist kein Pflichtenheft. Sie ist eine Seite, die sich lesen lässt, bevor die Arbeit beginnt.
Fünf Abschnitte unter einem Titel
Als Beispiel eine Aufgabe aus einer fiktiven Bibliothekssoftware:
# Alle Ausleihen auf einmal verlängern
## Ziel
Im Konto lassen sich alle laufenden Ausleihen in einem Schritt verlängern.
## Nicht Teil dieser Aufgabe
- Verlängerung von Fernleihen
- Änderungen an den Mahngebühren
## Verhalten
- Die Verlängerung beachtet die Höchstzahl an Verlängerungen je Medium.
- Ist ein Medium vorgemerkt oder die Höchstzahl erreicht, bleibt sein
Rückgabedatum unverändert, und ein Hinweis nennt den Titel und den Grund.
- Fernleihen werden übersprungen und im Hinweis genannt.
## Akzeptanzkriterien
- [ ] Zwei Bücher ohne Vormerkung, Höchstzahl nicht erreicht: Beide haben danach
ein neues Rückgabedatum.
- [ ] Drei Bücher, eines vorgemerkt, eines mit erreichter Höchstzahl: Das dritte
erhält ein neues Rückgabedatum. Der Hinweis nennt die beiden anderen Titel
mit ihrem Grund, ihre Daten bleiben.
- [ ] Keine Ausleihe lässt sich verlängern: Kein Datum ändert sich, der Hinweis
nennt alle Titel und Gründe.
- [ ] Eine Fernleihe ist dabei: Sie wird übersprungen und im Hinweis genannt.
- [ ] Tastatur: Die Verlängerung lässt sich allein mit der Tastatur auslösen.
## Offene Fragen
- Gilt die neue Leihfrist ab heute oder ab dem bisherigen Rückgabedatum?
- Lassen sich überfällige Ausleihen mitverlängern?
„Nicht Teil” ist der wichtigste Abschnitt
Was nicht gebaut wird, steht selten in einer Anforderung. Genau dort entstehen Missverständnisse. Ein Mensch lässt Naheliegendes weg, weil niemand danach gefragt hat. Ein Agent baut es mit, weil es sinnvoll erscheint.
Der Abschnitt begrenzt die Aufgabe. Jeder Punkt darin ist eine Entscheidung. Ausgeschlossen heißt trotzdem nicht unbestimmt. Fernleihen werden nicht verlängert, aber übersprungen und genannt. Was noch niemand entschieden hat, steht unter den offenen Fragen.
Akzeptanzkriterien als prüfbare Aussagen
„Die Funktion soll benutzerfreundlich sein” lässt sich nicht prüfen. „Die Verlängerung lässt sich allein mit der Tastatur auslösen” schon.
Jedes Akzeptanzkriterium ist so formuliert, dass es sich eindeutig mit Ja oder Nein prüfen lässt. Aus diesen Aussagen entstehen die Tests, und zwar vor der Umsetzung. Tests, die erst aus dem fertigen Code abgeleitet werden, prüfen nur, was der Code ohnehin tut. Was sich nicht sinnvoll automatisieren lässt, wird von Hand geprüft, aber gegen dieselbe Aussage. Die wichtigsten Kriterien sind oft die, in denen mehrere Regeln zusammentreffen.
Offene Fragen ausschreiben
Beim Schreiben fällt auf, was unklar ist. Statt eine Annahme zu treffen, steht die Frage in der Spezifikation. Sie geht an die Person, die die Anforderung gestellt hat, bevor gebaut wird. Im Beispiel hängt sogar ein Akzeptanzkriterium daran: Welches Datum nach dem Verlängern „neu” ist, entscheidet die Antwort auf die erste Frage. Bis dahin lässt sich das Kriterium nicht eindeutig prüfen. Die Umsetzung beginnt deshalb erst mit der Antwort.
Das ist der Punkt, an dem sich die Zeit für die Spezifikation auszahlt. Eine Frage vor der Umsetzung kostet eine Nachricht. Dieselbe Frage danach kostet einen Umbau.
Gegen die Quelle prüfen
Eine Spezifikation kann selbst falsch sein. Ich gleiche sie deshalb mit dem ab, woraus sie entstanden ist: mit dem Ticket, den Kommentaren, dem Entwurf der Oberfläche.
Diesen Abgleich lasse ich auch einen Agenten durchführen, mit einer einfachen Frage: Steht in der Spezifikation etwas, das die Quelle nicht hergibt, oder fehlt etwas, das die Quelle verlangt? Die Antwort lese ich selbst.
Wie lang
Eine Seite. Wird sie länger, ist die Aufgabe meist zu groß und sollte geteilt werden. Für eine kleine Korrektur genügen ein, zwei Sätze im Ticket; die volle Form lohnt sich, sobald mehr als eine Entscheidung offen ist. Zwei kleine Aufgaben mit je einer Seite sind leichter umzusetzen, zu prüfen und zurückzunehmen als eine große.
Was die Spezifikation nicht ist
- Kein Entwurf der Lösung. Sie beschreibt Verhalten, nicht Klassen. Hinweise zur Umsetzung stehen dort nur, wo eine Vorgabe besteht.
- Nicht festgeschrieben. Zeigt die Umsetzung, dass eine Annahme falsch war, ändere ich die Spezifikation in Absprache mit der Person, die die Anforderung gestellt hat.
- Kein Ersatz für das Gespräch. Sie ist dessen Ergebnis.
Nach der Umsetzung
Die Spezifikation ist der Maßstab für die Prüfung. Jedes Akzeptanzkriterium wird abgehakt. Lässt sich eines nicht erfüllen, entscheidet die Person, die die Anforderung gestellt hat, ob es entfällt oder sich ändert. Die Begründung steht in der Spezifikation. Die Beschreibung des Pull Requests entsteht aus ihr, sodass im Review ohne Rückfrage verständlich ist, was die Änderung bezweckt.
Danach hat sie ihren Zweck erfüllt. Ich pflege sie nicht als dauerhafte Dokumentation weiter, denn eine Spezifikation, die niemand nachführt, widerspricht bald dem Code. Was dauerhaft gelten soll, wandert in Tests und in die Leitfäden.
Unabhängig von KI
Diese Arbeitsweise ist nicht neu und nicht an Agenten gebunden. Gute Teams haben immer geklärt, was gebaut wird, bevor sie bauen. Agenten machen nur sichtbarer, was das Weglassen kostet.
Den Zusammenhang beschreibt Vom Prompt zum Pull Request, meine Arbeitsweise der Abschnitt agentische Entwicklung.
Thema für Ihr Projekt?
Passende Leistung: Agentische Entwicklung einführen. Schildern Sie mir kurz, worum es geht. Ich melde mich mit einer ersten Einschätzung.
Projekt anfragen