Funktionsspezifikationen schreiben

Funktionsspezifikationen machen vereinbartes Produktverhalten zu einer dauerhaften Referenz für Coding-Agenten, Prüfer und unabhängige Verifikation. Sie sollten präzise genug zum Testen und zugleich für Product Engineer und relevante fachliche Stakeholder verständlich sein.

Verantwortliche Rolle: Product Engineer.
Teilnehmer: Fachliche Stakeholder für Domänenentscheidungen; Architekt oder UX-Designer für relevante Beschränkungen.
Eingaben: Ziele, Discovery-Notizen, bestehende Spezifikationen, relevante Geschäftsrichtlinien, freigegebene Architektur- und Gestaltungsvorgaben.
Ergebnisse: Eingecheckte Funktionsspezifikation oder freigegebene Änderung einer bestehenden Funktionsspezifikation mit ausdrücklich benannten offenen Entscheidungen.

Der Product Engineer kann Funktionsspezifikationen mithilfe dialogbasierter KI erstellen und verfeinern. Ausgehend von geprüften Discovery-Notizen, bestehenden Produktspezifikationen und geltenden Unternehmensbeschränkungen beschreibt er das beabsichtigte Verhalten und bittet den Assistenten, es als lesbares, testbares Markdown-Funktionsdokument zu strukturieren.

Dies ist ein iterativer Analyseprozess. Der Assistent kann einen Hauptablauf vorschlagen, Rollen und Zustandsübergänge aufzählen, Fehlerfälle identifizieren und nach fehlenden Geschäftsregeln fragen. Der Product Engineer sollte den Entwurf aktiv hinterfragen: Stimmen die Akteure? Werden Annahmen als Tatsachen dargestellt? Sind Ausnahmefälle wesentlich? Sind Berechtigungen und negative Ergebnisse spezifiziert? Kann ein unabhängiger Prüfer aus jeder Akzeptanzbedingung beobachtbare Tests ableiten?

Eine plausible KI-Antwort ist keine freigegebene Geschäftsentscheidung. Zeigt der Assistent eine offene Richtlinienfrage auf, holt der Product Engineer eine Entscheidung beim Verantwortlichen ein und übernimmt sie in die Spezifikation. Der Agent darf keine Regel erfinden, nur damit das Dokument vollständig wirkt.

Nach der Prüfung wird die akzeptierte Spezifikation im versionierten specs/-Bestand des Projekts eingecheckt. Dieses Dokument, nicht das Gesprächsprotokoll, dient als Referenz für Implementierung und unabhängige Verifikation. Ändert Stakeholder-Feedback akzeptiertes Verhalten, aktualisiert der Product Engineer die relevante Spezifikation und ihre Akzeptanzbedingungen.

1. Kontext bereitstellen. Liefern Sie Produktziele, relevante bestehende Spezifikationen, Stakeholder-Entscheidungen, geltende Geschäftsrichtlinien und bekannte technische Grenzen. Geben Sie keine unzulässigen oder unnötigen sensiblen Daten weiter.
2. Analyse vor endgültiger Formulierung verlangen. Lassen Sie Akteure, Abläufe, Geschäftsregeln, Grenzfälle, Annahmen und offene Fragen aufzählen.
3. Folgenreiche Fragen klären. Nutzen Sie die Fragen des Assistenten, um erforderliche Stakeholder-Entscheidungen zu erkennen. Dokumentieren Sie akzeptierte Antworten und kennzeichnen Sie offene Punkte eindeutig.
4. Markdown-Funktionsentwurf erzeugen. Nehmen Sie eine stabile Kennung, Zweck, Akteure/Berechtigungen, Verhalten, Regeln/Ausnahmen und passende beobachtbare Akzeptanzbedingungen auf.
5. Entwurf prüfen und hinterfragen. Vergleichen Sie ihn mit den Ausgangsentscheidungen und dem aktuellen Produktverhalten. Entfernen Sie erfundene Annahmen, willkürliche Implementierungsvorgaben, Redundanz sowie unmögliche oder vage Akzeptanzbedingungen.
6. Vereinbarte Spezifikation einchecken. Speichern Sie sie in specs/ und nutzen Sie die Repository-Historie statt paralleler versionierter Kopien.
7. Während der Iteration pflegen. Aktualisieren Sie akzeptiertes Verhalten und Akzeptanzprüfungen, wenn Stakeholder-Feedback oder freigegebene Entscheidungen das verlangte Produktverhalten ändern.

Erste Aussage eines Stakeholders:

„Prüfende sollen Anträge ablehnen können.“

Ein dialogbasierter Assistent könnte fragen, ob ein Grund erforderlich ist, ob jede prüfende Person jeden Antrag ablehnen darf, ob Selbstprüfung erlaubt ist und ob Antragstellende die Entscheidung sehen können.

Nachdem der Stakeholder die Regeln entschieden hat, hält der Product Engineer beobachtbares Verhalten fest, etwa:

„Eine autorisierte prüfende Person darf einen offenen Antrag nur nach Eingabe eines nichtleeren Grundes ablehnen. Die Entscheidung erfasst die prüfende Person und den Zeitpunkt; Antragstellende können Ergebnis und Grund ihres eigenen Antrags sehen. Antragstellende dürfen ihre eigene Einreichung nicht prüfen.“

Dieses Beispiel zeigt Analyse und Klärung statt KI-bestimmter Richtlinien. Die Spezifikation kann anschließend getrennte Akzeptanzbedingungen für einen leeren Grund, unautorisierte Aktionen, Selbstprüfung und Sichtbarkeit für Antragstellende enthalten.

1. Eine zusammenhängende Funktionsgrenze wählen. Eine Funktion sollte sinnvolles Benutzer- oder Systemverhalten darstellen. Vermeiden Sie eine einzige riesige Produktspezifikation, sobald sie schwer wartbar wird; zerlegen Sie einen einfachen Ablauf aber nicht in eine eigene Datei je Feld oder Button.

2. Zweck und Akteure benennen. Erklären Sie, wer die Funktion benötigt, welches Ergebnis sie unterstützt, wer sie verwenden darf und welche wesentlichen Ausschlüsse gelten. Verweisen Sie bei Bedarf auf übergeordnete Projektziele.

3. Erwartetes Verhalten beschreiben. Formulieren Sie den Hauptablauf anhand beobachtbarer Ergebnisse statt einer vorgestellten Quellcodestruktur. Spezifizieren Sie gegebenenfalls Eingaben, Validierungen, Zustandsänderungen, Rückmeldungen und Ausgaben.

4. Regeln und Ausnahmen bestimmen. Berücksichtigen Sie Berechtigungen, Zulässigkeit, Grenzen, Ablehnungs- oder Fehlerfälle sowie Verhalten bei nicht verfügbaren Daten oder externen Abhängigkeiten. Verändert eine Ausnahme die Abnahme wesentlich, gehört sie in die Spezifikation.

5. Akzeptanzbedingungen ergänzen. Schreiben Sie Prüfungen, die durch Beobachtung oder Test beurteilt werden können. Nehmen Sie repräsentative positive und negative Bedingungen auf. Vermeiden Sie Aussagen wie „funktioniert perfekt“ oder „hat eine intuitive Oberfläche“ ohne konkreten Kontext.

6. Unsicherheit klären und dokumentieren. Kennzeichnen Sie wichtige offene Fragen und holen Sie Entscheidungen autorisierter Stakeholder ein. Machen Sie eine Vermutung des Agenten nicht zur akzeptierten Geschäftsregel. Wird trotz einer unkritischen offenen Frage weitergearbeitet, kennzeichnen Sie die Annahme als vorläufig.

7. Auf Konsistenz prüfen. Gleichen Sie die Spezifikation mit verwandten Funktionen, freigegebenen Sicherheits- und Technikbeschränkungen, Begriffen und bestehendem Verhalten ab. Verweisen Sie auf gemeinsame Regeln, statt sie widersprüchlich zu wiederholen.

8. Während der Iteration pflegen. Checken Sie die Spezifikation als Teil des dauerhaften Projektbestands ein. Ändern Stakeholder akzeptiertes Verhalten, aktualisieren Sie den entsprechenden Text und die Akzeptanzbedingungen vor oder zusammen mit der Implementierung. Bewahren Sie die Historie in der Versionskontrolle, statt verwirrende parallele Kopien anzulegen.

Unklar: „Prüfer sollten Anfragen einfach ablehnen können.“

Besser: „Ein autorisierter Prüfer kann eine offene Anfrage erst nach Eingabe einer Begründung ablehnen. Die Anfrage wechselt zu Abgelehnt, erfasst Prüfer und Entscheidungszeitpunkt und zeigt dem Antragsteller die Begründung. Ein Benutzer ohne Prüfberechtigung kann die Aktion nicht ausführen.“

Dieses Beispiel schreibt keine bestimmte Oberfläche vor. Es spezifiziert sinnvolles Verhalten, das implementiert und verifiziert werden kann.

Stabile Kennung und Titel; Zweck; Umfang und Ausschlüsse; Akteure und Berechtigungen; Voraussetzungen; Hauptverhalten; Geschäftsregeln; Ausnahmen; Akzeptanzbedingungen; Abhängigkeiten; Querverweise und offene Entscheidungen. Dies ist eine Ausgangsstruktur, keine Anweisung, nutzlose Abschnitte auszufüllen.

Eine Funktionsspezifikation ist bereit, die Implementierung zu leiten, wenn der Product Engineer und die relevanten Stakeholder ihre folgenreichen Geschäftsregeln bestätigt haben, das beabsichtigte Verhalten für einen Coding-Agenten ausreichend klar implementierbar ist, ohne Richtlinien zu erfinden, und ein unabhängiger Prüfer sinnvolle beobachtbare Prüfungen ableiten kann. Akzeptierte Spezifikationen bleiben versioniert und werden aktualisiert, wenn sich das vereinbarte Verhalten ändert. KI-gestütztes Entwerfen unterstützt diese Arbeit, ersetzt aber niemals menschliche Prüfung und verbindliche Produktentscheidungen.

Implementierungscode als Anforderungen tarnen; bereits andernorts verbindlich dokumentierte Unternehmensregeln wiederholen; kosmetische Details überspezifizieren; Berechtigungs- oder Fehlerverhalten vollständig implizit lassen; und funktionierenden Code zur einzigen verlässlichen Aussage über erwartetes Verhalten werden lassen.