Spezifikationen schreiben

Sie schreiben eine Spezifikation selten von einer leeren Seite. Sie beschreiben eine Änderung in natürlicher Sprache, /opsx:propose entwirft die Anforderungen und Szenarien, und dann verfeinern Sie diese. Diese Seite behandelt diesen letzten Schritt — wie „gut“ aussieht und wie Sie die KI dorthin steuern.

Es ist das Begleitdokument zu Überprüfen einer Änderung: Beim Überprüfen geht es darum, Schwachstellen im Entwurf zu finden; beim Schreiben geht es darum zu wissen, woraus ein starker Entwurf besteht.

Eine Spezifikation beschreibt Verhalten, nicht Code

Eine Spezifikation sagt, was Ihr System tut, in Begriffen, die jeder überprüfen kann — nicht, wie es gebaut ist. Sie besteht aus Anforderungen (Aussagen über das Verhalten) und Szenarien (konkreten Beispielen, die sie belegen).

### Anforderung: Sitzungstimeout
Das System MUSS eine Sitzung nach 30 Minuten Inaktivität ablaufen lassen.

#### Szenario: Inaktivitäts-Timeout
- GEGEBEN sei eine authentifizierte Sitzung
- WENN 30 Minuten ohne Aktivität vergehen
- DANN wird die Sitzung ungültig gemacht und der Benutzer muss sich erneut authentifizieren

Behalten Sie das Wie — die Warteschlange, die Bibliothek, das Tabellenschema — in design.md oder im Code. Wenn Verhalten und Implementierung in einer Anforderung gemischt werden, hört die Anforderung auf, testbar zu sein, und beginnt sofort zu veralten, sobald sich der Code ändert.

Was eine gute Anforderung ausmacht

Eine gute Anforderung beschreibt ein einzelnes Verhalten so klar, dass Sie es jemand anderem zur Überprüfung geben könnten.

• Eine Aussage, ein MUSS/SOLL. Wenn eine Anforderung drei „und außerdem“-Klauseln enthält, sind es eigentlich drei Anforderungen. Teilen Sie sie auf.

• Beobachtbar. Jemand außerhalb des Codes sollte feststellen können, ob sie erfüllt ist. „Das System MUSS einen Fehlerbanner anzeigen, wenn der Upload 10 MB überschreitet“ ist beobachtbar. „Das System MUSS große Uploads angemessen verarbeiten“ ist es nicht.

• Die richtige Stärke. OpenSpec verwendet die RFC-2119-Schlüsselwörter, und sie haben unterschiedliche Bedeutungen:

  Schlüsselwort	Bedeutung
  MUST / SHALL	Eine zwingende Anforderung. Nicht verhandelbar.
  SHOULD	Eine starke Empfehlung, mit Raum für eine begründete Ausnahme.
  MAY	Echte Optionality.

  Greifen Sie standardmäßig zu MUST/SHALL. Verwenden Sie SHOULD nur, wenn Sie wirklich meinen „es sei denn, es gibt einen guten Grund dagegen“.

Der Test für eine Anforderung: Könnte ein Tester, der den Code noch nie gesehen hat, feststellen, ob er bestanden wurde? Wenn nicht, muss sie geschärft werden.

Was ein gutes Szenario ausmacht

Szenarien sind der Ort, an dem eine Anforderung ihren Wert beweist. Jedes davon ist ein konkretes GEGEBEN/WENN/DANN, das zu einem automatisierten Test werden könnte.

• Es übt seine Anforderung aus. Ein Szenario, das die Anforderung nur in anderen Worten wiederholt, testet nichts. Machen Sie daraus eine spezifische Situation mit einem spezifischen Ergebnis.
• Abdecken Sie die Fälle, die wichtig sind, nicht nur den Happy Path. Der gültige Login ist einfach. Die leere Eingabe, das abgelaufene Token, der zweite Klick, das, was schiefgeht — dort leben Bugs, und dort ist ein Szenario am wertvollsten.
• Nennen Sie den Fall im Titel. „Szenario: Ablehnung eines abgelaufenen Tokens“ sagt einem Prüfer auf einen Blick, was abgedeckt ist; „Szenario: Test 2“ nicht.

Eine nützliche Gewohnheit: Fragen Sie vor der Genehmigung Welcher einzelne Fall würde mich am meisten ärgern, wenn er fehlschlägt? — und stellen Sie sicher, dass ein Szenario ihn benennt.

Wählen Sie die richtige Art von Delta

Eine Änderung beschreibt ihre Bearbeitungen der Spezifikationen mit drei Abschnittstypen. Die richtige Verwendung hält Ihre archivierten Spezifikationen ehrlich:

• ## ADDED Requirements — völlig neues Verhalten, das vorher nicht existierte.
• ## MODIFIED Requirements — Verhalten, das bereits existierte und sich ändert. Fügen Sie die vollständige neue Version ein; eine kurze Notiz zur Änderung hilft dem Prüfer.
• ## REMOVED Requirements — verschwindendes Verhalten, mit einer Zeile zur Begründung.

Beim Archivieren wird ADDED an die Hauptspezifikation angehängt, MODIFIED ersetzt die alte Version, und REMOVED wird daraus entfernt. Entfernen Sie die letzte Anforderung einer Fähigkeit, und Sie ruhen sie aus: Anstatt eine Spezifikation leer zurückzulassen, löscht das Archiv openspec/specs/<capability>/spec.md. Da dies der einzige Archivierungsschritt ist, der eine Datei entfernt, muss er explizit angefordert werden — fügen Sie retire_capabilities: true zur .openspec.yaml der Änderung hinzu, neben dem schema:, das diese Datei bereits benötigt. Ohne diese Einstellung bricht das Archiv ab und teilt dies mit. Das Ruhenlassen löscht die gesamte Datei, daher wird es auch abgelehnt, während die Spezifikation etwas außerhalb ihres Titels, ## Purpose und ihrer Anforderungsblöcke enthält — einen ## Notes-Abschnitt, einen Kommentar unter einer Anforderung. Der Abbruch benennt diese Zeilen; verschieben Sie sie in ## Purpose oder eine Anforderung, oder löschen Sie die Spezifikation manuell. Für eine Spezifikation im Checkout des Aufrufers benennt die Archivausgabe auch den git checkout, der eine commitete Datei wiederherstellt; ausgewählte Speicher erhalten stattdessen checkout-bezogene Wiederherstellungshinweise. Wenn Sie eine echte Änderung als ADDED markieren, haben Sie zwei konkurrierende Anforderungen; wenn Sie neues Verhalten als MODIFIED beschreiben, gibt es nichts zum Ersetzen. Im Zweifel öffnen Sie die aktuelle Spezifikation und prüfen, ob die Anforderung bereits vorhanden ist.

Ein weiterer Abschnitt ist es wert, bekannt zu sein. Wenn Ihr Delta eine Fähigkeit erstellt, die noch nicht existiert, öffnen Sie ihn mit ## Purpose — ein Satz oder zwei darüber, wofür die Fähigkeit gedacht ist. Das Archiv verwendet dies als Zweck der Hauptspezifikation, die es erstellt; überspringen Sie ihn, und Sie erhalten einen TBD-Platzhalter, den Sie manuell ausfüllen müssen. Eine vorhandene Spezifikation hat bereits einen Zweck, daher wird der eines Deltas dort ignoriert — bearbeiten Sie openspec/specs/<capability-path>/spec.md direkt, um ihn zu ändern. Hier ist <capability-path> das Verzeichnis relativ zu specs/, wie user-auth in einem flachen Projekt oder identity/user-auth in einem nach Domäne organisierten Projekt.

Die Änderung richtig dimensionieren

Der häufigste Fehler bei der Erstellung ist keine schlecht formulierte Anforderung — es ist eine Änderung, die versucht, drei Änderungen zu sein.

Eine gute Änderung hat eine Absicht, die Sie in einem Satz ausdrücken können. „Fügen Sie einen Dunkelmodus-Umschalter hinzu.“ „Drosseln Sie den Login-Endpunkt.“ „Migrieren Sie Sitzungen weg von Cookies.“ Wenn die Beschreibung der Änderung viel „und außerdem“ erfordert, ist dies das Signal, sie aufzuteilen.

Anzeichen dafür, dass eine Änderung zu groß ist:

• Der Umfang des Vorschlags liest sich wie eine Liste unabhängiger Funktionen.
• Die Überprüfung würde einen Nachmittag dauern, also wird es niemand tun.
• Zwei Personen könnten nicht daran arbeiten, ohne sich zu behindern.
• Die Hälfte der Aufgaben könnte eigenständig ausgeliefert werden.

Kleinere Änderungen sind einfacher zu überprüfen, einfacher in einer fokussierten Sitzung zu erstellen und später, sechs Monate später, wenn das Archiv das Einzige ist, was übrig bleibt, leichter zu durchdenken. Sie können immer mehrere Änderungen parallel ausführen — siehe Bearbeiten & Iterieren und Workflows.

Das Gegenteil tritt ebenfalls auf: Eine Tippfehlerkorrektur in einer Zeile benötigt keine drei Anforderungen und ein Design-Dokument. Passen Sie die Zeremonie an die Bedeutung an.

So steuern Sie die KI zu einem guten Entwurf

Da /opsx:propose den ersten Entwurf erstellt, spiegelt die Qualität dessen, was Sie zurückerhalten, die Qualität dessen wider, was Sie eingeben. Sie müssen keine Anforderungen von Hand schreiben — Sie müssen die KI gut ausrichten:

• Nennen Sie die Absicht und die Grenze. „Fügen Sie einen Dunkelmodus-Umschalter hinzu, der beim ersten Laden die OS-Einstellung übernimmt — berühren Sie die bestehende Theme-API nicht.“ Der Teil außerhalb des Geltungsbereichs ist genauso wichtig wie der Teil innerhalb.
• Nennen Sie die Fälle, die Ihnen wichtig sind. „Stellen Sie sicher, dass es ein Szenario für einen Benutzer gibt, der bereits manuell ein Thema ausgewählt hat.“ Die KI deckt ab, worauf Sie hinweisen.
• Dann bearbeiten. Es ist plain Markdown. Schärfen Sie eine vage SHALL, löschen Sie ein Szenario, das nichts testet, fügen Sie den fehlenden Fall hinzu — oder bitten Sie die KI darum: „Die Timeout-Anforderung ist vage, binden Sie sie an 30 Minuten.“

Entwurf, Schärfen, wiederholen. Einige Runden davon produzieren eine Spezifikation, der Sie vertrauen würden, was den ganzen Punkt ausmacht.

Eine schnelle Checkliste

• Jede Anforderung ist ein beobachtbares Verhalten mit einem SHALL/MUST.
• Keine Implementierungsdetails sind in die Anforderungen eingebaut.
• Jede Anforderung hat mindestens ein Szenario, das sie tatsächlich ausübt.
• Die wichtigen Rand- und Fehlerfälle haben Szenarien, nicht nur der Happy Path.
• Deltas verwenden ADDED / MODIFIED / REMOVED korrekt gegenüber der aktuellen Spezifikation.
• Die gesamte Änderung hat eine Absicht, die Sie in einem Satz ausdrücken können.

Weiterführende Links

• Überprüfen einer Änderung — der zweiminütige Durchlauf, der erfasst, was durchgerutscht ist.
• Konzepte — das tiefere Modell hinter Spezifikationen, Änderungen und Deltas.
• Beispiele & Rezepte — echte Änderungen von Anfang bis Ende.