ki-engineeering/30-anhang-a-templates.md

Anhang A: Templates

Dieser Anhang ist ein PDF-Snapshot der Kern-Vorlagen unter templates/. Er soll offline und im Druck lesbar bleiben — zum Mitdenken, Reviewen und als Einstieg in die jeweiligen Kapitel.

Lebende Quelle ist immer das Repo: die Dateien in templates/ können neuer, ausführlicher oder korrigiert sein. Wenn PDF und Repo auseinanderlaufen, gewinnt templates/. Platzhalter … ersetzen; keine Secrets, keine echten API-Keys, keine Produktions-Hostnamen.

Die Vorlagen hängen an der Buch-Pipeline: Ampel und Spec (Kapitel 05–06) → Adaptation und Modell (08–09) → Tools (13) → Eval und Go-Live (17–25) → Lifecycle und Incident (24–25). Kurz: Spec und Ownership zuerst, dann messbare Gates, dann Betrieb.

Übersicht

Vorlage	Zweck	Kapitel
ai-feature-spec.md	AI-Feature spezifizieren (Nutzen, Metriken, Failures, Constraints)	06
adr-adaptation.md	ADR: Stufe auf der Adaptation Ladder	08
adr-model-hosting.md	ADR: Model-Tier, Routing, Hosting, Pinning	09
eval-plan.md	Offline-/Online-Eval, Gates, Owner	17
tool-contract.md	Schema, Side Effects, AuthZ, Errors pro Tool	13
model-change-checklist.md	Model-/Prompt-Change: Vor, Rollout, Nach	24
production-ready-checklist.md	Go-Live-Gate für AI-Features	17–25
incident-runbook-ai.md	AI-Incident: Stabilisieren, Diagnose, Follow-up	25

Reihenfolge im Alltag oft: Feature-Spec → Adaptation-ADR / Model-Hosting-ADR → Tool-Contracts (falls Tools) → Eval-Plan → Production Ready → bei Change Model-Change → bei Brand Incident-Runbook.

---

A.1 AI-Feature-Spezifikation

Datei: templates/ai-feature-spec.md
Kapitel: 06 — Vom Problem zur Spezifikation
Wann: bevor Prompt, Framework und Adaptation die Produktentscheidungen implizit treffen. Bei Ampel Rot: Spec stoppen oder nur den deterministischen Ersatz spezifizieren.

Zweck: Nutzen, messbare Erfolgskriterien, Failure Modes, Cost/Latency/Privacy-Grenzen und Ownership explizit machen.

Snapshot

Meta

Feld	Wert
Feature	…
Owner (Feature / Eval / On-call)	… / … / …
Status	Draft / Review / Accepted
Spec-Version · Datum	… · …

0. Ampel und Schnitt (aus Kap. 05)

Feld	Wert
Ampel	Grün / Gelb / Rot
LLM	ja / nein / hybrid
Hybrid-Schnitt	LLM macht: … — deterministisch bleibt: …
Begründung (1–3 Sätze)	…

1. Problem und Nutzer

• Problem, Nutzer/Persona, Job-to-be-done
• Warum jetzt; Nicht-Ziele
• Wirkungsebene: nur formulieren / vorschlagen / entscheiden / ausführen (Side Effects: …)

2. Erfolgskriterien (messbar)

Metrik	Ziel	Messung	Bei Verfehlen
Qualität (z. B. Task Success)	…	Offline Eval / Online	…
Latency p95 (final / first-token)	…	Tracing	…
Kosten pro Request oder pro Erfolg	…	Token Accounting	…
Safety / Policy	…	Guardrail Hits / Suite	…
(optional) Business / UX	…	Analytics / Citations / …	…

3. Failure Modes (Auszug der Zeilen im Template)

Failure	Impact	Erkennung	Mitigation / Fallback
Halluzination / unbelegte Fakten	…	…	Validation / Citation / Refuse / HITL
Schema- / Contract-Bruch	…	…	Repair-Cap / Reject
Timeout / Provider-Outage	…	…	…
Tool-Fehler / Partial Apply	…	…	…
Prompt Injection / Tool Abuse	…	…	…
Data Leakage	…	…	…
Cost Spike / Loop	…	…	Cap / Kill-Switch
Quality Drop (Prompt/Model-Change)	…	Eval-Gate	Pin / Canary / Rollback

4. Constraints: Daten/Privacy; nie im Prompt/Log; Budget; erlaubte Model-Tiers; max. Tool-Calls/Agent-Steps; Latency-Budget; Compliance.

5. Architektur-Skizze: Stufe auf der Ladder (Prompt-only … FT); Begründung; Spikes. Detail: Adaptation- und Model-Hosting-ADR.

6. Eval-Plan (Verweis): Golden Set, Release-Gate, Re-eval-Rhythmus → eval-plan.md.

7. Production Ready: Feature-Flag/Kill-Switch; Runbook; Observability-Minimum → production-ready-checklist.md.

8. Offene Fragen: Frage · Owner · Bis.

---

A.2 ADR: Adaptation-Strategie

Datei: templates/adr-adaptation.md
Kapitel: 08 — Entscheidungsrahmen: Adaptation
Wann: wenn die Stufe teuer, riskant, umstritten oder schwer reversibel ist (typisch ab Tools/Agent/FT; früher bei Uneinigkeit).

Zweck: Ladder-Stufe begründen, Alternativen verwerfen, Follow-ups und Review-Trigger binden — vendor-agnostisch.

Snapshot

Status: Proposed | Accepted | Superseded by ADR-…
Datum · Autoren · Reviewer: …

Kontext

Feld	Inhalt
Feature / Capability	…
Link Feature-Spec	…
Ampel (Kap. 05)	Grün / Gelb / Rot · hybrid: ja/nein
Application Pattern (Kap. 07)	Single-Shot / Validate / Grounded / Workflow / Agent / HITL
Qualitätsziele · Cost/Latency Envelope	… · …
Top Failure Modes	1. … 2. … 3. …

Entscheidung — primäre Stufe

1. Prompt-only
2. Prompt + Structured Validation
3. RAG / Grounding
4. Tools + fester Workflow
5. Produkt-Agent (Loop)
6. Fine-Tuning / Distillation
7. Custom Train / Pretrain (selten — extra begründen)

Kombinationen optional (z. B. 2+3). Nicht in Scope: …

Begründung (Kriterien): Qualität/Failures · Datenlage · Ops-Last · Kosten · Latency · Time-to-value · Reversibilität · Security/Privacy.
Climb Signal: warum nicht die nächstniedrigere Stufe.

Alternativen (verworfen): niedrigere Stufe · höhere Stufe · kein LLM.

Follow-ups (verbindlich, Auszug)

• Eval-Plan / Golden-Set-Update — Owner · Gate
• Observability: adaptation_rung, Versionen, Tokens/Steps
• Security-Review bei Stufe ≥ 3–5
• Bei Agent / RAG: jeweilige Checklisten in checklists/
• Tool-Contracts bei Stufe ≥ 4

Review-Trigger: Eval-Regression · Last-/Kosten-Sprung · neuer Failure Mode · Compliance · spätestens Datum/Sprints.

---

A.3 ADR: Modellwahl und Hosting

Datei: templates/adr-model-hosting.md
Kapitel: 09 — Modelle und Routing
Wann: pro Feature/Capability oder als Plattform-Default. Preise/Limits nur mit Stand Monat Jahr, wenn Zahlen genannt werden — Tiers schlagen Rankings.

Zweck: Primary/Fallback, Routing, Hosting und Residenz entscheiden; Pinning und Change-Prozess erzwingen.

Snapshot

Status · Datum · Autoren · Reviewer: …

Kontext

Feld	Inhalt
Feature / Capability · Feature-Spec	… · …
Adaptation-Stufe (Kap. 08)	1–7 / Kombi · Adaptation-ADR: …
Workload	Interactive / Async / Batch · QPS/Peak: …
Latency-Budget · Cost Envelope	p95 final/first-token · € oder Tokens pro Task
Datenklassen · Residenz	… · …
Top Failure Modes	…

Entscheidung

Dimension	Wahl	Details
Model-Tier (Primary)	Fast/Cheap · Balanced · Strong · Specialized	…
Primary provider / model_id	…	pin: ja · Version/Stand: …
Fallback	keins · same-tier · other provider · degraded	…
Routing	Single · Task-static · Cascade · Canary	Regel: …
Escalation (Cascade)	Signale: …	Cap · Budget
Hosting	API Provider · Self-Host · Hybrid	wo was
Region / Residenz	…	…

Optional Hybrid-Skizze: Default / Escalate / Embeddings / Degraded.

Trade-offs: Qualität · Latency · Kosten · Privacy · Ops · Vendor-Lock-in.
Warum nicht Strong-by-Default / nur Self-Host: …

Verbindliche Follow-ups (Auszug)

• model_id + Prompt-Version in Config/Traces; kein latest in Prod
• Eval-Gate deckt Primary und Fallback ab
• Cost-Accounting: feature_key, model_id, routing_reason
• Alerts: Latency, Error-Rate, €/Task, Fallback-Rate
• Change-Prozess: model-change-checklist.md
• DPA/Residenz; bei Self-Host: Capacity, Patch-Owner, On-Call

Review-Trigger: Model-Update · Last-/Kosten-Sprung · Residenz-Änderung · Fallback-Rate/Quality-Drop · spätestens Datum.

---

A.4 Eval-Plan

Datei: templates/eval-plan.md
Kapitel: 17 — Evaluation und Testing (Online/Shadow ergänzend 18)
Wann: sobald es eine Capability mit Qualitätsversprechen gibt — ideal parallel zur Feature-Spec, spätestens vor Go-Live.

Zweck: Golden Set, Metriken, Release-Gates und Online-Signale mit Owner und Rhythmus fixieren. Qualität ohne Plan ist Meinung.

Snapshot

Feature / Capability: …

Offline Eval

Item	Detail
Golden Set	Größe, Herkunft, Ownership
Split	train/dev nicht mit FT vermischen, falls FT
Metrics	Exact match / F1 / Task success / Citation precision / …
LLM-as-Judge	ja/nein — Grenzen und Kalibrierung
Human Eval	Stichprobe, Rubrik, Inter-Rater

Gates (CI / Release)

Gate	Schwelle	Blockt Release?
Regression vs. Baseline	…	ja/nein
Safety suite	…	ja
Latency smoke	…	…
Cost smoke	…	…

Online Eval

• Shadow / Canary: …
• Feedback-Signale: …
• Alerting bei Quality Drop: …

Owner und Rhythmus

• Wer reviewed Golden-Set-Änderungen?
• Wie oft re-eval nach Model-Update?

---

A.5 Tool-Contract

Datei: templates/tool-contract.md
Kapitel: 13 — Tools und Function Calling
Wann: bevor das Schema ins Modell wandert — für jedes Tool mit Side Effects oder AuthZ, spätestens bei Ladder-Stufe ≥ 4.

Zweck: Vertrag zwischen Harness und Tool: Input-Schema, Fehlercodes, Rechte, Idempotenz, Security-Checks. Das Modell sieht die Beschreibung; die Runtime erzwingt den Contract.

Snapshot

Name und Zweck

• Name: …
• Beschreibung (fürs Modell): …
• Owner-System: …

Schema (Input) — JSON Schema (Auszug)

{
  "type": "object",
  "properties": {},
  "required": []
}

Output / Errors

Code / Condition	Bedeutung	Retry?
success	…	—
validation_error	…	nein
not_found	…	nein
permission_denied	… (generisch)	nein
timeout	…	ja (bounded)

Permissions & Side Effects (Klasse steuert Allowlist/HITL)

• read-only · write-internal · money/rights · external comms · irreversible
• AuthZ · Idempotency Key · Rate limits

Security

• Input validation (beyond schema)
• SSRF / path traversal
• Logging ohne Secrets

---

A.6 Model- / Prompt-Change-Checklist

Datei: templates/model-change-checklist.md
Kapitel: 24 — Wartung und Model Lifecycle
Wann: jeder produktive Wechsel von Model-ID, Prompt-Version, Routing-Regel oder Provider-Default — nicht nur „Major Releases“.

Zweck: Change behandeln wie Breaking Change: dokumentieren, offline grün, rollout kontrolliert, online nachsehen.

Snapshot

Vor dem Change

• Änderung dokumentiert (Prompt-ID / Model-ID / Version)
• Offline Eval gegen Golden Set grün (Gates)
• Safety suite grün
• Cost estimate (Token, Routing)
• Rollback-Plan definiert
• Stakeholder informiert (falls User-visible)

Rollout

• Shadow traffic (optional)
• Canary mit Qualitätsmetriken
• Alerts für Quality / Cost / Latency aktiv
• Full rollout nur nach Canary-DoD

Nach dem Change

• Online Metrics 24–72h beobachtet
• Golden Set ggf. um neue Edge Cases erweitert
• Postmortem nur bei Incident — sonst Changelog-Eintrag

---

A.7 Production Ready (AI Feature)

Datei: templates/production-ready-checklist.md
Kapitel: quer 17–25 (Qualität, Security, Ops, Incident)
Wann: Go-Live-Gate bzw. vor Aufhebung des Feature-Flags für Nutzerverkehr.

Zweck: Spec, Eval, Architektur, Security und Betrieb in einer Liste — „Demo läuft“ ist kein Ready.

Snapshot

Spec & Ownership

• Feature-Spec mit messbaren Success/Failure Criteria
• Named Owner für Prompt, Eval, Model, On-Call

Qualität

• Golden Set + Offline Gates
• CI blockt Regressionen (oder klar definiertes Warn→Block-Datum)
• Human-Stichprobe für kritische Flows

Architektur

• Adaptation-ADR dokumentiert
• Structured Output / Validation wo nötig
• Fallbacks (Model, Rule-based, Human)

Security & Privacy

• Threat Model (Injection, Leakage, Tool Abuse)
• Input/Output Guardrails
• Logging redaction; keine Secrets im Prompt-Log
• Data residency / retention geklärt

Betrieb

• Tracing (Prompt/Retrieval/Tool/Token)
• Cost + Latency Dashboards und Alerts
• Rate limits / Budget Caps
• Model-Change-Checklist im Release-Prozess
• Incident-Runbook verlinkt

Ergänzende Kurz-Checklisten (nicht hier verdoppelt): checklists/observability-minimum.md, checklists/security-review-ai.md, u. a.

---

A.8 Runbook: AI-Incident

Datei: templates/incident-runbook-ai.md
Kapitel: 25 — Incident Response
Wann: pro kritischer Capability ausfüllen und üben — bevor der erste Quality-Drop oder Cost-Spike kommt.

Zweck: AI-spezifische Symptome (Halluzination, Injection, Tool-Abuse, Cost Loop) mit denselben SE-Reflexen: stabilisieren, Evidence, Diagnose, Fix-Forward/Rollback, Learning.

Snapshot

Meta: Capability · Owner · SEV-Link · letzte Tabletop-Übung

Symptome / Klasse (wählen; kanonisch Kap. 25)

• Safety / Security (Policy, Leakage, Injection, Tool-Abuse)
• Cost spike
• Quality drop / Silent Degradation / erhöhte Halluzinationen
• Latency / Timeouts
• Provider outage / Rate-Limit-Sturm
• Data / Index (Citations, leere Hits, Index-Pin)

Sofortmaßnahmen

1. Stabilisieren: Traffic drosseln / Feature-Flag / Fallback-Modell
2. Stop-the-bleed: betroffene Tools deaktivieren, Budget Caps
3. Kommunizieren: Status-Page / Intern-Channel
4. Evidence: Traces, Prompt-Version, Model-ID, Sample-Outputs sichern (redacted)

Kill-Switches & Rollback (Tabelle): Feature-Flag · Tool-Deny · Budget Cap · Model/Prompt-Pin · Degraded Fallback — je Wo / Wer darf / Hinweis.

Dashboards & Evidence: Links Quality/Cost/Latency/Errors/Tools; Evidence-Pack + ACL; Pflichtfelder feature_key, model_id, prompt_version, request_id.

Kontakte & Eskalation: Capability-Owner · Platform/Model · Security · Legal/Privacy · SEV-Pfad.

Diagnose-Checkliste

• Welches Model/Prompt/Deploy seit wann?
• Provider-Status / Rate Limits?
• Retrieval-Index frisch / korrupt?
• Guardrails deaktiviert oder umgangen?
• Eval-Regression reproduzierbar offline?
• Cost: Top feature_key / Tenant / model_id?

Resolve & Follow-up

• Rollback oder Fix-Forward? (Rollback warm)
• Golden Set erweitern
• Postmortem mit Action Items (Owner, Datum)
• Runbook/Checklist härten

---

Checklisten (separat)

Die lebenden Checklisten (Ampel, RAG, Agent-Readiness, Security-Review, Observability-Minimum, Team-Onboarding) liegen unter checklists/, nicht unter templates/. Überblick und Lesepfade: Anhang E. Im PDF können Anhänge knapper sein als die Dateien im Repo — Quelle der Wahrheit bleibt das Dateisystem.

---

Key Takeaways

• Repo vor PDF: arbeiten mit templates/; dieser Anhang ist Snapshot und Lesestütze.
• Spec vor Prompt: ohne messbare Kriterien und Failure Modes steuert die Demo die Architektur.
• ADRs für teure Stufen: Adaptation und Model/Hosting explizit entscheiden, pin-en und reviewen.
• Gates und Contracts erzwingen Qualität: Eval-Plan, Tool-Contracts und Production-Ready sind Release-Artefakte, keine Deko.
• Change und Incident gehören zum Feature: Model-Change-Checklist und AI-Runbook vor dem ersten Produktionsbrand.