ki-engineeering/06-problem-zu-spezifikation.md

Vom Problem zur Spezifikation

Die Ampel steht auf Grün oder Gelb. Jetzt droht der zweite teure Fehler: ihr springt von „LLM ist ok“ direkt in Prompt und Framework — ohne zu sagen, was Erfolg ist, was scheitern darf, und was es kosten und riskieren darf.

In klassischem SE wäre das undenkbar: niemand baut Payment ohne Failure Modes. Mit AI-Features passiert es trotzdem, weil Demos Qualität vortäuschen und „wir iterieren am Prompt“ wie eine Spec klingt. Tut es nicht.

Kern in einem Satz: Eine AI-Feature-Spec macht Nutzen, Messgrößen, Failure Modes, Cost/Latency-Envelope und Privacy-Grenzen explizit — bevor Adaptation und Prompt die Architektur festnageln.

Lebende Vorlage: templates/ai-feature-spec.md. Eval und Go-Live hängen dran: eval-plan.md, production-ready-checklist.md.

---

Bridge: Klassisches SE → AI Engineering

Klassische Spec / PRD	In der AI-Feature-Spec zusätzlich / anders
User Story, Akzeptanzkriterien	Task Success und Qualitätsmetriken, die über „Seite lädt“ hinausgehen
Fehlercodes, Edge Cases	Halluzination, Injection, Tool-Missbrauch, „überzeugend falsch“
SLOs (Latency, Availability)	plus Token-Kosten, Repair-Raten, Time-to-final vs. first-token
Datenklassen, DSGVO-Felder	was ins Context-Fenster und in Logs/Traces darf
Out of Scope	plus was das Modell nicht entscheiden darf (Wirkungsebene)
Testplan	Golden Set, Online-Samples, Gate bei Model/Prompt-Change
Owner Feature	Owner für Prompt, Eval, Model-Change, Incident (können dieselben Personen sein)

Die Spec ersetzt keine Architektur. Sie verhindert, dass Architektur und Prompt implizite Produktentscheidungen treffen.

Voraussetzung aus Kapitel 05: Ampel und ja / nein / hybrid sind gesetzt. Rot spezifiziert man nicht „trotzdem mit LLM“ — man spezifiziert den deterministischen Ersatz oder stoppt.

---

Warum AI-Specs scheitern (kurz)

Muster	Folge
Nur Happy-Path-Demo beschrieben	kein Eval, kein Fallback, On-Call ratlos
Qualität = „klingt gut“	stilistisch optimiert, faktisch falsch
Kosten/Latency fehlen	Unit Economics und UX platzen unter Last
Privacy als Anhang	PII wandert in Prompts, Traces und Vendor-Logs
Scope = „der Bot kann alles“	unendliche Failure Surface, kein Schnitt
Spec nach dem Prompt	Prompt wird heimliche Spec; Review unmöglich

Die Heilung ist banal und unbequem: schreiben, teilen, freigeben — auch wenn Felder anfangs „unbekannt“ heißen. Unbekannt ist ehrlicher als implizit.

---

Anatomie der AI-Feature-Spec

Orientierung an templates/ai-feature-spec.md. Die Abschnitte sind die Mindestfläche; Tiefe skaliert mit Risiko.

1. Problem und Nutzer

• Problem: welcher Schmerz, in welcher Situation?
• Nutzer / Persona: wer tippt, wer liest, wer haftet bei Fehler?
• Job-to-be-done: „Wenn … will ich … damit …“
• Warum jetzt: Trigger (Last, Kosten, Wettbewerb, Compliance) — nicht „weil AI“.
• Nicht-Ziele: was wir bewusst nicht lösen (verhindert Agent-Maximalismus).
• Wirkungsebene: nur formulieren / vorschlagen / entscheiden / ausführen — inkl. Side Effects, die wirklich erlaubt sind.

Ohne Job-to-be-done wird jedes Modell-Update zur Roadmap.

2. Erfolgskriterien (messbar) — T3

Qualität, die nicht messbar ist, existiert in der Spec nicht. Mindestens eine Qualitätsmetrik, eine Latency-Metrik, eine Kostenmetrik, eine Safety/Policy-Metrik — auch grob.

Metrik-Typ	Beispiele	Messung
Aufgabe erfüllt	Task Success, Korrekte Extraktion, Routing-Accuracy	Golden Set, Shadow, Human Sample
Nutzen / Business	Deflection-Rate, Time-to-Resolution, Edit-Distance zum finalen Text	Produkt-Analytics
Latenz	p95 Time-to-final; optional Time-to-first-token	Traces
Kosten	€ oder Tokens pro Request; € pro erfolgreichem Task	Token Accounting
Safety / Policy	Guardrail-Hits, Policy-Violations, Leakage-Funde	Suites + Review
UX-Vertrauen	Citation-Rate, „unable to answer“-Rate, User-Corrections	Logs + UI-Events

Zielformulierung: Zahl oder Band + Methode + „was passiert, wenn verfehlt“ (nicht shippen / nur intern / Feature-Flag aus).

Schlechte Ziele: „möglichst gut“, „besser als ChatGPT“, „Stakeholder happy“.
Bessere Ziele: „≥ X % Task Success auf Golden Set v1 (n=…)“, „p95 < Y ms interaktiv“, „≤ Z € / 1k Requests bei Tier …“.

3. Failure Modes

Liste, die passieren wird — nicht die, die ihr euch wegwünscht. Pro Mode: Impact, Erkennung, Mitigation, ob Fallback deterministisch ist.

Mindestkatalog (streichen was nicht passt, ergänzen was domänenspezifisch ist):

Failure Mode	Typische Mitigation
Halluzination / unbelegte Fakten	Grounding, Citations, Refuse, HITL
Schema- / Contract-Bruch	Structured Output, Validate, Repair mit Cap
Timeout / Provider-Outage	Deadline, Queue, cached/degraded mode
Tool-Fehler / Partial Apply	Idempotenz, Kompensation, User-sichtbarer Status
Prompt Injection / Tool Abuse	Isolation, least privilege, Output-Filter (Kap. 19)
Data Leakage (Context, Logs, Antwort)	Redaction, Datenklassen, Trace-Policy
Cost Spike / Loop	Max steps, Budget Cap, Kill-Switch
Quality Drop nach Model-Update	Pin, Eval-Gate, Canary, Rollback (T9)
Übervertraute UX	Framing als Entwurf; Pflichtfelder vor Wirkung

Orakel-Test aus Kap. 05 gehört hierher: 5 % überzeugend falsch — welcher Failure Mode fängt das auf?

4. Constraints: Cost Envelope, Latency, Privacy

Cost Envelope (T7)

• Budget pro Request (soft/hard) und pro Zeitraum (Feature/Tenant)
• Erlaubte Model-Tiers und ob Auto-Upgrade erlaubt ist
• Max. Tool-Calls / Agent-Steps
• Verhalten bei Überschreitung: downgrade, queue, reject, human

Ohne Envelope optimiert das Team Eloquenz und Context-Größe — die Rechnung optimiert sich selbst, gegen euch.

Latency-Budget

• Interaktiv vs. async/Batch trennen
• p95 Final vs. First-Token
• UX bei Wartezeit (Streaming, Skeleton, „läuft im Hintergrund“)

Privacy und Compliance (Praxis, keine Rechtsberatung)

• Datenklassen im Input, Retrieval und Memory
• Residenz (wo läuft Inferenz, wo liegen Traces)
• Retention: Prompts, Outputs, Eval-Logs
• Zweckbindung und Nutzertransparenz
• Was niemals ins Prompt/Tool-Log darf (Secrets, besondere Kategorien)

Wenn unklar: Feature bleibt hinter Flag, bis Privacy-Owner „ok“ sagt — das ist Spec, kein Blocker-Theater.

5. Architektur-Skizze (Adaptation) — nur grob

Noch keine Ladder-Doktorarbeit (Kapitel 08). In der Spec reicht:

• Ampel und Hybrid-Schnitt (was deterministisch bleibt)
• Voraussichtliche Stufe: Prompt-only / Structured / RAG / Tools / Agent / FT
• Ein Satz Begründung und die größten Unbekannten

Detail-ADRs kommen, wenn die Entscheidung teuer oder schwer reversibel wird (adr-adaptation.md).

6. Eval-Plan (Verweis mit Substanz)

Die Spec verweist auf eval-plan.md, muss aber mindestens sagen:

• Größe und Herkunft des ersten Golden Sets (auch n=20 ist ein Start, wenn repräsentativ)
• welches Gate Releases blockt
• wer das Set owned

Ohne das ist Abschnitt 2 (Metriken) Dekoration.

7. Production Ready und Ownership

• Checkliste: production-ready-checklist.md
• Kill-Switch / Feature-Flag
• On-Call und Runbook-Verweis (incident-runbook-ai.md)
• Review-Pfad für Prompt- und Model-Diffs

8. Offene Fragen

Explizite Unbekannte mit Owner und Datum schlagen implizite Hoffnung.

---

Mini-Beispiel (Skizze, kein Produktversprechen)

Nur zur Form — Zahlen sind Platzhalter, keine Benchmarks.

Feld	Beispielinhalt
Job-to-be-done	Support will L1-Tickets zu Intent + Entwurf-Antwort, damit Erstreaktion schneller wird
Ampel	Gelb → hybrid
Hybrid	Intent+Entwurf LLM; Erstattung/Kündigung nur bestehende APIs + Rechte
Task Success	≥ 85 % korrektes Intent-Label auf Golden Set v1 (n=150, historisch gelabelt)
Latency	p95 Final < 4 s interaktiv
Kosten	≤ … € / 1k Tickets bei Balanced-Tier; kein Strong-Tier default
Failure	Halluzinierte Policy → nur mit Retrieval-Zitat absenden; sonst Template „Bitte warten, Kollege“
Privacy	Keine Zahlungsdaten im Prompt; Ticket-Body redaction rule R1
Owner	Feature: …; Eval: …; On-call: Team …

Wenn ihr diese Zeilen nicht füllen könnt, seid ihr nicht „agil“ — ihr seid unspezifiziert.

---

Wie die Spec im Flow sitzt

Problem / Idee
    → Ampel (Kap. 05, Checkliste wann-llm)
    → AI-Feature-Spec (dieses Kapitel)
    → Adaptation / Architektur (Kap. 07–10)
    → Bausteine + Orchestrierung (Kap. 11–16)
    → Eval-Gates + Production Ready (Kap. 17–25)

Definition of Ready (AI): Spec Status ≥ Review, Ampel gesetzt, mind. ein Qualitäts- und ein Kosten-/Latency-Ziel, Top-5 Failure Modes, Privacy-Owner informiert, Eval-Owner benannt.

Definition of Done (AI): Gates aus Eval-Plan grün, Production-Ready-Check bestanden, Kill-Switch getestet — nicht „Demo hat gefallen“.

---

Patterns und Trade-offs

Pattern: Spec vor Prompt-Repo

Erst Spec (auch Draft), dann Prompt-Versionierung. Sonst versioniert ihr Text ohne Ziel.

Trade-off: ein halber Tag Schreiben vs. Wochen Prompt-Theater.

Pattern: Metriken, die das Team steuern kann

Wählt Metriken, die sich durch Context, Ladder-Stufe und Harness bewegen — nicht nur Vanity (Token-Verbrauch ohne Task Success).

Pattern: Failure Modes als Backlog

Jeder schwere Offline-Fehler → neuer Golden-Set-Fall oder neue Regel. Die Spec lebt.

Decision Frame: Wie viel Spec-Tiefe?

Risiko / Wirkung	Spec-Minimum
Interner Entwurf, keine Side Effects	Kurzform: Job, 1 Qualitätsziel, 3 Failures, Budget grob
Nutzer-sichtbar, Fakten	+ Grounding, Citations, Privacy, Eval n≥ sinnvoll
Tools / Geld / Rechte	+ Hybrid-Schnitt, HITL, Security-Review, On-Call
Reguliert / hohes Schadenmaß	+ schriftliche Freigaben, Audit-Spur, ggf. kein LLM auf Entscheid

---

Anti-Patterns

Anti-Pattern	Symptom	Besser
Prompt-as-Spec	„Steht im System-Prompt“	Spec im Repo; Prompt implementiert Contracts
Metrik-Theater	20 KPIs, keine Gate-Schwelle	3–6 steuerbare Metriken mit Zielen
Nur Offline oder nur Bauch	Golden Set ohne Online — oder umgekehrt	beides, unterschiedlich gewichtet
Budget „schauen wir später“	erste Rechnung = Incident	Envelope in Spec und Alert
Privacy-Anhang	Absatz ganz unten, nie operationalisiert	Datenklassen + Redaction als Constraint
Endless Scope	Bot soll „alles Support“	Nicht-Ziele + Hybrid-Schnitt
Spec einmal schreiben	veraltet nach erstem Model-Change	Review bei Prompt/Model/Ladder-Change

---

Production Notes

Cost. Envelope und Accounting-IDs (feature key) von Tag 1. Spec nennt die Währung der Optimierung: €/Task Success schlägt €/Token allein.

Latency. SLOs in der Spec sind die Quelle für Timeouts und UX — nicht umgekehrt („wir streamen, also passt’s“).

Observability. Jede Spec-Metrik braucht eine Messquelle. Was ihr nicht tracen könnt, könnt ihr nicht als Ziel verkaufen (observability-minimum.md).

Security. Failure Modes Injection/Leakage/Tool Abuse in der Spec erzwingen Design-Reviews früh (security-review-ai.md).

Lifecycle. Spec-Version und Prompt-/Model-Version verlinken. Model-Update = Spec-Review, ob Ziele noch gelten (T9).

---

Key Takeaways

• Nach der Ampel kommt die Spec, nicht der Prompt: Nutzen, Metriken, Failures, Envelope, Privacy.
• Messbar oder nicht in der Spec (T3) — Qualität, Kosten, Latency, Policy.
• Failure Modes und Hybrid-Schnitt definieren, was das Modell nicht darf.
• Eval-Plan und Production-Ready sind Teil der Lieferdefinition, nicht Nachtrag.
• Vorlage nutzen und versionieren: templates/ai-feature-spec.md.

Praktische nächste Schritte

1. Kopiere templates/ai-feature-spec.md ins Feature-Repo oder Confluence-Äquivalent und setze Status auf Draft.
2. Fülle Abschnitte 1–4 in 60–90 Minuten: Problem, 4 Metrik-Zeilen, Top-Failure-Modes, Constraints — Lücken als offene Fragen.
3. Hänge Ampel-Entscheidung und Hybrid-Schnitt aus checklists/wann-llm.md an.
4. Benenne Eval-Owner und leg den Stub eval-plan.md mit Ziel-Gate an (auch n=20 Golden Cases).
5. Lies als Nächstes die Architektur-Schiene: Architektur-Landkarte und/oder Entscheidungsrahmen Adaptation — sobald die Spec Review übersteht.