Teil 7. Feature-Spezifikation

Nach den Projektregein haben Sie eine Roadmap, aber noch keine Erlaubnis, Code zu schreiben. Der nächste Schritt ist die Spezifikation des ersten Features. In unserem Lernprojekt heißt die erste Phase Hello Hono: Hono installieren, einen TypeScript-Server starten, eine minimale HTML-Seite ausliefern und die Typen prüfen.

Die Feature-Spezifikation verhindert, dass der Agent aus einer kleinen Phase ein halbes Produkt macht. Sie beantwortet drei Fragen:

• was in die Grenzen der Aufgabe fällt und was nicht;
• in welcher Reihenfolge umzusetzen ist;
• welche Fakten erfüllt sein müssen, um das Ergebnis anzunehmen.

Regel für dieses Tutorial: Die textliche Spezifikation leitet den Agenten, aber die Fusion muss die Fakten entscheiden. Deshalb wird validation.md sofort als Satz prüfbarer Aussagen geschrieben, nicht als allgemeine Wunschliste.

Struktur der Feature-Spezifikation

specs/
  2026-05-01-hello-hono/
    requirements.md
    plan.md
    validation.md

Das Datum macht die Arbeitsreihenfolge verständlich. Der Name in kebab-case verbindet den Ordner mit dem Branch.

Branch erstellen

git checkout -b phase-1-hello-hono

Oder bitten Sie Qwen Code:

Finde die nächste unvollendete Phase in @specs/roadmap.md.
Erstelle dafür einen Branch.
Implementiere noch keinen Code.

Frag mich zuerst nach der Feature-Spezifikation.

Prüfen Sie git status, um nicht ein Feature auf unvollendeter Arbeit aufzubauen.

Anfrage für Qwen Code

Finde die nächste Phase in @specs/roadmap.md und erstelle eine Feature-Spezifikation.

Erstelle:
- specs/YYYY-MM-DD-feature-name/requirements.md
- specs/YYYY-MM-DD-feature-name/plan.md
- specs/YYYY-MM-DD-feature-name/validation.md

Stelle mir vor dem Schreiben der Dateien genau drei gruppierte Fragen:
1. Grenzen: Was soll und was soll nicht in das Feature einfließen
2. Entscheidungen: Schlüsselentscheidungen der Implementierung
3. Kontext: Ton, Einschränkungen, Risiken und Erwartungen an die Prüfung

Nutze @specs/mission.md und @specs/tech-stack.md als Orientierung.
Schreibe keine Implementierungscode.

Separater Klärungs-Schritt

Im GitHub Spec Kit ist zwischen Absicht und Plan ein separater Schritt /clarify ausgewiesen: Der Agent stellt eine Reihe punktueller Fragen zu den Stellen, an denen die Anforderungen unterschiedliche Interpretationen zulassen. Wir reproduzieren diesen Schritt innerhalb des Blocks «drei gruppierte Fragen», aber bei großen Features lohnt es sich, die Klärung separat auszulagern – besonders wenn die ersten Antworten neue Mehrdeutigkeiten eröffnet haben.

Anzeichen für eine separate Klärung:

• der Agent sagt selbst «ich kann X als A oder als B verstehen»;

• zwei Stellen der Spezifikation wirken äußerlich konsistent, erfordern aber sich gegenseitig ausschließende Entscheidungen im Code;
• die Entscheidung hängt von einem externen Service oder einer Absprache ab, die dem Agenten nicht bekannt ist;
• Ihre eigenen Antworten widersprechen sich.

Anfrage für die Klärung:

Bevor du requirements.md, plan.md und validation.md schreibst, liste alle Stellen auf,
an denen dir Alternativen verbleiben. Stelle mir zu jeder genau eine Frage: Was wählen
und warum. Schlage keine Antwort vor, bevor ich gewählt habe. Rate nicht. Gibt es keine
Alternativen, schreibe «keine Klärung erforderlich».

Wenn der Agent 0–2 punktuelle Fragen zurückgibt, lohnt es sich meist zu antworten und weiterzumachen. Bei 6+ ist das ein Signal, dass die Phase zu groß ist oder dass die Verfassung zu viele offene Entscheidungen lässt; besser anhalten, mission.md/tech-stack.md aktualisieren und später zur Spezifikation zurückkehren.

Beispiel requirements.md

# Anforderungen — Hello Hono

## Grenzen

Hono mit Entwicklungsserver über tsx installieren und konfigurieren. Eine Route GET / hinzufügen, die über Hono JSX eine minimale HTML-Seite zurückgibt. Bestätigen, dass TypeScript durchgehend funktioniert.

## Außerhalb der Grenzen

- Keine Datenbank.
- Keine Authentifizierung.

- Kein Test-Framework-Setup.
- Kein Deployment in Produktivumgebung.
- Keine mehrseitige Navigation.

## Was sich nicht ändern darf

- Strict Mode in `tsconfig.json` bleibt aktiviert.
- `package.json` erhält keine Abhängigkeiten, die nicht in `tech-stack.md` aufgeführt sind.
- `.gitignore` wird nicht verkleinert; Hinzufügen ist erlaubt, Entfernen nicht.
- Bestehende Skripte `npm run typecheck` funktionieren weiterhin.

## Entscheidungen

- Hono-Version ohne ^ oder ~ festnageln.
- Strict Mode TypeScript beibehalten.
- HTML mit Server-Side-Rendering verwenden, kein Client-Framework.

## Kontext

Diese Phase beweist die grundsätzliche Funktionsfähigkeit. Sie soll absichtlich klein sein. Die Startseite darf eine Überschrift, einen Slogan und eine minimale Struktur enthalten.

Negative Anforderungen: Block «Was sich nicht ändern darf»

Der Abschnitt «Außerhalb der Grenzen» beantwortet die Frage «was fügen wir nicht hinzu». Der Abschnitt «Was sich nicht ändern darf» beantwortet eine andere Frage — «was funktioniert bereits und soll weiterhin funktionieren». Diese beiden Listen überschneiden sich, stimmen aber nicht überein.

Einfaches Beispiel. «Außerhalb der Grenzen» sagt: «wir fügen keine Authentifizierung hinzu». «Was sich nicht ändern darf» sagt: «die bestehende Route GET / liefert weiterhin HTML mit <h1>AgentClinic</h1> zurück».

Ohne negative Anforderungen «repariert» der Agent leicht etwas, das nicht kaputt war: benennt eine Route um, ändert das Antwortformat, schreibt einen Feldnamen in der Datenbank um. Ein Teil solcher Regressionen wird von Tests gefangen, aber nicht alle: Gibt es keinen Test für das alte Verhalten, hält nichts außer einem expliziten «nicht ändern» den Agenten auf.

Gute Punkte in diesem Block:

• welche öffentlichen URLs bleiben unverändert;
• welche Feld- und Tabellennamen nicht umbenannt werden;
• welche Antwortformate sich nicht ändern;
• welche Abhängigkeiten nicht «nebenbei» aktualisiert werden;
• welche Konfigurationsdateien unangetastet bleiben.

Wenn das Feature gar nichts bewahren soll (z. B. erste Projektphase, wo es noch keine URLs oder Tabellen gibt), lassen Sie den Abschnitt leer mit dem Vermerk «kein bestehendes Verhalten zu schützen».

Formulierungsformen: EARS und Given/When/Then

Freie Prosa in Anforderungen funktioniert bei kleinen Features, überträgt sich aber schlecht in validation.md: Dieselbe Phrase in Prosa wird von zwei Personen in zwei verschiedene Prüfungen übersetzt. Zwei etablierte Mikroformen helfen.

EARS (Easy Approach to Requirements Syntax) — für funktionale Anforderungen:

WHEN <Bedingung/Ereignis>
THE SYSTEM SHALL <erwartetes Verhalten>.

Zum Beispiel: «WHEN der Benutzer GET / öffnet, THE SYSTEM SHALL HTTP 200 und HTML mit <h1>AgentClinic</h1> zurückgeben».

Given / When / Then — für Akzeptanzszenarien in validation.md:

Given <Vorbedingung>
When  <Aktion>
Then  <erwartetes Ergebnis>.

Zum Beispiel: «Given der Server läuft auf Port 3000. When curl -s http://localhost:3000 ausgeführt wird. Then enthält die Antwort die Teilzeichenkette <h1>AgentClinic</h1> und der Exit-Code von curl ist 0».

Verwandeln Sie nicht die gesamte Spezifikation in strenge Vorlagen — das erschwert das Lesen. Nutzen Sie die Formen dort, wo sonst unklar wäre, wie genau zu prüfen ist: Integrationen, Validierung, Randfälle.

Bereitschaft der Spezifikation zur Implementierung

Bevor Sie zum Code übergehen, prüfen Sie die Spezifikation anhand einer kurzen Checkliste. Ist auch nur ein Punkt nicht erfüllt, ist die Spezifikation noch nicht bereit, und die Implementierung wird raten.

• [ ] Absicht und Zielgruppe des Features sind aus requirements.md ohne Chat-Verlauf verständlich.
• [ ] «Was einfließt» und «was außerhalb der Grenzen liegt» sind konkret formuliert.

• [ ] Der Block «Was sich nicht ändern darf» ist ausgefüllt (oder explizit mit «kein bestehendes Verhalten zu schützen» markiert).
• [ ] Alle getroffenen Entscheidungen sind dokumentiert; offene sind markiert und vor der Implementierung geschlossen.
• [ ] Der Plan ist in Aufgabengruppen gegliedert, jede endet mit einem prüfbaren Ergebnis.
• [ ] In validation.md hat jeder Fakt einen Befehl oder manuelles Szenario; es gibt keine Punkte «alles sollte funktionieren».
• [ ] Dieselbe Person, die die Spezifikation geschrieben hat, kann ein Kriterium «diese Phase ist abgeschlossen» nennen.

Kann die Person die letzte Frage nicht beantworten, wird der Agent es erst recht nicht können. Kehren Sie zum Interview oder zum Klärungs-Schritt zurück.

Beispiel plan.md

# Plan — Hello Hono

## Gruppe 1 — Paket-Setup

1. hono installieren.
2. tsx als Entwicklungsabhängigkeit installieren.
3. Strikte TypeScript-Einstellungen bestätigen.

## Gruppe 2 — Anwendungseinstieg

4. `src/index.ts` durch minimale Hono-Anwendung ersetzen.
5. Route GET / hinzufügen.
6. Server an Port 3000 binden.

## Gruppe 3 — Startseite

7. Startseite mit Server-Side-Rendering hinzufügen.
8. h1 mit AgentClinic ausgeben.
9. Kurzen Slogan gemäß Mission hinzufügen.

## Gruppe 4 — Prüfung

10. `npm run typecheck` ausführen.
11. `npm run dev` ausführen.
12. Bestätigen, dass `curl localhost:3000` HTML zurückgibt.

Beispiel validation.md

# Prüfung — Hello Hono

## Faktensammlung

### F1 — TypeScript kompiliert

- Befehl: `npm run typecheck`
- Erwartung: Exit-Code 0
- Verantwortlich: automatische Prüfung
- Status: angenommen

### F2 — Server startet

- Befehl: `npm run dev`
- Erwartung: Server hört auf Port 3000 ohne Startfehler
- Verantwortlich: manuelle Prüfung
- Status: angenommen

### F3 — Home-Route gibt HTML zurück

- Befehl: `curl -s http://localhost:3000`
- Erwartung: Antwort enthält HTML mit `<h1>AgentClinic</h1>`
- Verantwortlich: manuelle oder automatische Prüfung
- Status: angenommen

### F4 — Grenzen sind nicht ausgeweitet

- Prüfung: Branch-Diff betrachten
- Erwartung: keine Datenbank, Authentifizierung, CI oder zusätzliche Produkt-Routen hinzugefügt
- Verantwortlich: manuelle Prüfung
- Status: angenommen

## Manuelle Prüfung

- Bestätigen, dass der Slogan zur Mission passt.
- Bestätigen, dass unbeteiligte Dateien nicht umgeschrieben wurden.

## Fertigstellungskriterien

- Alle Punkte der Faktensammlung sind umgesetzt oder explizit zurückgestellt.
- Obligatorische automatische Fakten werden bestanden.

- Manuelle Fakten sind geprüft.
- Die Phase der Roadmap kann als abgeschlossen markiert werden.

Spezifikationsprüfung vor der Implementierung

Bitten Sie zuerst den Agenten, Schwachstellen zu finden:

Prüfe @specs/2026-05-01-hello-hono/requirements.md,
@specs/2026-05-01-hello-hono/plan.md und
@specs/2026-05-01-hello-hono/validation.md.

Liste Mehrdeutigkeiten auf, durch die die Implementierung in die Irre gehen könnte.
Liste auch Prüfpunkte auf, die keine konkreten Fakten sind.
Ändere Dateien nicht ohne meine Erlaubnis.

Hat der Agent eine Mehrdeutigkeit gefunden, korrigieren Sie die Spezifikation vor dem Code.

Praxis

1. Wählen Sie die erste Phase der Roadmap.
2. Erstellen Sie einen Branch.
3. Führen Sie das Interview über Qwen Code durch.
4. Erstellen Sie die drei Spezifikationsdateien.
5. Prüfen Sie die Spezifikation auf Mehrdeutigkeit.
6. Committen Sie nur die Spezifikation:

git add specs/2026-05-01-hello-hono
git commit -m "Add Hello Hono feature spec"

Kontrollfragen

1. Warum muss die Feature-Spezifikation vor der Implementierung entstehen?
2. Was sollte in validation.md enthalten sein, außer npm test?
3. Worin unterscheidet sich requirements.md von plan.md?