ki-engineeering/08-entscheidungsrahmen-adaptation.md

Entscheidungsrahmen: Adaptation

Die Landkarte steht: Control Flow und LLM Flow sind getrennt, ein Application Pattern ist gewählt (Kapitel 07). Trotzdem hört man im Refinement: „Wir fine-tunen unser Modell“ — obwohl es noch kein Golden Set gibt. Oder: „Wir brauchen einen Agenten“ — obwohl ein Structured-Output-Aufruf den Job erledigen würde.

Adaptation ist der Hebel, mit dem ihr ein Foundation Model an euer Problem anpasst — ohne es von Grund auf zu trainieren. Die teure Frage ist nicht „welches Framework?“, sondern: welche Stufe lohnt jetzt, und was müsst ihr messen, bevor ihr höher klettert?

Kern in einem Satz: Die Adaptation Ladder ordnet Anpassungen von leicht/ reversibel (Prompt, Structured Output) zu schwer/ teuer (Fine-Tune, eigenes Training) — von unten starten, nur mit Evidenz steigen, und jede Stufe im Control Flow einklammern.

Lebende Entscheidung: templates/adr-adaptation.md. Voraussetzung: Ampel nicht rot (Kapitel 05), Spec mit Metriken und Failures (Kapitel 06).

---

Bridge: Klassisches SE → AI Engineering

In klassischem SE wählt ihr den leichtesten Baustein, der die Anforderung trägt: Config vor Code, Library vor Framework, Schema vor Engine. Dieselbe Ökonomie gilt für Adaptation.

Klassische Entscheidung	Pendant Adaptation
Config / Feature-Flag	Prompt-Version, Policy-Text, Few-Shots
Validierung an der API-Grenze	Structured Output + Schema-Reject/Repair
Cache / Read-Model / Search	RAG: Retrieval als Faktenlieferung
Integration zu Services	Tools / Function Calling mit Contracts
Workflow-Engine / Saga	fester Tool-Workflow oder begrenzter Produkt-Agent
Eigenes Modul / spezieller Service	Fine-Tuning / Distillation (selten)
Eigenes Produkt von null	Custom Train / Pretrain (fast nie Produkt-Default)
ADR bei teuren, irreversiblen Choices	adr-adaptation.md

Faustregel wie bei Dependencies: je höher die Stufe, desto mehr Daten-, Ops- und Rollback-Last — und desto stärker muss die Spec die Investition rechtfertigen.

---

Was „Adaptation“ hier meint

Adaptation = alles, womit ihr ein vortrainiertes Foundation Model produkttauglich macht:

• Kontext und Instruktionen (Prompting)
• strukturierte Verträge (Schemas)
• externes Wissen (RAG)
• kontrollierte Systemzugriffe (Tools)
• Schleifen und Workflows (Pipeline / Produkt-Agent)
• gelegentlich Gewichts-Anpassung (Fine-Tune, Distill)

Nicht Adaptation im Sinne dieses Buchs: Foundation Models von null pretrainen, Research-Architektur, „die KI neu erfinden“. Das ist ML Research / ML Engineering — Schnittstellen ja, Default-Pfad nein (T1).

Adaptation lebt in der Adaptation-Schicht des Production Stacks (Kapitel 07); der Control Flow drumherum bleibt euer.

---

Die Adaptation Ladder

Von unten nach oben: Time-to-value sinkt selten linear — Kosten und Irreversibilität steigen oft sprunghaft. Kombiniert Stufen, wo nötig (z. B. RAG + Tools); entscheidet aber explizit, welche Stufe den Haupt-Hebel trägt.

        ▲  teurer · schwerer reversibel · mehr Ops
        │
   [7]  Custom Train / Pretrain     (fast nie)
   [6]  Fine-Tuning / Distillation
   [5]  Produkt-Agent (freier Tool-Loop)
   [4]  Tools + fester Workflow
   [3]  RAG / Grounding
   [2]  Prompt + Structured Validation
   [1]  Prompt-only (Entwurf, niedrige Wirkung)
        │
        ▼  schneller · reversibler · leichter zu evalen

Stufe 1 — Prompt-only

Was: System-/User-Prompt, Few-Shots, Rollen, Stil. Ausgabe oft Freitext.

Wann: Entwürfe, interne Assistenz ohne Side Effects, Exploration, UX-Copy — Wirkung gering oder Mensch liest mit.

Braucht: Prompt-Versionierung, rudimentäres Eval (auch Stichproben), klares Framing in der UX.

Grenzen: keine Faktengarantie; Business-Regeln im Prompt sind Anti-Pattern (Kap. 07).

Vertiefung Interface-Design: Kapitel 11.

Stufe 2 — Prompt + Structured Validation

Was: Modell liefert JSON/Schema; Code validiert; bei Bruch Repair mit Cap oder Fallback.

Wann: Extraktion, Routing in endliche Labels, Formulare aus Freitext, alles was downstream Code konsumiert.

Braucht: Schema als Contract, Reject/Repair-Budget, Golden Set auf Feldebene.

Grenzen: Struktur ≠ Wahrheit. Ein valides JSON kann falsche Fakten enthalten.

Das ist der professionelle Default für die meisten grünen Produkt-Schnittstellen — nicht „Chat-Transcript als API“.

Stufe 3 — RAG / Grounding

Was: Zur Laufzeit relevantes Wissen holen (Suche, Hybrid, API) und dem Modell als Context geben; ideal mit Citations und Refuse ohne Evidenz.

Wann: Antworten sollen euren Korpus widerspiegeln (Docs, Tickets, Policies, Produktwissen); Halluzination ist P0.

Braucht: Korpus-Ownership, Chunking/Index-Version, Retrieval-Eval, „keine Quelle → keine Behauptung“, Privacy auf abgerufenen Snippets.

Grenzen: schlechtes Retrieval erzeugt überzeugend falsche Antworten mit Quellenoptik. RAG ist System, kein Vektor-DB-Kauf.

Vertiefung: Kapitel 12, rag-production-ready.md.

Stufe 4 — Tools + fester Workflow

Was: Modell (oder einzelne Knoten) ruft erlaubte Tools auf; Reihenfolge und Verzweigungen steuert primär der Code (Pipeline/State-Machine).

Wann: Lesen aus CRM, Preis aus API, Ticket anlegen nach Bestätigung — bekannter Prozess, kontrollierte Wirkung.

Braucht: Tool-Contracts, least privilege, Idempotenz, HITL vor riskanten Writes, Observability pro Tool.

Grenzen: „ein bisschen Agent“ ohne Caps rutscht in Stufe 5. Pipeline zuerst, wenn der Ablauf bekannt ist (Kapitel 07 Pattern 4).

Vertiefung Tools: Kapitel 13; Orchestrierung: Kapitel 16.

Stufe 5 — Produkt-Agent (Loop)

Was: Modell wählt in einer Schleife Tools/Schritte bis Ziel, Limit oder Mensch.

Wann: Pfad echt nicht a priori festlegbar; Tool-Wahl kontextabhängig; Team trägt Agent-Ops (Eval von Trajectories, Caps, Kill-Switch).

Braucht: agent-readiness.md, max steps/cost, Audit, enge Tool-Allowlist, oft HITL.

Grenzen: Kosten × Varianz × Latency multiplizieren mit Steps. Coding-Agents (ki-praxis) sind kein Copy-Paste-Threat-Model für Produkt-Agents.

Vertiefung: Kapitel 14.

Stufe 6 — Fine-Tuning / Distillation

Was: Gewichte anpassen (oder kleines Modell aus großem destillieren) für Format, Stil, Domänenverhalten, Latenz/Kosten.

Wann: nach messbarem Plateau auf Stufen 1–5: z. B. stabiles Format bei hohem Volumen, Domänensprache, kleineres Modell soll „gut genug“ das große ersetzen — mit Daten und Eval, die das belegen.

Braucht: gelabelte/ kuratierte Daten, Trainings- und Eval-Pipeline, Versionierung der Adapter/Checkpoints, Regression-Suite, Owner für Datenqualität.

Grenzen: FT heilt selten fehlendes Knowledge besser als RAG; heilt nicht fehlende AuthZ; erhöht Ops-Last. Default der ehrlichen Praxis: meistens nicht — Details Kapitel 15.

Stufe 7 — Custom Train / Pretrain

Was: eigenes Foundation- oder Spezialmodell von Grund auf oder mit massivem Continue-Pretrain.

Wann: extrem selten in Produkt-AI-Engineering — strategische Differenzierung, radikale Residenz-/IP-Zwänge, Forschungsmandate. Nicht „unser Chatbot soll besser klingen“.

Braucht: ML Engineering, Kapital, Datenmoat, Jahre — nicht ein Sprint-Ziel aus dem AI-Feature-Backlog.

Wenn jemand Stufe 7 vorschlägt, bevor Stufe 2–3 evaluiert sind: Stopp, Spec und Ladder-Review.

---

Decision Frame: Welche Stufe — und wann steigen?

Startfrage (vor der Stufe)

1. Ampel? (rot → kein LLM; gelb → hybrid erzwingen)
2. Application Pattern? (Kapitel 07)
3. Was muss garantiert sein vs. was darf variieren?
4. Gibt es ein Eval, das den Aufstieg messen kann?

Ohne 4 ist „wir brauchen FT/Agent“ eine Meinung, keine Entscheidung (T3).

Schnellwahl nach Problemtyp

Problemtyp	Typische Startstufe	Erst steigen, wenn …
Entwurf / Umformulieren	1 Prompt	Struktur downstream nötig → 2
Extraktion / Routing	2 Structured	Fakten aus Korpus nötig → 3
Fragen über interne Docs	3 RAG	Live-Systeme lesen/schreiben → 4
Bekannter Fachprozess	4 Tools+Workflow	Pfad unmöglich vorab zu modellieren → 5
Offene Multi-Tool-Aufgabe	5 Agent (eng)	nur mit agent-readiness; sonst zurück zu 4
Format/Latenz/Kosten-Plateau	2–4 stabil	Messungen zwingen 6 FT/Distill
Eigenes Foundation Model	—	fast nie; ML-Eng-Track separat

Aufstiegs-Evidenz (Climb Signals)

Steige eine Stufe höher nur mit mindestens einem harten Signal:

Signal	Beispiel
Failure Mode ungelöst	Halluzination trotz Prompt → Grounding (3), nicht „längerer Prompt“
Contract bricht systematisch	Freitext unbrauchbar für Code → Structured (2)
Wissen veraltet/fehlt im Modell	Policies ändern sich wöchentlich → RAG (3), nicht FT als Wiki-Ersatz
Wirkung nötig	Lesen/Schreiben in Systeme → Tools (4), nicht „Modell soll so tun als ob“
Graph explodiert	40 Sonderfälle in der State-Machine, unwartbar → Agent (5) oder Scope schneiden
Unit Economics / Latenz	Starkes Modell zu teuer/langsam bei stabilem Task → Distill/FT (6) mit Eval-Parität
Plateau dokumentiert	Golden Set + Online-Metriken zeigen: Context/Tools ausgereizt

Abstiegs-Evidenz (Run Signals)

Zurück oder seitwärts, wenn:

• Kosten/Latenz die Spec sprengen und Scope nicht verhandelbar ist
• Eval auf höherer Stufe schlechter oder unmessbar wird
• Security-Review Tools/Agent nicht freigibt
• Team-Ownership für Index/FT/Agent-Ops fehlt (T10)

Abstieg ist Engineering, kein Gesichtsverlust.

Kombinationen (normal)

Kombination	Sinn
2 + 3	Structured grounded answers
3 + 4	RAG für Wissen, Tools für Live-Fakten/Aktionen
2 + 4	Pipeline-Knoten mit Schema, ohne freien Loop
4 + HITL	Wirkung erst nach Mensch — oft besser als 5
6 + 3	FT für Stil/Format, RAG weiter für Fakten (Fakten nicht „einfinetunen“)

Schreib die primäre Stufe ins ADR; Kombis als Konsequenz, nicht als Nebel.

---

Patterns und Trade-offs

Pattern: Lowest Competent Rung

Baue die niedrigste Stufe, die Spec-Metriken und Top-Failure-Modes adressiert. Optimiere dort (Context, Schema, Retrieval, Tool-Design), bevor du kletterst.

Trade-off: weniger Demo-Glanz; mehr Lieferbarkeit und Rollback-Fähigkeit.

Pattern: Measure Before Climb

Jeder Aufstieg braucht: Baseline-Metrik, Hypothese („RAG senkt Halluzinationsrate um …“), Eval-Update, Rollback-Plan.

Trade-off: ein Sprint „nur messen“ fühlt sich langsam an — spart FT- und Agent-Friedhöfe.

Pattern: Reversible by Default

Prompt, Schema, Index-Config, Tool-Allowlist, Feature-Flags sind diff- und flagbar. FT-Checkpoints und Agent-Policies brauchen dieselbe Disziplin (Version pin, Canary) — sonst ist Stufe 6 ein Einwegticket (T9).

Pattern: Hybrid schlägt Maximal-Adaptation

Deterministischer Kern (Regeln, APIs) + dünne Adaptation am Sprach-/Varianz-Rand schlägt oft „alles im Agenten“. Das ist Ampel-Gelb operationalisiert.

Decision Frame: RAG vs. Fine-Tune (Kurz)

Wenn …	eher …
Wissen ändert sich, muss zitierbar sein	RAG (3)
Format/Stil/Latenz bei stabilem Task, Wissen extern ok	FT/Distill (6) nach Plateau
beides	RAG für Fakten + optional FT für Form — nicht FT als Dokumentenspeicher
unsicher	RAG zuerst (reversibler, oft billiger in der Iteration)

Anhang-Matrix später ausführlicher; hier reicht die Produktregel.

Decision Frame: Workflow vs. Agent (Kurz)

Wenn …	eher …
Ablauf bekannt, Audit pro Schritt	Tools + Workflow (4)
Schrittfolge offen, Tool-Wahl dynamisch	Agent (5) mit Caps
strenge p95/€	4 oder Single-Shot; 5 nur mit Budget-Beweis
Team ohne Trajectory-Eval	nicht 5

Siehe agent-readiness.md.

---

Anti-Patterns

Anti-Pattern	Symptom	Besser
Ladder-Skipping	FT oder Agent im Kickoff, kein Golden Set	Stufe 2–3 + Eval zuerst
FT als Wiki	„Wir trainieren die Policies ein“	RAG + Policy im Code
Agent als Architekturersatz	freier Loop statt Spec und State	Pattern + Stufe 4, dann ggf. 5
Prompt-Maximalismus	8k Tokens Policy im System-Prompt statt Tools/RAG	Context-Diät; richtige Stufe
Ein ADR für alles	eine Ladder-Stufe für fünf Jobs	Stufe pro Capability/Schnitt
Framework = Stufe	„Wir nutzen Lib X, also sind wir Agent-first“	Stufe unabhängig vom Vendor wählen
Climb without Owner	niemand owns Index, Tool-Permissions oder FT-Daten	T10: Owner vor Aufstieg
Demo-Stufe	Stakeholder sahen Agent-Demo → Prod-Default	Ampel, Spec, Climb Signals
Keine Alternative im ADR	nur die gewählte Stufe dokumentiert	verworfene Stufen + Warum (lernt das Team)

---

Das ADR schreiben (kurz)

Nutze templates/adr-adaptation.md, sobald die Stufe teuer, riskant oder schwer reversibel wird — oder wenn das Team uneins ist. Für triviale Prompt-only-Entwürfe reicht ein Satz in der Feature-Spec; ab Tools/Agent/FT ist ADR Pflichtgefühl.

Mindestinhalt:

1. Kontext — Feature, Metriken, Ampel, Pattern
2. Entscheidung — primäre Stufe (+ Kombi)
3. Begründung — Qualität, Datenlage, Ops, Kosten, Time-to-value
4. Alternativen — mind. eine niedrigere Stufe und warum sie (noch) nicht reicht
5. Konsequenzen — Eval-Follow-ups, Observability, Security-Review
6. Review-Trigger — wann neu entscheiden (Model-Change, Last, Failure-Spike)

Die Feature-Spec bleibt Owner der Ziele; das ADR Owner der Hebel-Wahl.

---

Production Notes

Cost. Höhere Stufen multiplizieren: RAG (Retrieval + Tokens), Tools (Roundtrips), Agents (Steps), FT (Training + Serving + Iteration). Envelope aus der Spec gilt pro Stufe; Agent ohne Step-Budget ist offene Kreditkarte (T7).

Latency. Jede Stufe kann p95 verschieben. Structured Repair-Loops, Hybrid-Search, Tool-Ketten und Agent-Trajectories brauchen eigene Budgets — und ggf. Async (Kapitel 07).

Observability. Logge adaptation_rung (oder äquivalent), Prompt-/Index-/Tool-Versionen, Step-Count, Validate/Repair, Token- und Retrieval-Metriken. Sonst kannst du Climb Signals nicht belegen. Minimum: observability-minimum.md.

Security. Ab Stufe 3: untrusted Documents im Context. Ab Stufe 4–5: Tool Abuse und Injection-Pfade. FT: Trainingsdaten als Angriffs- und Leakage-Fläche. Security-Review skaliert mit der Stufe (security-review-ai.md, Kapitel 19).

Lifecycle. Prompt- und Index-Changes sind häufig; FT- und Agent-Policy-Changes brauchen dieselben Gates wie Model-Updates (Eval, Canary, Rollback — T9). ADR bei Stufenwechsel aktualisieren oder superseden.

---

Key Takeaways

• Adaptation Ladder = Prompt → Structured → RAG → Tools/Workflow → Agent → FT → Train; von unten, mit Evidenz.
• Lowest Competent Rung schlägt Demo-Maximalismus; Abstieg ist erlaubt und oft richtig.
• Structured Validation (Stufe 2) ist der Default an Code-Grenzen; RAG (3) für Fakten; Pipeline (4) vor Agent (5); FT (6) nur nach Plateau.
• Climb Signals sind messbare Failure Modes und Unit Economics — nicht Blogposts oder Vendor-Releases.
• Teure/irreversible Stufen: adr-adaptation.md + Owner + Eval-Follow-up.

Praktische nächste Schritte

1. Nimm ein Feature mit bestehender Spec und trage die primäre Ladder-Stufe plus eine verworfene Alternative in die Architektur-Skizze ein.
2. Prüfe Climb Signals: Welcher Failure Mode der Spec ist auf der aktuellen Stufe ungelöst? Wenn keiner — nicht steigen.
3. Bei Stufe ≥ 4 oder geplanter 5/6: fülle templates/adr-adaptation.md (Status Proposed) und lass Spec-Owner + Security kurz reviewen.
4. Lege Baseline-Eval fest (auch n=20), bevor du RAG-Index, Agent-Loop oder FT-Job aufsetzt (eval-plan.md).
5. Als Nächstes Model-Zugriff und Tiers: Modelle und Routing — erst nach sinnvoller Adaptation-Stufe, nicht davor.