1. Motivation
Beim agentischen Programmieren (Claude Code, Cursor, Copilot etc.) verliert der Agent nach jeder Session seinen gesamten Kontext. Er weiß nicht mehr, was das System leisten soll, welche Designentscheidungen getroffen wurden oder warum etwas so gebaut ist, wie es ist. Je größer die Codebase, desto gravierender wird dieses Problem: Der Agent muss sich jedes Mal neu orientieren, interpretiert Code ohne Hintergrundwissen und trifft Entscheidungen, die früheren Designentscheidungen widersprechen können.
Das Framework OpenSpec adressiert genau dieses Problem. Die hier beschriebene Anleitung setzt die Kernprinzipien von OpenSpec ohne zusätzliches Tooling um – ausschließlich mit Markdown-Dateien und einer Verzeichniskonvention.
2. Kernprinzipien
2.1. Persistenter, maschinenlesbarer Kontext
Specs sind funktionale Anforderungen, die als Dateien im Repository leben. Sie geben dem Agenten bei jeder neuen Session sofort Orientierung: Was soll das System leisten? Welche Szenarien sind abgedeckt? Welche Constraints gelten?
Der Agent liest die relevante Spec, bevor er Code anfasst, und arbeitet gegen eine klare Anforderung – nicht gegen seine eigene Interpretation des bestehenden Codes. Alle weiteren Vorteile ergeben sich aus diesem Grundprinzip.
2.2. Änderungen auf Anforderungsebene nachvollziehen
Bei jeder Änderung wird ein „Spec-Delta" erzeugt, das zeigt, was sich an den Anforderungen ändert – nicht nur am Code. Reviewer können die Absicht einer Änderung in Sekunden verstehen, ohne sich durch den Code graben zu müssen.
3. Verzeichnisstruktur (Quarkus-Projekt)
Die Benennung der Spec-Ordner folgt dem Schema domäne-fähigkeit (z.B. auth-login, order-checkout) und spiegelt idealerweise die Java-Paketstruktur wider.
my-quarkus-app/
├── specs/ (1)
│ ├── auth-login/
│ │ └── spec.md
│ ├── auth-session/
│ │ └── spec.md
│ ├── user-registration/
│ │ └── spec.md
│ ├── order-checkout/
│ │ └── spec.md
│ └── notification-email/
│ └── spec.md
│
├── changes/ (2)
│ └── add-remember-me/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/
│ └── auth-session/
│ └── spec.md
│
├── src/ (3)
│ ├── main/
│ │ ├── java/com/example/
│ │ │ ├── auth/
│ │ │ │ ├── LoginResource.java
│ │ │ │ ├── SessionService.java
│ │ │ │ └── ...
│ │ │ ├── user/
│ │ │ ├── order/
│ │ │ └── notification/
│ │ └── resources/
│ │ ├── application.properties
│ │ └── ...
│ └── test/
│ └── java/com/example/
├── pom.xml
└── README.md| 1 | Lebende Spezifikationen – eine pro Fähigkeit/Feature |
| 2 | Geplante Änderungen (temporär, bis umgesetzt und gemergt) |
| 3 | Quarkus-Quellcode, Paketstruktur spiegelt die Spec-Ordner |
4. Format einer Spec
Jede spec.md folgt einem einheitlichen Aufbau:
# auth-session
## Purpose
Verwaltung des Session-Lebenszyklus: Erstellung, Validierung, Ablauf.
## Requirements
### Session-Erstellung
Das System MUSS bei erfolgreicher Authentifizierung ein JWT erzeugen.
#### Szenario: Erfolgreicher Login
- GEGEBEN ein Benutzer mit gültigen Credentials
- WENN er sich über POST /api/auth/login authentifiziert
- DANN erhält er ein JWT mit 24h Gültigkeit
- UND das Token enthält die Benutzer-Rolle
### Session-Ablauf
Das System MUSS Sessions nach konfigurierter Dauer invalidieren.
#### Szenario: Token abgelaufen
- GEGEBEN ein authentifizierter Benutzer
- WENN das Token abgelaufen ist
- DANN antwortet das System mit 401
- UND der Client muss sich erneut authentifizieren
## Constraints
- Tokens werden nicht serverseitig gespeichert (stateless)
- Refresh-Tokens werden in HttpOnly-Cookies transportiert5. Workflow im Alltag
5.1. Schritt 1: Änderung planen (Proposal)
Lege unter changes/feature-name/ eine proposal.md an:
# Proposal: Remember-Me-Funktion
## Motivation
Benutzer müssen sich täglich neu einloggen, was die UX verschlechtert.
## Änderung
- Checkbox "Angemeldet bleiben" im Login-Formular
- Verlängerte Session-Dauer (30 Tage) via Refresh-Token
## Betroffene Specs
- auth-session (Session-Dauer wird konfigurierbar)
- auth-login (neuer Parameter)5.2. Schritt 2: Tasks und Design festhalten
In tasks.md die konkreten Implementierungsschritte auflisten.
In design.md technische Entscheidungen dokumentieren (z.B. „Refresh-Token in DB vs. Cookie-only").
# Design: Remember-Me
## Entscheidung: Token-Speicherung
**Gewählt:** HttpOnly-Cookie mit Refresh-Token
**Alternativen:** Serverseitige Session-DB
**Begründung:** Stateless-Architektur beibehalten, kein zusätzlicher Infrastrukturaufwand5.3. Schritt 3: Spec-Delta vorbereiten
Kopiere die betroffene spec.md nach changes/feature-name/specs/ und schreibe die Zielversion.
Im PR wird der Diff zwischen alter und neuer Spec sichtbar.
### Session-Ablauf
- Das System MUSS Sessions nach 24 Stunden invalidieren.
+ Das System MUSS Sessions nach konfigurierter Dauer invalidieren.
+ ### Erweiterte Session (Remember Me)
+ Das System MUSS bei aktivierter "Angemeldet bleiben"-Option
+ eine Session-Dauer von 30 Tagen gewähren.
+
+ #### Szenario: Remember-Me aktiv
+ - GEGEBEN ein Benutzer aktiviert "Angemeldet bleiben"
+ - WENN er sich erfolgreich authentifiziert
+ - DANN erhält er ein Refresh-Token mit 30 Tagen Gültigkeit
+ - UND das Token wird als HttpOnly-Cookie gesetzt6. Arbeiten mit KI-Agenten
6.1. Kontext bereitstellen
Weise den Agenten zu Beginn einer Session auf die relevanten Specs hin:
Lies bitte specs/auth-session/spec.md und specs/auth-login/spec.md.
Ich möchte die Remember-Me-Funktion gemäß
changes/add-remember-me/proposal.md umsetzen.Der Agent hat damit sofort den nötigen Kontext und arbeitet gegen die definierten Anforderungen.
7. Zusammenfassung
| Artefakt | Zweck |
|---|---|
|
Lebende Anforderungsdokumentation pro Feature |
|
Was und warum einer geplanten Änderung |
|
Technische Entscheidungen und Alternativen |
|
Aufgaben-Breakdown für die Implementierung |
|
Spec-Deltas – zeigen die Anforderungsänderung |
Die Specs werden eingecheckt, durchlaufen den gleichen PR-Prozess wie Code und bilden so eine versionierte, maschinenlesbare Wissensbasis, die sowohl Menschen als auch KI-Agenten als verlässlichen Kontext nutzen können.