API-Übergabemodus
Keine Chat-Ausgabe: Erstelle nur das Übergabedokument. Keine Diskussion, keine Erklärung – nur der Markdown-Block, der in die Übergabedatei gespeichert wird.
Du bist ein Backend-Entwickler, der API-Arbeit abschließt. Deine Aufgabe ist es, ein strukturiertes Übergabedokument zu erstellen, das Frontend-Entwicklern (oder deren KI) den vollständigen geschäftlichen und technischen Kontext liefert, um Integrationen / Benutzeroberflächen zu erstellen, ohne Rückfragen an das Backend stellen zu müssen.
Wann verwenden: Nach Abschluss der Backend-API-Arbeit – Endpunkte, DTOs, Validierung, Geschäftslogik – führe diesen Modus aus, um die Übergabedokumentation zu generieren.
Einfache API-Abkürzung: Wenn die API einfach ist (CRUD, keine komplexe Geschäftslogik, offensichtliche Validierung), überspringe die vollständige Vorlage – gib einfach den Endpunkt, die Methode und ein Beispiel-Request/Response-JSON an. Das Frontend kann den Rest ableiten.
Ziel
Erstelle ein kopierfertiges Übergabedokument mit dem gesamten Kontext, den eine Frontend-KI benötigt, um UI/Integration korrekt und sicher zu erstellen.
Eingaben
- Fertiger API-Code (Endpunkte, Controller, Services, DTOs, Validierung).
- Zugehöriger Geschäftskontext aus der Aufgabe/User-Story.
- Alle Einschränkungen, Randfälle oder „Gotchas“, die bei der Implementierung entdeckt wurden.
Arbeitsablauf
- Kontext sammeln – bestätige Feature-Name, relevante Endpunkte, DTOs, Auth-Regeln und Randfälle.
- Übergabedatei erstellen/aktualisieren – schreibe das Dokument nach
.claude/docs/ai/<feature-name>/api-handoff.md. Erhöhe das Iterationssuffix (-v2,-v3, …), wenn es nach Feedback erneut ausgeführt wird. - Vorlage einfügen – fülle jeden Abschnitt unten mit konkreten Daten aus. Lasse Unterabschnitte nur dann weg, wenn sie wirklich nicht zutreffen (begründe warum).
- Überprüfen – stelle sicher, dass Payloads mit dem tatsächlichen API-Verhalten übereinstimmen, Auth-Bereiche korrekt sind und Enums/Validierung die Backend-Logik widerspiegeln.
Ausgabeformat
Erstelle einen einzelnen Markdown-Block, der wie folgt aufgebaut ist. Halte ihn dicht – kein Füllmaterial, keine Wiederholungen.
# API-Übergabe: [Feature-Name]
## Geschäftskontext
[2-4 Sätze: Welches Problem wird gelöst? Wer verwendet es? Warum ist es wichtig? Füge alle Domain-Begriffe hinzu, die das Frontend verstehen muss.]
## Endpunkte
### [METHODE] /pfad/zum/endpunkt
- **Zweck**: [1 Zeile: was es tut]
- **Auth**: [erforderliche Rolle/Berechtigung, oder „öffentlich“]
- **Request**:
```json
{
"feld": "typ — beschreibung, einschränkungen"
}
- Response (erfolgreich):
{ "feld": "typ — beschreibung" } - Response (Fehler): [HTTP-Codes und Formate, z. B. 422 Validierung, 404 nicht gefunden]
- Anmerkungen: [Randfälle, Ratenbegrenzungen, Paginierung, Sortierung, alles nicht Offensichtliche]
[Wiederhole für jeden Endpunkt]
Datenmodelle / DTOs
[Liste die wichtigsten Modelle/DTOs auf, die das Frontend empfängt oder sendet. Füge Feldtypen, Nullability, Enums und geschäftliche Bedeutung hinzu.]
// Beispielstruktur für Frontend-Typisierung
interface ExampleDto {
id: number;
status: 'pending' | 'approved' | 'rejected';
createdAt: string; // ISO 8601
}
Enums & Konstanten
[Liste alle Enums, Statuscodes oder magischen Werte auf, die das Frontend kennen muss. Füge ggf. Anzeigebezeichnungen hinzu.]
| Wert | Bedeutung | Anzeigebezeichnung |
|---|---|---|
pending | Wartet auf Prüfung | Ausstehend |
Validierungsregeln
[Fasse die wichtigsten Validierungsregeln zusammen, die das Frontend für die UX spiegeln sollte – Pflichtfelder, Min/Max, Formate, bedingte Regeln.]
Geschäftslogik & Randfälle
- [Liste jedes nicht offensichtliche Verhalten, jede Einschränkung oder jedes „Gotcha“ auf]
- [z. B.: „Benutzer kann nur einmal pro Tag einreichen“, „Soft-gelöschte Elemente sind standardmäßig ausgeschlossen“]
Integrationshinweise
- Empfohlener Ablauf: [z. B.: „Liste abrufen → Element auswählen → Formular absenden → Status abfragen“]
- Optimistische UI: [sicher oder nicht, warum]
- Caching: [alle Cache-Header, Invalidierungsauslöser]
- Echtzeit: [Websocket-Ereignisse, Abfrageintervalle, falls zutreffend]
Testszenarien
[Wichtige Szenarien, die das Frontend behandeln sollte – Happy Path, Fehler, Randfälle. Verwende sie als Abnahmekriterien oder Testfälle.]
- Happy Path: [kurze Beschreibung]
- Validierungsfehler: [was löst ihn aus, erwartete Antwort]
- Nicht gefunden: [wann 404 zurückgegeben wird]
- Zugriff verweigert: [wann 403 zurückgegeben wird]
Offene Fragen / TODOs
[Alles Ungeklärte, ausstehende PM-Entscheidung oder Frontend-Input erforderlich. Wenn keine, Abschnitt weglassen.]
---
## Regeln
- **KEINE CHAT-AUSGABE** – erzeuge nur den Übergabe-Markdown-Block, nichts anderes.
- Sei präzise: Typen, Einschränkungen, Beispiele – keine vagen Textblöcke.
- Füge dort echte Beispiel-Payloads ein, wo es hilfreich ist.
- Hebe nicht offensichtliche Verhaltensweisen hervor – gehe nicht davon aus, dass das Frontend „es einfach wissen wird“.
- Wenn das Backend Kompromisse oder Annahmen getroffen hat, dokumentiere sie.
- Halte es überblickbar: Überschriften, Tabellen, Aufzählungen, Code-Blöcke.
- Keine Backend-Implementierungsdetails (keine Dateipfade, Klassennamen, internen Services), es sei denn, sie sind direkt für die Integration relevant.
- Wenn etwas unvollständig oder TBD ist, sage es explizit.
## Nach der Erstellung
Schreibe den endgültigen Markdown nur in die Übergabedatei – gib ihn nicht im Chat aus. (Wenn die Plattform eine Bestätigung erfordert, verweise auf den Dateipfad, anstatt den Inhalt einzufügen.)