Specs und EARS: vom Kriterium zum Test.

4.1 Warum Specs: gut ist nicht dasselbe wie richtig

Stell dir vor, du gibst einem Coding-Agenten den Auftrag: „Baue einen CSV-Export für die Auftragsliste.“ Nach zwanzig Minuten ist der Build grün, alle Tests laufen, der Code ist sauber strukturiert, der statische Security-Reviewer findet nichts. Ist der Auftrag erfüllt?

Du weißt es nicht. Exportiert die Funktion alle Aufträge oder nur die gefilterten? Komma oder Semikolon als Trennzeichen (in deutschsprachigen Tabellenkalkulationen ein echter Unterschied)? Welche Kodierung? Was passiert bei einer Million Zeilen? Dürfen Techniker exportieren oder nur Disponenten? Was ist mit einem Kundennamen, der mit einem Gleichheitszeichen beginnt und in der Tabellenkalkulation als Formel ausgeführt würde? Der Agent hat jede dieser Fragen irgendwie beantwortet, und zwar stillschweigend. Die Tests, die er mitgeliefert hat, prüfen genau seine eigenen Annahmen. Sie sind grün, weil sie dasselbe Verständnis teilen wie der Code, den sie prüfen.

Das ist der Kern des Problems, und er wird mit Agenten größer, nicht kleiner. Ein menschlicher Entwickler hätte nachgefragt oder wenigstens im Daily erwähnt, dass er sich für das Semikolon entschieden hat. Ein Agent arbeitet in der Fabrik headless: Niemand beantwortet Rückfragen während des Laufs (siehe Kapitel 2). Die Engineering-Guardrails verlangen deshalb ausdrücklich, Annahmen offenzulegen statt zu fragen („surface, don’t ask“). Aber eine offengelegte Annahme ist immer noch eine Annahme, die jemand im Nachhinein prüfen muss.

Zwei Fragen, zwei Werkzeuge

Qualitätssicherung beantwortet zwei verschiedene Fragen, und sie brauchen verschiedene Werkzeuge:

Die Fabrik hat die erste Frage lange sehr gründlich beantwortet: Build-Gate, sechs Reviewer, Architekturregeln, Dependency-Scan. Die Grundsatzentscheidung zu Spec-Driven Development (ADR-0027) beschreibt die Lücke selbst so: Das Quality Gate prüft, ob Code gut ist, nicht, ob er das Richtige tut. Vor Version 0.35 erreichten Akzeptanzkriterien das Quality Gate schlicht nicht; das Feld dafür im Review-Auftrag war fest leer. Die Spec schließt diese Lücke, indem sie das Gewollte in eine Form bringt, die Menschen freigeben und Maschinen prüfen können.

Was eine Spec ist und was nicht

„Spec“ ist ein überladenes Wort. In dieser Academy meinen wir damit, wie die Fabrik, die Produkt-Spec: ein kurzes, versioniertes Dokument, das aus Nutzersicht beschreibt, was ein Feature leisten soll, was ausdrücklich nicht dazugehört und woran man erkennt, dass es fertig ist. Abgrenzung zu benachbarten Artefakten:

Eine Spec ist also kein Lastenheft mit 80 Seiten und kein Ticket mit einem Satz. Eine gute Produkt-Spec passt auf eine bis drei Bildschirmseiten. Sie ist lösungsneutral (sie schreibt nicht vor, welche Klasse den Export erzeugt), aber präzise im Verhalten (sie sagt, welches Trennzeichen gilt).

Warum gerade bei Agenten

• Agenten sind wörtlich. Was nicht dasteht, wird ergänzt, und zwar mit dem statistisch Plausibelsten, nicht mit dem fachlich Richtigen. Eine Spec verschiebt Entscheidungen von „irgendwann im Lauf, implizit“ nach „vorher, explizit, freigegeben“.
• Agenten sind schnell. Wenn Code billig wird, wird die Klarheit darüber, welcher Code entstehen soll, zum Engpass. Eine Stunde Spec-Arbeit spart dann nicht eine Stunde Programmierung, sondern mehrere Korrekturschleifen und Reviews.
• Agenten arbeiten parallel. Wenn drei Child Runs an einem Feature bauen (Kapitel 7), brauchen sie einen gemeinsamen, unveränderlichen Bezugspunkt. Sonst baut jeder gegen seine eigene Interpretation.
• Agenten-Ergebnisse müssen nachweisbar sein. In regulierten Umgebungen reicht „der Build war grün“ nicht. Man muss zeigen können, gegen welche freigegebene Anforderung gebaut und abgenommen wurde (Kapitel 9).

4.2 Aufbau einer Produkt-Spec

Eine Produkt-Spec in der Fabrik ist Markdown mit YAML-Frontmatter. Die Vorlage liegt unter specs/_vorlage/spec.md. Pflicht sind die Abschnitte Ziel, Nicht-Ziele und Akzeptanzkriterien; Kontext, Randfälle und offene Fragen sind optional, aber in der Praxis fast immer hilfreich.

Das Frontmatter

---
id: SPEC-012                 # SPEC-<nnn>, fortlaufend je Projekt
titel: CSV-Export der Wartungsaufträge
version: 1                   # wird von der Fabrik je neuer Fassung erhöht
status: DRAFT                # DRAFT | APPROVED | SUPERSEDED — nur die Fabrik setzt APPROVED
owner: k.berger              # fachlich verantwortlich
contracts: []                # optional: Namen verknüpfter Verträge der Contract Registry
ersetzt: null                # optional: SPEC-<nnn>, die diese Spec ablöst
---

• id ist die stabile Kennung. Sie taucht in jeder AC-ID wieder auf (AC-012-01), in Plänen, Commits und im Audit.
• version und status verwaltet die Fabrik: Jede Änderung erzeugt eine neue Fassung im Status DRAFT; nur die Freigabe durch einen Menschen setzt APPROVED.
• owner ist die fachlich verantwortliche Person, nicht der Agent, der den Text geschrieben hat.
• contracts verknüpft die Spec mit Verträgen der Contract Registry, etwa einer OpenAPI-Beschreibung (Kapitel 7).
• ersetzt verweist auf eine ältere Spec, die diese ablöst, wenn ein Feature grundlegend neu geschnitten wird.

Ziel

Ein bis drei Absätze aus Nutzersicht: Wer bekommt was und warum? Das Ziel ist kein Akzeptanzkriterium, sondern die Begründung, an der man im Zweifel abwägt. Wenn ein Randfall nicht geregelt ist, hilft das Ziel bei der Entscheidung.

Disponenten exportieren die aktuell gefilterte Auftragsliste als CSV, um sie in der Tabellenkalkulation auszuwerten oder an Subunternehmer weiterzugeben. Heute kopieren sie die Liste von Hand aus dem Browser; dabei gehen Umlaute und Spalten verloren.

Nicht-Ziele

Der am meisten unterschätzte Abschnitt. Nicht-Ziele sagen, was die Spec ausdrücklich nicht regelt. Sie verhindern Scope-Creep, und sie machen „ungedecktes Verhalten“ prüfbar: Wenn ein Agent nebenbei einen Excel-Export einbaut, obwohl „kein Excel-Format“ als Nicht-Ziel dasteht, ist das ein klarer Befund und keine Geschmacksfrage. Gute Nicht-Ziele sind konkret und benennen naheliegende Erweiterungen, die man bewusst nicht will:

• Kein Export im Excel-Format (.xlsx).
• Kein zeitgesteuerter oder per E-Mail versendeter Export.
• Kein Import von CSV-Dateien.
• Keine Änderung an der Filterlogik der Auftragsliste.

Kontext

Optional: Ausgangslage, betroffene Module und Dateien, Abhängigkeiten, verknüpfte Verträge. Hier dürfen konkrete Pfade stehen, denn der Kontext hilft dem Agenten, die Stelle im Code zu finden, ohne dass er das Verhalten vorschreibt. Die Fabrik-eigenen Specs nennen dort etwa betroffene Klassen und die nächste freie Migrationsnummer.

Akzeptanzkriterien

Das Herz der Spec. Jedes Kriterium hat eine ID nach dem Schema AC-<nnn>-<nn>, wobei <nnn> die Spec-Nummer ist. IDs sind eindeutig innerhalb der Spec und stabil über Versionen: Ein Kriterium behält seine ID, auch wenn sein Text präzisiert wird. Eine entfernte ID wird nie wiederverwendet, sonst würde ein alter Test plötzlich ein ganz anderes Kriterium „belegen“. Formuliert werden die Kriterien bevorzugt in EARS (Abschnitt 4.4), Given/When/Then ist erlaubt (Abschnitt 4.6).

Randfälle

Grenz- und Negativfälle, die nicht vergessen werden dürfen. Die Vorlage empfiehlt: bei Bedarf als eigenes AC übernehmen. Die Faustregel: Wenn ein Randfall ein beobachtbares Verhalten verlangt, gehört er als AC in die Spec, damit er eine ID bekommt und getestet wird. Wenn er nur ein Hinweis zur Umsetzung ist, darf er hier stehen bleiben.

Offene Fragen

Was noch nicht entschieden ist. Ein Spec-Run schreibt hierher, was er nicht entscheiden kann (Abschnitt 4.10). Die Vorlage sagt unmissverständlich: Eine Spec mit offenen Fragen sollte nicht freigegeben werden. Offene Fragen sind kein Makel; sie sind der ehrlichste Teil eines Entwurfs.

Der Lebenszyklus einer Spec

  anlegen / bearbeiten / Agent ändert specs/…
                 │
                 ▼
            ┌─────────┐   Freigabe (ab MAINTAINER,   ┌──────────┐  neue Fassung   ┌────────────┐
            │  DRAFT  │ ── validiert Pflicht-      ──▶│ APPROVED │ ── freigegeben ─▶│ SUPERSEDED │
            └─────────┘    abschnitte und AC-IDs)     └──────────┘                  └────────────┘
                 ▲                                         │
                 └──── jede Änderung = neue Fassung ◀──────┘   (APPROVED bleibt unverändert)

Drei Regeln folgen daraus. Erstens: Eine freigegebene Fassung ändert sich nie; wer etwas ändern will, erzeugt eine neue Entwurfsfassung. Zweitens: Die Freigabe einer neuen Fassung setzt die bisher freigegebene auf SUPERSEDED. Drittens: Weil jede Fassung einen Inhalts-Hash hat, lässt sich später exakt nachweisen, gegen welchen Text gebaut wurde.

Ein vollständiges Beispiel

Das folgende Beispiel begleitet uns durch das Kapitel. Es ist bewusst realistisch: nicht perfekt, aber freigabefähig.

---
id: SPEC-012
titel: CSV-Export der Wartungsaufträge
version: 3
status: DRAFT
owner: k.berger
contracts: []
ersetzt: null
---

# SPEC-012 — CSV-Export der Wartungsaufträge

## Ziel

Disponenten exportieren die aktuell gefilterte Auftragsliste als CSV, um sie
in der Tabellenkalkulation auszuwerten oder an Subunternehmer weiterzugeben.
Heute kopieren sie die Liste von Hand; dabei gehen Umlaute und Spalten verloren.

## Nicht-Ziele

- Kein Export im Excel-Format (.xlsx).
- Kein zeitgesteuerter oder per E-Mail versendeter Export.
- Kein Import von CSV-Dateien.
- Keine Änderung an der Filterlogik der Auftragsliste.

## Kontext

- Auftragsliste: io.beispiel.maint.auftrag.web.AuftragListeController
- Filter: AuftragFilter (bestehend, unverändert)
- Rollen: ADMIN, DISPONENT (siehe PROJECT.md, Abschnitt Security)

## Akzeptanzkriterien

- **AC-012-01** — Wenn ein Disponent in der Auftragsliste „Als CSV exportieren“
  wählt, dann soll das System eine CSV-Datei mit genau den Aufträgen liefern,
  die dem aktuell gesetzten Filter entsprechen.
- **AC-012-02** — Das System soll CSV-Dateien in UTF-8 mit Byte-Order-Mark,
  Semikolon als Trennzeichen und einer Kopfzeile mit den Spaltennamen erzeugen.
- **AC-012-03** — Falls der Filter mehr als 50 000 Aufträge ergibt, dann soll
  das System den Export ablehnen und die Meldung „Bitte Filter einschränken
  (höchstens 50 000 Zeilen)“ anzeigen.
- **AC-012-04** — Solange ein Export für einen Nutzer läuft, soll das System
  den Export-Knopf für diesen Nutzer deaktivieren.
- **AC-012-05** — Wo das Modul „Kostenstellen“ aktiviert ist, soll das System
  die Spalte „Kostenstelle“ als letzte Spalte in den Export aufnehmen.
- **AC-012-06** — Falls ein Feldinhalt ein Semikolon, ein Anführungszeichen
  oder einen Zeilenumbruch enthält, dann soll das System das Feld in
  Anführungszeichen setzen und enthaltene Anführungszeichen verdoppeln.
- **AC-012-07** — Falls ein Feldinhalt mit =, +, - oder @ beginnt, dann soll
  das System ihm ein Apostroph voranstellen.
- **AC-012-08** — Falls ein Nutzer ohne Rolle DISPONENT oder ADMIN den Export
  aufruft, dann soll das System mit HTTP 403 antworten und keine Auftragsdaten
  ausliefern.

## Randfälle

- Leere Ergebnismenge: Datei mit Kopfzeile und ohne Datenzeilen (AC-012-01).
- Genau 50 000 Aufträge: Export erlaubt (Grenze von AC-012-03).
- Umlaute und Sonderzeichen in Kundennamen (AC-012-02).

## Offene Fragen

- (keine)

Beachte, was hier nicht steht: keine Klasse CsvExportService, keine Bibliothek, kein Streaming-Verfahren. Die Spec beschreibt beobachtbares Verhalten. Wie der Agent es umsetzt, entscheidet er im Rahmen von Projektdefinition, Guardrails und Architekturregeln.

4.3 Was ein gutes Akzeptanzkriterium ausmacht

Bevor wir zur Satzform kommen, lohnt ein Blick auf die Eigenschaften, die ein einzelnes Kriterium haben muss. Die Liste orientiert sich an den Qualitätsmerkmalen, die die Requirements-Engineering-Norm ISO/IEC/IEEE 29148 für einzelne Anforderungen beschreibt, übersetzt in die Praxis mit Agenten:

Wie viele Kriterien?

Es gibt keine Zauberzahl. Als Orientierung: Eine Spec mit zwei Kriterien ist meist zu grob (die Randfälle fehlen), eine mit vierzig ist meist zu breit (eigentlich mehrere Features). Fünf bis fünfzehn Kriterien je Spec sind ein guter Bereich. Wird es mehr, prüfe, ob sich die Spec entlang der Nicht-Ziele teilen lässt. Die Fabrik hat die Frage „eine Spec je Feature oder Epic mit Unter-Specs“ selbst noch als offene Frage geführt; die Empfehlung ihrer Roadmap ist eine Spec je Feature.

Die richtige Flughöhe

Ein Kriterium liegt auf der richtigen Höhe, wenn es von außen beobachtbar ist: über die Oberfläche, eine Schnittstelle, eine Datei, eine Antwort, einen Logeintrag, den jemand sehen soll. „Das System soll den Export über einen Stream erzeugen“ ist zu tief (Implementierung). „Das System soll Disponenten die Arbeit erleichtern“ ist zu hoch (Ziel, nicht prüfbar). „Falls der Filter mehr als 50 000 Aufträge ergibt, dann soll das System den Export ablehnen und die Meldung … anzeigen“ ist genau richtig: Man kann es von außen auslösen und das Ergebnis prüfen.

4.4 EARS: fünf Satzschablonen für präzise Anforderungen

EARS steht für Easy Approach to Requirements Syntax. Alistair Mavin und Kollegen haben die Methode bei Rolls-Royce entwickelt, um Anforderungen an Triebwerkssteuerungen eindeutiger zu machen, und 2009 auf der IEEE International Requirements Engineering Conference vorgestellt. Die Idee ist bestechend einfach: Statt Anforderungen in freier Prosa zu schreiben, verwendet man eine kleine Zahl von Schablonen mit festen Schlüsselwörtern und fester Reihenfolge der Satzteile. Das reduziert typische Probleme natürlicher Sprache (Mehrdeutigkeit, Vagheit, fehlende Bedingungen, Weglassungen), ohne dass man eine formale Sprache lernen muss.

Jede EARS-Anforderung hat dieselbe Grundstruktur:

[Vorbedingung(en)]  [Auslöser]  das <System>  soll  <Reaktion>
     optional         optional     Pflicht      Pflicht   Pflicht

Die Schlüsselwörter zeigen, welcher Satzteil welche Rolle spielt. Daraus ergeben sich fünf Grundmuster. Die Fabrik-Vorlage verwendet deutsche Schablonen, die wir hier übernehmen; daneben steht jeweils das englische Original.

Grafik in voller Größe öffnenGrafik in voller Größe öffnen

1. Allgemein (Ubiquitous)

Anforderungen, die immer gelten, ohne Auslöser und ohne Zustand. Sie beschreiben Invarianten und grundlegende Eigenschaften.

Deutsch:   Das System soll <Reaktion>.
Englisch:  The <system name> shall <system response>.

• AC-012-02 — Das System soll CSV-Dateien in UTF-8 mit Byte-Order-Mark, Semikolon als Trennzeichen und einer Kopfzeile mit den Spaltennamen erzeugen.
• Das System soll jeden Auftrag mit einer eindeutigen, unveränderlichen Auftragsnummer führen.
• Das System soll alle Zeitstempel in der API im Format ISO-8601 mit Zeitzonenangabe ausgeben.
• Aus der Fabrik selbst (AC-001-07): Das System soll freigegebene Versionen unveränderlich halten; eine Änderung erzeugt eine neue Version im Status DRAFT.

Vorsicht: Die allgemeine Schablone ist die bequemste und wird deshalb überbenutzt. Prüfe bei jeder allgemeinen Anforderung, ob sie wirklich immer gilt. Oft versteckt sich eine Bedingung („… wenn der Nutzer angemeldet ist“), und dann ist eine der anderen Schablonen richtig.

2. Ereignisgesteuert (Event-driven)

Anforderungen, die eine Reaktion auf ein Ereignis beschreiben: eine Nutzeraktion, eine eingehende Nachricht, einen Zeitpunkt, ein Signal. Das Ereignis ist ein Moment, kein Dauerzustand.

Deutsch:   Wenn <Auslöser>, dann soll das System <Reaktion>.
Englisch:  When <trigger>, the <system name> shall <system response>.

• AC-012-01 — Wenn ein Disponent in der Auftragsliste „Als CSV exportieren“ wählt, dann soll das System eine CSV-Datei mit genau den Aufträgen liefern, die dem aktuell gesetzten Filter entsprechen.
• Wenn ein Auftrag den Status „Erledigt“ erhält, dann soll das System dem Disponenten des Auftrags eine Benachrichtigung anzeigen.
• Wenn täglich um 02:00 Uhr die Wartungsplanung startet, dann soll das System alle Aufträge mit überschrittenem Fälligkeitsdatum als „überfällig“ markieren.
• Aus der Fabrik (AC-002-02): Wenn ein Run mit Spec-Bezug startet, dann soll das System RUN_SPEC_GEBUNDEN … der zu diesem Zeitpunkt freigegebenen Fassung in die Audit-Kette schreiben.

3. Zustandsgesteuert (State-driven)

Anforderungen, die gelten, solange ein Zustand andauert. Der Unterschied zum Ereignis: Ein Zustand hat eine Dauer, und die Reaktion gilt während der gesamten Dauer.

Deutsch:   Solange <Zustand>, soll das System <Reaktion>.
Englisch:  While <precondition(s)>, the <system name> shall <system response>.

• AC-012-04 — Solange ein Export für einen Nutzer läuft, soll das System den Export-Knopf für diesen Nutzer deaktivieren.
• Solange sich die Anwendung im Wartungsmodus befindet, soll das System schreibende API-Aufrufe mit HTTP 503 beantworten.
• Solange ein Auftrag einem Techniker zugewiesen ist, soll das System die Zuweisung an weitere Techniker verhindern.
• Aus der Fabrik (AC-001-10): Solange ein Projekt im Spec-Modus streng ist, soll das System die Aktivierung eines PlanItems ablehnen, dessen Spec keine freigegebene Version hat.

4. Unerwünschtes Verhalten (Unwanted behaviour)

Anforderungen an den Umgang mit Fehlern, Störungen und unerwünschten Situationen: ungültige Eingaben, fehlende Rechte, Ausfälle, Grenzüberschreitungen, Angriffe. Genau diese Anforderungen fehlen in Freitext-Aufträgen am häufigsten, und genau hier rät ein Agent am meisten.

Deutsch:   Falls <unerwünschte Situation>, dann soll das System <Reaktion>.
Englisch:  If <trigger>, then the <system name> shall <system response>.

• AC-012-03 — Falls der Filter mehr als 50 000 Aufträge ergibt, dann soll das System den Export ablehnen und die Meldung „Bitte Filter einschränken (höchstens 50 000 Zeilen)“ anzeigen.
• AC-012-08 — Falls ein Nutzer ohne Rolle DISPONENT oder ADMIN den Export aufruft, dann soll das System mit HTTP 403 antworten und keine Auftragsdaten ausliefern.
• Falls die Datenbank während eines Exports nicht erreichbar ist, dann soll das System den Export abbrechen, keine unvollständige Datei ausliefern und die Meldung „Export fehlgeschlagen, bitte später erneut versuchen“ anzeigen.
• Aus der Fabrik (AC-001-03): Falls eine Spec doppelte AC-IDs, AC-IDs außerhalb des Schemas oder keinen Abschnitt „Akzeptanzkriterien“ enthält, dann soll das System die Freigabe mit einer verständlichen Validierungsmeldung ablehnen (HTTP 400, kein Serverfehler).

5. Optionales Merkmal (Optional feature)

Anforderungen, die nur gelten, wo ein bestimmtes Merkmal vorhanden ist: ein aktiviertes Modul, eine Produktvariante, eine Lizenzstufe, eine Konfiguration, ein Hardwaremerkmal.

Deutsch:   Wo <Merkmal vorhanden>, soll das System <Reaktion>.
Englisch:  Where <feature is included>, the <system name> shall <system response>.

• AC-012-05 — Wo das Modul „Kostenstellen“ aktiviert ist, soll das System die Spalte „Kostenstelle“ als letzte Spalte in den Export aufnehmen.
• Wo eine Anmeldung über SSO konfiguriert ist, soll das System auf der Login-Seite die Schaltfläche „Mit Firmenkonto anmelden“ anzeigen.
• Wo das Gerät eine Kamera besitzt, soll die App das Erfassen von Fotos zu einem Auftrag anbieten.
• Aus der Fabrik (AC-002-09): Wo das FeatureGate SDD freischaltet, soll das System im Projekt-Assistenten die Wahl des Spec-Modus anbieten und am angelegten Projekt speichern.

Der Unterschied zur zustandsgesteuerten Form: Ein optionales Merkmal ist eine Eigenschaft der Ausprägung des Systems (Konfiguration, Variante), die sich während der Nutzung typischerweise nicht ändert. Ein Zustand ändert sich im Betrieb (Export läuft, Wartungsmodus aktiv).

Kombinierte Formen (Complex)

Reale Anforderungen haben oft mehrere Bedingungen. EARS erlaubt, die Schlüsselwörter zu kombinieren. Die übliche Reihenfolge: optionales Merkmal, dann Zustand, dann Auslöser, dann System und Reaktion.

Englisch:  Where <feature>, while <precondition>, when <trigger>, the <system> shall <response>.
           While <precondition>, if <trigger>, then the <system> shall <response>.

Deutsch:   Solange <Zustand>, wenn <Auslöser>, dann soll das System <Reaktion>.
           Wo <Merkmal>, solange <Zustand>, soll das System <Reaktion>.
           Solange <Zustand>, falls <unerwünschte Situation>, dann soll das System <Reaktion>.

• Solange ein Export für einen Nutzer läuft, wenn derselbe Nutzer die Seite neu lädt, dann soll das System den Fortschritt des laufenden Exports anzeigen, statt einen zweiten Export zu starten.
• Wo das Modul „Kostenstellen“ aktiviert ist, falls einem Auftrag keine Kostenstelle zugeordnet ist, dann soll das System die Spalte „Kostenstelle“ für diesen Auftrag leer lassen.
• Solange sich die Anwendung im Wartungsmodus befindet, wenn ein Administrator sich anmeldet, dann soll das System ihm den vollen Zugriff gewähren.
• Aus der Fabrik (AC-001-01), eine zustandsgesteuerte Anforderung mit zwei verknüpften Bedingungen: Solange softwarefabrik.spec.enabled aus ist oder ein aktives Lizenzsystem den Tier Community meldet, soll das System keine Spec-Oberfläche anbieten …

Kombinierte Formen sind mächtig, aber sie haben einen Preis: Jede zusätzliche Bedingung verdoppelt grob die Zahl der Fälle, die man testen sollte. Wenn ein Satz drei Bedingungen hat, prüfe, ob sich daraus nicht besser zwei oder drei Kriterien machen lassen.

Übersicht

„soll“, „muss“ und das Subjekt

Das englische shall drückt in Anforderungen eine verbindliche Pflicht aus. Die Fabrik-Vorlage übersetzt es mit „soll“, und so ist es in Fabrik-Specs auch gemeint: verbindlich. Wichtig zu wissen: Im deutschsprachigen Requirements Engineering verwenden manche Organisationen eine abgestufte Konvention mit „muss“ (verbindlich), „sollte“ (empfohlen) und „kann“ (optional), etwa nach den Satzschablonen von Chris Rupp. Wenn deine Organisation so arbeitet, entscheide dich bewusst und schreibe die Konvention in die Projektdefinition. Mischen ist der eigentliche Fehler: Eine Spec, in der „soll“ mal verbindlich und mal empfohlen gemeint ist, ist nicht eindeutig.

Das Subjekt ist in der Vorlage „das System“. In größeren Produkten darfst du präziser werden („die Auftrags-API soll …“, „die Web-Oberfläche soll …“), solange klar bleibt, welcher Teil verantwortlich ist. Vermeide dagegen Sätze ohne Subjekt im Passiv („Es soll exportiert werden können“): Dann fehlt, wer was tut.

4.5 Typische Fehler und wie man sie umformuliert

Die meisten schlechten Anforderungen scheitern an einer Handvoll wiederkehrender Muster. Wer sie einmal gesehen hat, findet sie in jedem Ticket. Für jedes Muster: woran man es erkennt, warum es mit Agenten besonders teuer ist, und eine Umformulierung.

Vage Wörter

Erkennungszeichen: schnell, benutzerfreundlich, intuitiv, angemessen, robust, flexibel, modern, sicher, möglichst, gegebenenfalls, in der Regel, usw., etc., und so weiter, ausreichend, zeitnah. Jedes dieser Wörter lädt den Agenten ein, seine eigene Definition einzusetzen, und jede Definition besteht den Test, den er selbst dazu schreibt.

Doppelanforderungen

Erkennungszeichen: zwei unabhängige Reaktionen, verbunden mit „und“, „sowie“, „außerdem“, „/“. Problem: Ein Test kann nur eine davon rot werden lassen, und die Traceability wird unscharf. Wenn ein Commit „Implements: AC-012-09“ trägt, welche Hälfte ist gemeint?

Nicht jedes „und“ ist ein Fehler. „… den Export ablehnen und die Meldung anzeigen“ beschreibt eine zusammengehörige Reaktion auf eine Situation: Ablehnung ohne Meldung wäre unvollständig, Meldung ohne Ablehnung sinnlos. Die Prüffrage lautet: Könnte man die beiden Teile sinnvoll getrennt umsetzen, priorisieren oder testen? Dann trennen.

Selbstkritik am Beispiel: AC-012-02 in der Fassung oben bündelt Kodierung, Byte-Order-Mark, Trennzeichen und Kopfzeile. Das ist grenzwertig. Alle vier Eigenschaften sind Teil von „gültiges CSV für deutschsprachige Tabellenkalkulationen“, aber ein Test für die Kopfzeile sagt nichts über die Kodierung. In einer vierten Fassung würde man die Kopfzeile als eigenes Kriterium führen.

Implementierung statt Verhalten

Erkennungszeichen: Klassen-, Tabellen- oder Bibliotheksnamen, Algorithmen, Datenstrukturen im Kriterium. Problem: Das Kriterium wird wahr, sobald die Technik verwendet wird, unabhängig davon, ob das Verhalten stimmt; und es verbietet bessere Lösungen.

Technische Vorgaben haben trotzdem ihren Platz: projektweit in der Projektdefinition (Technologie- und Architekturpräferenzen), für ein Feature im Abschnitt Kontext der Spec. Dort sind sie Rahmenbedingung, nicht Abnahmekriterium.

Nicht prüfbar

Erkennungszeichen: Negationen ohne Grenze („soll nie abstürzen“), Absolutheiten („alle“, „immer“, „jederzeit“) ohne Bezugsmenge, subjektive Urteile, fehlende Messgröße. Problem: Kein Test kann es bestätigen, also wird es nie belegt, also ist es in der Fabrik ein dauerhafter Befund ohne Lösung.

Weitere häufige Muster

• Versteckte Bedingung. „Das System soll den Export-Knopf deaktivieren.“ Wann? Eine allgemeine Anforderung, die in Wahrheit zustandsgesteuert ist. Umformulierung mit „Solange …“.
• Fehlender Fehlerfall. Zu jedem „Wenn“ gehört die Frage: Was, falls es schiefgeht? Zähle in einer Spec die „Falls“-Kriterien. Sind es null, fehlt mit hoher Wahrscheinlichkeit etwas.
• Pronomen ohne Bezug. „Wenn er den Export startet, soll es ihn benachrichtigen.“ Wer ist er, was ist es, wen benachrichtigt es? Jede Rolle ausschreiben.
• Schwache Modalverben. „Das System kann …“, „sollte nach Möglichkeit …“. Entweder es ist eine Anforderung, dann verbindlich formulieren, oder es ist ein Wunsch, dann gehört es nicht in die Akzeptanzkriterien.
• Lösung im Gewand eines Ziels. „Ziel: Ein Export-Button in der Toolbar.“ Das Ziel nennt die Lösung; das eigentliche Ziel (Daten weitergeben, auswerten) fehlt. Ohne echtes Ziel gibt es keinen Maßstab für Randfälle.
• Widerspruch zu einem Nicht-Ziel. Ein Kriterium verlangt einen E-Mail-Versand, obwohl „kein per E-Mail versendeter Export“ als Nicht-Ziel dasteht. Vor der Freigabe Kriterien und Nicht-Ziele gegeneinander lesen.
• Unbestimmte Mengen und Grenzen. „Bei vielen Aufträgen …“ Wie viele? Und gehört die Grenze dazu oder nicht? „Mehr als 50 000“ ist eindeutig, „ab 50 000“ ist es auch, „bis zu 50 000“ ebenso, aber man muss sich für eines entscheiden.

Checkliste vor der Freigabe

• Jedes Kriterium hat eine ID im Schema AC-<nnn>-<nn> und genau eine Reaktion.
• Jedes Kriterium beginnt mit dem passenden Schlüsselwort (oder ist bewusst allgemein).
• Kein Kriterium enthält vage Wörter, Implementierungsdetails oder unbestimmte Mengen.
• Zu jedem Ereignis ist mindestens ein Fehlerfall bedacht.
• Jede Grenze ist eindeutig (inklusiv oder exklusiv).
• Kriterien und Nicht-Ziele widersprechen sich nicht.
• Zu jedem Kriterium kannst du in einem Satz einen Testfall nennen.
• Der Abschnitt „Offene Fragen“ ist leer oder enthält nur Fragen, die bewusst nach der Freigabe geklärt werden.

4.6 Given/When/Then als Alternative

Given/When/Then (deutsch oft Angenommen/Wenn/Dann) stammt aus dem Behaviour-Driven Development und ist durch die Sprache Gherkin bekannt geworden, die Werkzeuge wie Cucumber ausführen. Statt einer allgemeinen Regel beschreibt Given/When/Then ein konkretes Beispiel: Ausgangslage, Aktion, erwartetes Ergebnis.

Given  ein Disponent hat die Auftragsliste auf Status „Offen“ gefiltert
  And  der Filter ergibt 3 Aufträge
When   er „Als CSV exportieren“ wählt
Then   erhält er eine Datei mit einer Kopfzeile und 3 Datenzeilen
  And  jede Datenzeile hat den Status „Offen“

EARS und Given/When/Then im Vergleich

Beide Formen schließen sich nicht aus. Eine bewährte Praxis: die Regel in EARS als Akzeptanzkriterium, und zwei oder drei Given/When/Then-Beispiele als Testfälle oder als Randfälle darunter. Die Fabrik-Vorlage erlaubt Given/When/Then direkt als Kriterium:

- **AC-012-09** — *Given* ein Auftrag mit dem Kunden „Müller; Söhne“ *When* er
  exportiert wird *Then* steht im Feld Kunde der Wert "Müller; Söhne" in
  Anführungszeichen.

Szenario-Tabellen

Gherkin kennt Szenario-Vorlagen mit Beispieltabellen (Scenario Outline mit Examples). Sie eignen sich hervorragend für Grenzwerte, weil sie die Äquivalenzklassen sichtbar machen:

Scenario Outline: Obergrenze des Exports (AC-012-03)
  Given der Filter ergibt <anzahl> Aufträge
  When  ein Disponent „Als CSV exportieren“ wählt
  Then  ist das Ergebnis <ergebnis>

  Examples:
    | anzahl | ergebnis                           |
    | 0      | Datei mit Kopfzeile, ohne Daten    |
    | 49999  | Datei mit 49999 Datenzeilen        |
    | 50000  | Datei mit 50000 Datenzeilen        |
    | 50001  | Ablehnung mit Meldung              |

4.7 Von Akzeptanzkriterien zu Tests

Ein Akzeptanzkriterium ist ein Versprechen. Ein Test ist der Beleg, dass es gehalten wird, und zwar nicht einmal, sondern bei jedem Build. Die Grundregel ist einfach: Jedes Akzeptanzkriterium wird durch mindestens einen Test belegt, und dieser Test nennt die AC-ID. In der Praxis reicht ein Test fast nie. Ein gutes Kriterium braucht:

• mindestens einen positiven Test, der zeigt, dass die geforderte Reaktion eintritt;
• mindestens einen negativen Test, der zeigt, dass die Reaktion nicht eintritt, wenn die Bedingung nicht erfüllt ist;
• Grenzfalltests, wo das Kriterium eine Grenze enthält (Mengen, Längen, Zeiten, Zustandswechsel).

Warum der negative Test so wichtig ist: Eine Implementierung, die den Export-Knopf immer deaktiviert, besteht den positiven Test von AC-012-04 („solange ein Export läuft, ist der Knopf deaktiviert“) problemlos. Erst der negative Test („läuft kein Export, ist der Knopf aktiv“) entlarvt sie. Agenten erzeugen solche zu breiten Lösungen nicht aus Bosheit, sondern weil der positive Test das einzige Signal war, das sie hatten.

Testfälle systematisch ableiten

Zwei klassische Techniken des Testentwurfs passen perfekt zu EARS:

• Äquivalenzklassen: Teile die möglichen Eingaben in Klassen, für die das System gleich reagieren soll, und teste je Klasse einen Vertreter. Für AC-012-03: „0 Aufträge“, „1 bis 50 000“, „mehr als 50 000“.
• Grenzwertanalyse: Fehler sitzen an den Rändern. Teste die Werte direkt an und neben jeder Grenze: 49 999, 50 000, 50 001. Ein „größer“ statt „größer gleich“ im Code fällt nur so auf.

Jede EARS-Form legt außerdem eine bestimmte Teststrategie nahe:

Die AC-ID im Test

Damit Menschen und Werkzeuge erkennen, welcher Test welches Kriterium belegt, nennt der Test die AC-ID. Drei Stellen haben sich bewährt, und die Fabrik-Vorlage nennt alle drei: im Testnamen, in einer Annotation wie @Spec("AC-012-03") oder in einem Kommentar. Wähle in deinem Projekt eine Konvention und halte sie ein; schreibe sie in die Projektdefinition oder ins Projekt-Memory, damit auch der Agent sie kennt.

In Java gibt es keine Standard-Annotation dafür. Lege sie einmal im Testcode an:

package io.beispiel.maint.testsupport;

import java.lang.annotation.*;

/** Verknüpft einen Test mit Akzeptanzkriterien einer Produkt-Spec. */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
@Documented
public @interface Spec {
    /** AC-IDs, z. B. "AC-012-03". */
    String[] value();
}

Beispiel in Java mit JUnit 5

package io.beispiel.maint.auftrag.export;

import io.beispiel.maint.testsupport.Spec;
import org.junit.jupiter.api.*;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import static org.assertj.core.api.Assertions.*;

@DisplayName("SPEC-012 CSV-Export")
class AuftragCsvExportTest {

    private final AuftragTestdaten daten = new AuftragTestdaten();
    private final AuftragCsvExport export = new AuftragCsvExport(daten.repository());

    // AC-012-03: Obergrenze 50 000 Zeilen — Grenzwerte an und neben der Grenze
    @Spec("AC-012-03")
    @ParameterizedTest(name = "AC-012-03: {0} Aufträge → erlaubt = {1}")
    @CsvSource({ "0, true", "49999, true", "50000, true", "50001, false" })
    void ac_012_03_obergrenze(int anzahl, boolean erlaubt) {
        var filter = daten.filterMitTreffern(anzahl);

        if (erlaubt) {
            assertThat(export.erzeuge(filter).datenzeilen()).hasSize(anzahl);
        } else {
            assertThatThrownBy(() -> export.erzeuge(filter))
                .isInstanceOf(ExportZuGrossException.class)
                .hasMessage("Bitte Filter einschränken (höchstens 50 000 Zeilen)");
        }
    }

    // AC-012-06: Maskierung — positiv (Sonderzeichen) und negativ (normales Feld)
    @Test
    @Spec("AC-012-06")
    @DisplayName("AC-012-06: Feld mit Semikolon und Anführungszeichen wird maskiert")
    void ac_012_06_maskiert_sonderzeichen() {
        daten.auftragMitKunde("Müller; \"Söhne\"");
        var zeile = export.erzeuge(daten.filterAlle()).datenzeilen().getFirst();
        assertThat(zeile).contains("\"Müller; \"\"Söhne\"\"\"");
    }

    @Test
    @Spec("AC-012-06")
    @DisplayName("AC-012-06: Feld ohne Sonderzeichen bleibt unverändert")
    void ac_012_06_normales_feld_unveraendert() {
        daten.auftragMitKunde("Meier GmbH");
        var zeile = export.erzeuge(daten.filterAlle()).datenzeilen().getFirst();
        assertThat(zeile).contains(";Meier GmbH;").doesNotContain("\"Meier GmbH\"");
    }

    // AC-012-07: Formel-Injection — alle vier Startzeichen und ein harmloser Fall
    @Spec("AC-012-07")
    @ParameterizedTest(name = "AC-012-07: \"{0}\" → \"{1}\"")
    @CsvSource(delimiter = '|', quoteCharacter = '"', value = {
        "=SUMME(A1)|'=SUMME(A1)", "+49 123|'+49 123", "-5|'-5", "@cmd|'@cmd", "Kunde A|Kunde A" })
    void ac_012_07_formel_injection(String eingabe, String erwartet) {
        assertThat(AuftragCsvExport.zelle(eingabe)).isEqualTo(erwartet);
    }
}

Beachte zwei Details. Erstens taucht die AC-ID dreifach auf; das ist bewusst redundant, damit sie in Testberichten (über den Anzeigenamen), in der Code-Suche (über die Annotation) und beim Lesen (über den Kommentar) sofort sichtbar ist. Zweitens deckt der Test für AC-012-07 auch den harmlosen Fall ab: Ohne ihn bestünde eine Implementierung, die jedem Feld ein Apostroph voranstellt.

Beispiel in TypeScript mit Vitest

Für die Oberfläche, etwa das zustandsgesteuerte AC-012-04, eignet sich ein Komponententest. In TypeScript-Testframeworks wie Vitest oder Jest trägt man die AC-ID am einfachsten in die Beschreibung von describe und it:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { ExportButton } from './ExportButton';

// SPEC-012, AC-012-04: Solange ein Export für einen Nutzer läuft,
// soll das System den Export-Knopf für diesen Nutzer deaktivieren.
describe('AC-012-04 Export-Knopf während eines laufenden Exports', () => {
  it('AC-012-04: ist deaktiviert, solange ein Export läuft', () => {
    render(<ExportButton exportLaeuft={true} />);
    expect(screen.getByRole('button', { name: 'Als CSV exportieren' })).toBeDisabled();
  });

  it('AC-012-04: ist aktiv, wenn kein Export läuft', () => {
    render(<ExportButton exportLaeuft={false} />);
    expect(screen.getByRole('button', { name: 'Als CSV exportieren' })).toBeEnabled();
  });

  it('AC-012-04: wird wieder aktiv, sobald der Export endet', () => {
    const { rerender } = render(<ExportButton exportLaeuft={true} />);
    rerender(<ExportButton exportLaeuft={false} />);
    expect(screen.getByRole('button', { name: 'Als CSV exportieren' })).toBeEnabled();
  });
});

Und in Python?

Mit pytest funktioniert dasselbe Muster: AC-ID im Kommentar oder Docstring und in der Testbezeichnung, zum Beispiel über die ids einer Parametrisierung. Wer eine Annotation möchte, kann eine eigene pytest-Markierung registrieren (etwa @pytest.mark.spec("AC-012-03")); ein Kommentar mit der ID sollte trotzdem dabeistehen, damit auch einfache Textsuchen sie finden.

import pytest

# AC-012-03: Obergrenze 50 000 Zeilen
@pytest.mark.parametrize(
    "anzahl, erlaubt",
    [(0, True), (49_999, True), (50_000, True), (50_001, False)],
    ids=["AC-012-03 leer", "AC-012-03 knapp darunter", "AC-012-03 Grenze", "AC-012-03 darüber"],
)
def test_ac_012_03_obergrenze(export, filter_mit_treffern, anzahl, erlaubt):
    ...

Auf welcher Ebene testen?

Nicht jedes Kriterium braucht einen End-to-End-Test. Wähle die niedrigste Ebene, auf der das Kriterium noch vollständig prüfbar ist: Maskierungsregeln (AC-012-06, AC-012-07) als schnelle Unit-Tests, die Rechteprüfung (AC-012-08) als Integrationstest gegen den Web-Endpunkt, den Zustand des Knopfes (AC-012-04) als Komponententest. Ein einzelner End-to-End-Test für den Hauptablauf (AC-012-01) sichert zusätzlich, dass die Teile zusammenspielen.

Wenn sich kein Test schreiben lässt

Fällt dir zu einem Kriterium kein Test ein, ist fast immer das Kriterium das Problem, nicht der Test. Gehe zurück zu Abschnitt 4.5: Meist steckt ein vages Wort, eine fehlende Grenze oder eine Doppelanforderung darin. Die Umkehrung gilt ebenso und ist ein starkes Werkzeug beim Schreiben: Formuliere zu jedem Kriterium sofort einen Testfall in einem Satz. Gelingt das nicht, ist das Kriterium noch nicht fertig.

4.8 Traceability: von der Anforderung bis zum Commit

Traceability (Rückverfolgbarkeit) heißt: Zu jeder Codeänderung lässt sich sagen, welche Anforderung sie umsetzt, und zu jeder Anforderung, welche Änderungen und Tests zu ihr gehören. Das klingt nach Bürokratie, ist aber die Grundlage für drei sehr praktische Dinge: Impact-Analyse (was ist betroffen, wenn sich AC-012-03 ändert?), Review (passt dieser Diff zu dem, was er umsetzen soll?) und Nachweis (gegen welche Anforderung wurde gebaut und abgenommen?).

Grafik in voller Größe öffnenGrafik in voller Größe öffnen

IDs statt Texte

Traceability über Texte funktioniert nicht: Texte werden präzisiert, umformuliert, übersetzt. Die Fabrik verfolgt deshalb konsequent IDs (ADR-0027, Entscheidung E6). Die AC-ID ist der Faden, der durch alle Artefakte läuft:

SPEC-012 v3 (APPROVED, sha256 …)
   └─ AC-012-03 ─┬─ Plan:     plans/0007-csv-export.md      (Spec: SPEC-012 / AC: AC-012-01, AC-012-03)
                 ├─ Backlog:  Eintrag mit Spec- und AC-Bezug
                 ├─ Run:      RUN_SPEC_GEBUNDEN spec=SPEC-012;version=3;hash=…;ac=AC-012-01,AC-012-03
                 ├─ Commit:   Implements: AC-012-01, AC-012-03
                 ├─ Test:     @Spec("AC-012-03") ac_012_03_obergrenze
                 ├─ Review:   Akzeptanzkriterien im Review-Auftrag aller Reviewer
                 └─ Trace:    Warum-Trace des Runs zeigt Spec, Version, Hash, AC-IDs

Commit-Trailer

Git kennt Trailer: Zeilen der Form Schlüssel: Wert im letzten Absatz einer Commit-Nachricht. Bekannte Beispiele sind Signed-off-by: oder Co-authored-by:. Werkzeuge wie git interpret-trailers oder git log --format='%(trailers)' lesen sie maschinell aus. Für SDD verwendet die Fabrik zwei Trailer:

feat(export): CSV-Export der gefilterten Auftragsliste

Liefert die gefilterte Auftragsliste als CSV (UTF-8, Semikolon) und lehnt
Exporte über 50 000 Zeilen mit einer verständlichen Meldung ab.

Spec: SPEC-012
Implements: AC-012-01, AC-012-03

Damit lässt sich jederzeit fragen: Welche Commits implementieren AC-012-03? Ein git log --grep="AC-012-03" genügt für den Anfang.

4.9 Spec-Drift: wenn Spec, Plan und Code auseinanderlaufen

Spec-Drift ist die Abweichung zwischen Spec, Plan und Code. Sie entsteht auf zwei Wegen:

• Die Spec ändert sich, die Arbeit nicht. Ein Kriterium wird präzisiert oder gestrichen, während ein Backlog-Eintrag oder ein laufender Task noch gegen die alte Fassung geplant ist. Wer jetzt baut, baut gegen eine Anforderung, die nicht mehr gilt.
• Der Code ändert sich, die Spec nicht. Ein Bugfix, eine „kleine“ Erweiterung, eine Optimierung verändert beobachtbares Verhalten, ohne dass jemand die Spec anpasst. Die Spec lügt dann leise, und die nächste Person (oder der nächste Agent), die sich auf sie verlässt, baut auf Sand.

Gegen den zweiten Weg hilft vor allem Disziplin: Erst die Spec ändern, dann den Code. Eine Verhaltensänderung beginnt mit einer neuen Entwurfsfassung, wird freigegeben und dann umgesetzt. Die Hinweise auf „ungedecktes Verhalten“ (Abschnitt 4.7) machen Verstöße sichtbar. Gegen den ersten Weg hilft Technik: Wenn jede Arbeit an eine bestimmte Fassung gebunden ist und Fassungen auf AC-Ebene vergleichbar sind, kann ein System berechnen, welche Arbeit durch eine Änderung veraltet.

Was „geändert“ bedeutet

Ein Vergleich auf AC-Ebene unterscheidet drei Fälle: Ein Kriterium ist neu (keine bestehende Arbeit ist betroffen, aber jemand muss es umsetzen), entfernt (Arbeit, die es umsetzt, ist überflüssig oder sogar schädlich) oder geändert (Arbeit muss geprüft und vielleicht angepasst werden). Weil IDs stabil bleiben und nie wiederverwendet werden, ist dieser Vergleich eindeutig.

4.10 Specs erarbeiten: allein, im Team, mit dem Agenten

Eine Spec entsteht selten in einem Zug. Bewährt hat sich ein Vorgehen in vier Schritten:

1. Ziel und Nicht-Ziele zuerst. Zwei Absätze Ziel, drei bis sechs Nicht-Ziele. Wer hier keine Einigkeit hat, braucht über Kriterien noch nicht zu reden.
2. Hauptablauf als Kriterien. Die ereignisgesteuerten Kriterien des Normalfalls („Wenn …, dann …“).
3. Systematisch nach Fehlern und Zuständen fragen. Für jedes Ereignis: Was, falls die Eingabe ungültig ist, die Rolle fehlt, eine Grenze überschritten wird, eine Abhängigkeit ausfällt? Welche Zustände beeinflussen das Verhalten? Welche Varianten gibt es? Daraus entstehen die „Falls“-, „Solange“- und „Wo“-Kriterien.
4. Gegenlesen mit Testbrille. Zu jedem Kriterium einen Testfall in einem Satz. Was sich nicht testen lässt, wird umformuliert. Was offen ist, wandert in „Offene Fragen“.

Gerade Schritt 3 ist eine Stärke von Sprachmodellen: Sie sind gut darin, zu einer Regel Randfälle aufzuzählen, an die man selbst nicht gedacht hat. Ihre Schwäche ist, dass sie plausible, aber falsche Entscheidungen treffen, wenn man sie entscheiden lässt. Die richtige Arbeitsteilung ist deshalb: Der Agent schlägt vor und fragt, der Mensch entscheidet und gibt frei.

Reverse-Spec: Specs für bestehenden Code

Bei bestehenden Systemen gibt es oft keine Spec, aber Code und Tests, die das Verhalten implizit festlegen. Eine Reverse-Spec leitet daraus einen Entwurf ab. Der Wert liegt weniger im fertigen Text als in den Fragen, die dabei auftauchen: Ist dieses Verhalten gewollt oder ein Fehler? Ein Reverse-Spec-Entwurf muss deshalb Annahmen, Nicht-Ziele und offene Fragen ausdrücklich kennzeichnen. Ihn ungeprüft freizugeben hieße, den Ist-Zustand samt seiner Fehler zur Anforderung zu erklären.

Zusammenfassung

• Tests und Reviews prüfen, ob Code gut ist. Ob er das Richtige tut, lässt sich nur gegen eine vereinbarte, prüfbare Beschreibung prüfen: die Spec.
• Eine Produkt-Spec hat Frontmatter, Ziel, Nicht-Ziele und Akzeptanzkriterien mit stabilen IDs AC-<nnn>-<nn>; Kontext, Randfälle und offene Fragen ergänzen sie. Lebenszyklus: DRAFT → APPROVED → SUPERSEDED, freigegebene Fassungen sind unveränderlich.
• EARS kennt fünf Schablonen: allgemein (Das System soll), ereignisgesteuert (Wenn), zustandsgesteuert (Solange), unerwünscht (Falls … dann), optional (Wo), dazu kombinierte Formen.
• Vage Wörter, Doppelanforderungen, Implementierung statt Verhalten und nicht prüfbare Aussagen sind die häufigsten Fehler; jede hat eine Standard-Umformulierung.
• Given/When/Then beschreibt Beispiele; es ergänzt EARS, vor allem für Abläufe und Grenzwerttabellen.
• Jedes Kriterium braucht positive, negative und Grenzfalltests, die die AC-ID im Namen, in einer Annotation oder im Kommentar tragen.
• Die Fabrik verfolgt AC-IDs vom Plan über die Bindung (RUN_SPEC_GEBUNDEN), den Objective-Kopf und die Commit-Trailer bis in den Warum-Trace; seit v0.38.0 prüft spec-conformance die Abdeckung, und Spec-Drift markiert veraltete Arbeit.
• Specs schreiben Menschen und Agenten gemeinsam; freigeben (ab MAINTAINER) immer ein Mensch.

Kapitelfragen

1. Ein Agent liefert einen grünen Build, 95 % Testabdeckung und keine Befunde der statischen Reviewer. Warum ist damit nicht gezeigt, dass er den Auftrag erfüllt hat?

   Musterantwort

   Build, Abdeckung und Reviewer beantworten die Verifikationsfrage: Ist der Code gut? Ob er das Richtige tut (Validierung), lässt sich nur gegen eine vereinbarte Beschreibung des Gewollten prüfen. Die Tests stammen vom selben Agenten und prüfen dessen eigene Annahmen; sie sind grün, weil sie dasselbe Verständnis teilen wie der Code. Erst Akzeptanzkriterien mit IDs, die ein Mensch freigegeben hat, und Tests, die genau diese Kriterien belegen, schließen die Lücke.

2. Welche drei Abschnitte einer Produkt-Spec sind in der Fabrik Pflicht, und warum sind die Nicht-Ziele mehr als eine Formalie?

   Musterantwort

   Pflicht sind Ziel, Nicht-Ziele und Akzeptanzkriterien. Nicht-Ziele grenzen den Umfang ab, verhindern Scope-Creep und machen ungedecktes Verhalten prüfbar: Baut ein Agent etwas, das ausdrücklich als Nicht-Ziel genannt ist, ist das ein eindeutiger Befund statt einer Geschmacksfrage. Außerdem verhindern sie, dass ein Agent „hilfreich“ naheliegende Erweiterungen ergänzt, die niemand bestellt hat.

3. Ordne zu: „Solange der Wartungsmodus aktiv ist …“, „Wo das Modul Kostenstellen aktiviert ist …“, „Falls die Datenbank nicht erreichbar ist …“, „Wenn ein Auftrag erledigt wird …“. Worin unterscheiden sich Zustand und optionales Merkmal?

   Musterantwort

   Zustandsgesteuert, optional, unerwünscht, ereignisgesteuert. Ein Zustand ändert sich im laufenden Betrieb und hat eine Dauer (Wartungsmodus ein/aus). Ein optionales Merkmal beschreibt die Ausprägung des Systems, also Konfiguration, Variante, Modul oder Lizenzstufe, und ändert sich während der Nutzung typischerweise nicht. Entsprechend testet man Zustände mit Übergängen hinein und heraus, optionale Merkmale mit und ohne das Merkmal.

4. Formuliere um: „Der Upload soll schnell und zuverlässig funktionieren und große Dateien angemessen behandeln.“ Welche Fehlermuster stecken darin?

   Musterantwort

   Vage Wörter (schnell, zuverlässig, groß, angemessen) und eine Dreifachanforderung. Umformulierung zum Beispiel: „Wenn ein Nutzer eine Datei bis 10 MB hochlädt, dann soll das System den Upload innerhalb von 5 Sekunden bestätigen.“ – „Falls ein Upload durch einen Verbindungsabbruch unvollständig ist, dann soll das System keine Teildatei speichern und die Meldung … anzeigen.“ – „Falls eine Datei größer als 10 MB ist, dann soll das System den Upload ablehnen und die Meldung ‚Datei zu groß (höchstens 10 MB)‘ anzeigen.“ Die konkreten Werte sind Annahmen und gehören bis zur Klärung in die offenen Fragen.

5. Warum reicht für AC-012-04 („Solange ein Export läuft, soll das System den Export-Knopf deaktivieren“) ein einzelner positiver Test nicht aus? Welche Tests gehören dazu?

   Musterantwort

   Eine Implementierung, die den Knopf immer deaktiviert, bestünde den positiven Test. Nötig sind: Knopf deaktiviert, solange ein Export läuft (positiv); Knopf aktiv, wenn kein Export läuft (negativ); Knopf wird wieder aktiv, wenn der Export endet (Übergang). Bei „für diesen Nutzer“ zusätzlich: Ein Export von Nutzer A deaktiviert den Knopf von Nutzer B nicht.

6. Warum dürfen AC-IDs nach dem Entfernen eines Kriteriums nie wiederverwendet werden?

   Musterantwort

   Tests, Commits (Implements:), Backlog-Einträge, Audit-Ereignisse und Warum-Traces verweisen über die ID auf das Kriterium. Würde die ID für ein neues Kriterium wiederverwendet, belegte ein alter Test plötzlich ein ganz anderes Kriterium, und historische Nachweise würden ihren Sinn verändern. Stabile, nie wiederverwendete IDs machen außerdem den Vergleich zweier Fassungen (neu, entfernt, geändert) und die Drift-Erkennung eindeutig.

7. Ein Agent hat in einem Build-Run die Datei specs/SPEC-012-csv-export/spec.md geändert und ein Kriterium „präzisiert“. Was passiert in der Fabrik mit dieser Änderung, und was musst du tun?

   Musterantwort

   Die Fabrik übernimmt die Änderung nach dem Build als neue Entwurfsfassung (DRAFT), niemals als Freigabe; die freigegebene Fassung bleibt unverändert und gilt weiter für gebundene Runs. Du prüfst den Entwurf, am besten mit dem Vergleich zur freigegebenen Fassung, und entscheidest: freigeben (ab MAINTAINER), überarbeiten oder verwerfen. Ein Agent kann eine Spec nie selbst freigeben.

8. Dein Projekt steht im Spec-Modus LEICHT. Ein Backlog-Eintrag verweist auf SPEC-012, die aber nur als Entwurf existiert. Was passiert beim Aktivieren, und was wäre in STRENG anders?

   Musterantwort

   In LEICHT zeigt das Backlog einen Hinweis, der Build-Run startet trotzdem, aber ohne Spec-Bindung: RUN_SPEC_GEBUNDEN entfällt, im Run-Log steht ein Hinweis, und der Agent bekommt keinen Objective-Kopf mit gebundenen Kriterien. In STRENG lehnt die Fabrik die Aktivierung ab, weil eine freigegebene Spec Startbedingung ist.

9. Drei Child Runs eines Workflows bauen an SPEC-012. Während der zweite läuft, gibt jemand Fassung 4 frei. Gegen welche Fassung arbeiten die Child Runs, und warum ist das so gewollt? Was ändert sich durch die Spec-Drift-Erkennung (seit v0.38.0)?

   Musterantwort

   Alle Child Runs arbeiten gegen die Fassung, die beim Start am Task gebunden wurde; die Fabrik garantiert, dass alle Child Runs eines Workflows dieselbe gebundene Fassung erhalten, auch wenn die Spec zwischenzeitlich neu freigegeben wurde. Sonst würden parallele Agenten gegen unterschiedliche Anforderungen bauen und das Integrationsergebnis wäre widersprüchlich. Seit v0.38.0 vergleicht die Fabrik Fassung 4 auf AC-Ebene mit Fassung 3, schreibt SPEC_DRIFT in die Audit-Kette, markiert offene Backlog-Einträge, die an geänderte oder entfernte Kriterien gebunden sind, als veraltet und setzt daran gebundene, nicht abgeschlossene Tasks auf WAITING_FOR_REPLAN. Dann entscheidet ein Mensch über Neuplanung.

10. Transfer: Du übernimmst ein bestehendes Repository ohne Specs und willst auf STRENG umstellen. Wie gehst du vor, und welche Gefahr birgt eine Reverse-Spec?

    Musterantwort

    Repo importieren, Spec-Modus zunächst auf LEICHT. Für die wichtigsten Bereiche Specs erarbeiten: von Hand, mit einem normalen Run, der unter specs/ schreibt, oder mit einer Reverse-Spec (seit v0.38.0), die aus Code und Tests einen Entwurf ableitet. Jeden Entwurf fachlich prüfen: Ist das beschriebene Verhalten gewollt oder ein Fehler? Annahmen und offene Fragen klären, dann freigeben. Bestehende Tests nach und nach mit AC-IDs versehen. Erst wenn die relevanten Bereiche freigegebene Specs haben, auf STRENG umstellen. Die Gefahr der Reverse-Spec: Sie beschreibt den Ist-Zustand samt seiner Fehler. Ungeprüft freigegeben, würden Fehler zur Anforderung erklärt. Deshalb kennzeichnet sie Annahmen ausdrücklich und wird nie automatisch freigegeben.