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

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