ki-engineeering/07-architektur-landkarte.md

Architektur-Landkarte

Spec und Ampel stehen. Im Board taucht trotzdem der Satz auf: „Wir bauen einen Agenten.“ Manche meinen Chat-UI, manche einen Tool-Loop, manche nur „LLM hinter dem Endpoint“. Drei Sprints später steckt Business-Logik im System-Prompt, Control Flow im Framework-Magic und niemand kann auf einem Whiteboard zeigen, wo das System entscheidet und wo es nur vorschlägt.

Das ist kein Prompt-Problem. Das ist fehlende Architektur. Ohne Landkarte wird jedes Feature zur Demo-Architektur: ein Modellaufruf, Hoffnung, und später ein Incident.

These 5 / Kern in einem Satz: Architektur vor Prompt heißt: zuerst Control Flow, Boundaries und Application Pattern festlegen — und den LLM-Pfad als eingegrenzte, orchestrierte Komponente einbauen, nicht als unsichtbare Business-Logik.

Dieses Kapitel liefert die Karte. Die Adaptation Ladder (Prompt → Structured → RAG → Tools/Workflow → Agent → Fine-Tune → Train) folgt in Kapitel 08; hier geht es um wo und wie der Flow läuft, nicht um die feine Stufenwahl.

---

Bridge: Klassisches SE → AI Engineering

Du kennst Architektur schon: Schichten, Bounded Contexts, Sync/Async, Side-Effect-Grenzen. Mit Foundation Models kommt eine zweite Strömung ins Bild — LLM Flow — die du nicht mit dem deterministischen Control Flow vermischen darfst.

Klassisches SE	In AI Engineering …
Request → Service → DB → Response	Request → Orchestrierung → (optional) Modell/Tools → Validierung → Response/Wirkung
Business-Regeln im Code	Harte Regeln und AuthZ im Code; Modell liefert Sprache, Extraktion, Vorschläge
Ein Control Flow pro Use Case	Control Flow (Code, State, Policies) und LLM Flow (Context → Generate → ggf. Tool-Runden)
Layered / Hexagonal Architecture	Production Stack: UX, Orchestrierung, Adaptation, Model Access, Context/Data, Eval/Guardrails, Observability & Cost
„Welches Framework?“	Zuerst Application Pattern und Schnitt; Framework ist Implementierungsdetail
Side Effects hinter Service-API	Side Effects hinter Policy + Idempotenz; Modell löst sie nicht „einfach so“ aus
Architekturdiagramm ohne Runtime-Kosten	Diagramm inkl. Token-, Roundtrip- und Loop-Budget (T7)

Die Brücke: dieselbe Disziplin (Grenzen, Ownership, Failure Modes) — mit der expliziten Regel: was garantiert sein muss, lebt im Control Flow; was variieren und formulieren darf, lebt im LLM Flow.

---

Control Flow vs. LLM Flow

Zwei Pfade, die in jedem Production-Feature vorkommen — auch wenn Teams nur einen sehen.

Control Flow (Code besitzt die Wahrheit)

• Routing, AuthN/AuthZ, Feature-Flags, Timeouts
• State-Maschinen, Queues, Retries mit Budget
• Schema-Validierung, Business-Rules, Persistenz
• Entscheidung: darf eine Wirkung eintreten (Schreiben, Buchen, Mail senden)?
• Fallback: Template, Regelwerk, Mensch, „unable“

Deterministisch im Rahmen eurer Spec. Reviewbar per Diff. Testbar mit klassischen Tests plus den Gates um den Modellpfad.

LLM Flow (Modell besitzt Vorschlag und Formulierung)

• Context-Aufbau (Instruktionen, Retrieval, Memory, Tool-Results)
• Generierung / Structured Output
• optional: Tool-Calls und weitere Modellrunden
• Formulierung, Klassifikation, Extraktion, Plan-Vorschlag

Probabilistisch (T2). Qualität hängt am Context (T4). Ohne Einklammerung durch Control Flow wird der LLM Flow zur heimlichen Orchestrierung — und Incidents werden zu Prompt-Debugging.

Die Trennlinie in einem Satz

LLM Flow schlägt vor und formuliert.
Control Flow prüft, begrenzt, entscheidet und wirkt.

Wenn du die Linie nicht ziehen kannst, hast du noch keine Architektur — nur einen Modellaufruf.

Mini-Beispiel: Ticket-Triaging

Schritt	Flow
Request annehmen, Tenant prüfen	Control
ähnliche Tickets + Policy-Snippet laden	Control (+ Retrieval als Datenlieferung)
Kategorie, Priorität, Kurzsummary vorschlagen	LLM
Schema prüfen, erlaubte Kategorien erzwingen	Control
bei Unsicherheit: Queue „Mensch“; sonst Label schreiben	Control
Telemetrie, Sample für Eval	Control

Das Modell „triagiert“ nicht das System. Es füllt ein Contract; das System triagiert.

---

Application Patterns

Patterns sind Schnittmuster, keine Framework-Namen. Wähle das dünnste, das Spec und Failure Modes trägt. Ladder-Details (wann RAG, wann Tools) → Kapitel 08.

1. Single-Shot Assist (ein Aufruf, keine Wirkung)

Klassifikation, Extraktion, Umschreiben, Zusammenfassung ohne Side Effects.

• Control: Input-Filter, Schema, Reject/Repair, Anzeige als Entwurf
• LLM: ein Generate-Schritt
• Passt wenn: Grün/Gelb, begrenzter Scope, messbares Format

2. Generate-then-Validate

Modell erzeugt; Code validiert hart (Schema, Regeln, Allowlist). Bei Fail: Repair mit Cap oder Fallback.

• Control: Validator, Retry-Budget, Fallback-Pfad
• LLM: Generate (+ optional Repair-Prompt)
• Passt wenn: Structured Output Pflicht; freie Prosa als API zu riskant

3. Grounded Answer (RAG-gestützt)

Antwort an abgerufene Quellen koppeln; Citations oder Refuse bei fehlender Evidenz.

• Control: Retrieval-Query, Rank/Filter, Grounding-Check, „keine Quelle → keine Behauptung“
• LLM: Antwort auf Basis gelieferter Snippets
• Passt wenn: Fakten domäne; Halluzination ist P0-Failure (Kapitel 12)

4. Tool-Workflow (Pipeline, fester Graph)

Feste Schritte im Code: z. B. extrahieren → API lesen → Entwurf → User bestätigt → schreiben. Modell an benannten Stationen, nicht als freier Loop.

• Control: Graph/State, Tool-Permissions, Idempotenz, HITL-Gates
• LLM: einzelne Knoten (parse, draft, classify)
• Passt wenn: Ablauf bekannt; Wirkung kontrolliert — oft besser als „Agent“

5. Produkt-Agent (Loop mit Stopps)

Modell wählt Tool-Schritte in einer Schleife, bis Ziel, Limit oder Mensch.

• Control: max steps, Budget, erlaubte Tools, Escape Hatches, Audit
• LLM: Planen und Tool-Argumente innerhalb der Policy
• Passt wenn: Varianz des Pfads echt nötig und Spec/Eval das tragen (Kapitel 14, agent-readiness.md)

Produkt-Agent ≠ Coding-Agent (ki-praxis). Hier: Nutzer und Business im Produkt; anderes Threat Model und andere SLOs.

6. Human-in-the-loop als First-Class Pattern

Nicht Nachgedanke: vor riskanter Wirkung immer Mensch oder zweite deterministische Freigabe.

• Control: Approval-Queue, Timeout, Default-Deny
• LLM: Vorschlag, Begründung, Diff zum Status quo
• Passt wenn: Geld, Rechte, Außenwirkung, Regulierung — Gelb mit Zähnen

Pattern-Wahl (Decision Frame)

Wenn …	dann eher …	vermeide …
ein Format, keine Tools	Single-Shot + Validate	Agent-Loop
Fakten aus Korpus	Grounded Answer	freies Wissen ohne Quellen
bekannter Business-Ablauf	Tool-Workflow (Pipeline)	offenen Agent „der den Prozess erfindet“
unbekannte Schrittfolge, hohes Tool-Risiko	Agent nur mit Caps oder Pipeline + HITL	Agent ohne Budget/Permissions
harte Korrektheit / Policy	Control Flow only (Ampel rot)	LLM als Regel-Engine

Faustregel: Steige im Pattern erst auf, wenn das dünnere an messbaren Failure Modes scheitert — nicht weil der Blogpost „Agents“ sagt (T5, T6).

---

Production Stack (Skizze)

Die Schichten sind Verantwortlichkeiten, keine Pflicht-Microservices. Frameworks mappen darauf unterschiedlich; die Fragen bleiben.

┌─────────────────────────────────────────────────────────┐
│  UX / Channel     Chat, Formular, API-Client, Batch-Job │
├─────────────────────────────────────────────────────────┤
│  Orchestrierung   Control Flow, State, Flags, Timeouts  │
│  (Harness)        Validate / Repair / Fallback / HITL   │
├─────────────────────────────────────────────────────────┤
│  Adaptation       Prompt-Contracts, RAG, Tools, Agent-  │
│                   Policies  (Stufen: Kap. 08)           │
├─────────────────────────────────────────────────────────┤
│  Model Access     Routing, Tiers, Fallback-Provider,    │
│                   Version-Pin  (Kap. 09)                │
├─────────────────────────────────────────────────────────┤
│  Context & Data   Retrieval-Korpus, Memory, Caches,     │
│                   PII-Redaction  (Kap. 10)              │
├─────────────────────────────────────────────────────────┤
│  Eval & Guardrails  Golden Sets, Online Samples,        │
│                     Input/Output/Policy-Gates (17–19)   │
├─────────────────────────────────────────────────────────┤
│  Observability &    Traces, Tokens, Quality Signals,    │
│  Cost Control       Budgets, Alerts (22–23)             │
└─────────────────────────────────────────────────────────┘
         Security / Privacy / Ownership durchziehen (T8, T10)

Was jede Schicht besitzen muss

Schicht	Typische Artefakte	Häufiger Fehler
UX / Channel	Framing („Entwurf“), Streaming-UX, Async-Status	Orakel-UI ohne Unsicherheit
Orchestrierung	State-Machine, Caps, Kill-Switch	Framework-Default = Architektur
Adaptation	Prompt-Version, Tool-Contracts, Index-Version	alles im einen System-Prompt
Model Access	Model-ID pin, Tier-Regeln, Fallback	„immer stärkstes Modell“
Context & Data	Datenklassen, Retention, Cache-Keys	PII und Secrets im Prompt-Log
Eval & Guardrails	Gates vor Release und nach Model-Change	Demo als Qualitätssignal
Obs & Cost	feature key, €/Task, p95	Kosten erst bei Rechnung

Harness in diesem Buch: die Software-Schicht ums Modell (Orchestrierung + Policies + Telemetrie) — kein Produktname. Orchestrierung im Detail: Kapitel 16.

Sync vs. Async (kurz)

Modus	Wann	Architektur-Hinweis
Synchron / interaktiv	Nutzer wartet; enges Latency-Budget	wenig Roundtrips; Streaming optional; p95 in Spec
Async / Batch	lange Contexts, viele Tools, Nachtschicht	Queue, Idempotenz, Status-API; LLM Flow entkoppelt von UX-Thread

Application Pattern und Latency-Envelope aus der Spec (Kapitel 06) entscheiden den Modus — nicht der erste Prototyp im Notebook.

---

Patterns und Trade-offs

Pattern: Deterministischer Kern, probabilistischer Rand

AuthZ, Preise, Kontostände, „darf buchen“ — Code. Sprache, Prioritätsvorschlag, Mail-Entwurf — LLM. Hybrid aus Kapitel 05 wird zur Topologie, nicht nur zur Ampel-Farbe.

Trade-off: mehr Schnittstellen und Mapping-Code; dafür reviewbare Garantien und kleinere Failure Surface am Modell.

Pattern: Thin Orchestration, dicke Contracts

Orchestrierung bleibt lesbar: wenige klare Schritte, explizite Caps. Substanz steckt in Schemas, Tool-Contracts, Policies und Eval — nicht in 400 Zeilen Prompt-Prosa.

Trade-off: weniger „magische“ One-Shot-Prompts; dafür diffbare Änderungen und testbare Grenzen (tool-contract.md).

Pattern: Ein Diagramm vor dem ersten Production-Prompt

Whiteboardsession: Kästen für Control vs. LLM, Pfeile für Side Effects, Notiz zu Budget und HITL. Erst dann Prompt-Repo und Framework-Wahl.

Trade-off: ein bis zwei Stunden „langsam“; spart Wochen Pattern-Hopping.

Decision Frame: Welches Application Pattern?

Dominante Spec-Sorge	Pattern-Tendenz	Stack-Fokus
Format/Extraktion	Single-Shot + Validate	Contracts, Eval-Schema
Fakten / Quellen	Grounded Answer	Retrieval, Citations, Refuse
Bekannter Prozess + Wirkung	Tool-Workflow	State, Permissions, HITL
Offene Schrittfolge	Produkt-Agent (eng)	Caps, Audit, agent-readiness
Nur Regeln / Lookups	kein LLM-Pattern	Control Flow only

Unklar zwischen Workflow und Agent? Default Workflow. Agent ist die teurere Runtime (Varianz × Steps × Tokens) — begründungspflichtig in Spec oder ADR.

Trade-off: Flexibilität vs. Steuerbarkeit

Mehr Agent / freier Loop	Mehr Pipeline / Single-Shot
handhabt unbekannte Pfade	vorhersagbare Kosten/Latenz
schwerer zu evalen end-to-end	Golden Sets pro Knoten machbar
größere Injection-/Abuse-Fläche	kleinere Tool-Oberfläche
beeindruckt in Demos	überlebt On-Call

Wähle Steuerbarkeit, bis Evidenz Flexibilität erzwingt.

---

Anti-Patterns

Anti-Pattern	Symptom	Besser
Chat als Architektur	Ein Thread = Business-Prozess	Pattern + State außerhalb des Transcripts
Agent by Default	Jedes Ticket wird „Agent“	dünnstes Pattern; Ladder in Kap. 08
Prompt-as-Control-Plane	Policies nur im System-Prompt	Policies im Code; Prompt für Sprache/Format
Flow-Vermischung	unklar, ob Code oder Modell „entschieden“ hat	explizite Trennlinie; Logs mit decision_source
Framework-First	Stack-Wahl vor Use-Case-Schnitt	Pattern und Stack-Fragen zuerst; Lib danach
Alles in einer Schicht	UX ruft Provider-SDK direkt	Orchestrierung + Model Access trennen
Side Effects im LLM-Kopf	Modell „soll die Mail senden“ ohne Gate	Tool nur nach Policy/HITL; Idempotenz
Kein Budget im Diagramm	Architektur ohne Token/Step-Limits	Caps als First-Class Kanten im Flow
Coding-Agent-Kopie	Produkt-Loop wie Dev-Harness	Produkt-Threat-Model; ki-praxis nicht 1:1 übernehmen

---

Production Notes

Cost. Application Pattern dominiert Unit Economics stärker als Prompt-Feinschliff: jeder Agent-Step und jedes unnötige Full-Context-RAG multipliziert. Pattern und Caps gehören in die Spec-Envelope (T7), nicht in die erste Kostenüberraschung.

Latency. p95 ≈ Summe aus Retrieval, Modell, Tool-Roundtrips und Validierung. Single-Shot hält Budgets; freie Loops sprengen sie. Async, wenn die Spec es erlaubt — nicht als stiller Default hinter einem Spinner.

Observability. Traces spannen beide Flows: orchestration_step, prompt_version, model_id, Retrieval-IDs, Tool-Name, Token-Usage, validate_ok / repair count. Ohne das sind „Control vs. LLM“-Debates nur Meinungen. Minimum: observability-minimum.md.

Security. Trust Boundaries an jeder Stelle, wo untrusted Text den LLM Flow betritt (Nutzer, Tickets, abgerufene Docs, Tool-Output). Least Privilege für Tools; AuthZ nie an den LLM Flow delegieren (T8). Review: security-review-ai.md.

Lifecycle. Pattern- und Stack-Entscheidungen versionieren (kurz im Feature-Spec oder ADR). Model-Update ändert oft nur Model Access — kann aber Grounding und Tool-Verhalten verschieben: Eval-Gate und Canary bleiben Pflicht (T9). Owner für Orchestrierung und für Prompt/Eval benennen (T10).

---

Key Takeaways

• Architektur vor Prompt (T5): zuerst Control Flow, Boundaries und Application Pattern — dann Formulierungen und Frameworks.
• Control Flow vs. LLM Flow: Code prüft, begrenzt und wirkt; das Modell schlägt vor und formuliert.
• Application Patterns (Single-Shot → Validate → Grounded → Workflow → Agent → HITL) von dünn nach dick wählen; Agent ist Ausnahme mit Caps.
• Der Production Stack verteilt Verantwortung (UX/Channel, Orchestrierung, Adaptation, Model Access, Context, Eval/Guardrails, Observability & Cost) — Security und Ownership durchziehen.
• Ladder und Model-Tiers kommen als Nächstes (08, 09); ohne Landkarte optimierst du die falsche Schicht.

Praktische nächste Schritte

1. Nimm ein laufendes oder geplantes AI-Feature und zeichne zwei Farben: Control Flow vs. LLM Flow — inkl. Side Effects und HITL.
2. Ordne es einem Application Pattern zu; schreibe in einem Satz, warum nicht das dünnere.
3. Mappe die Kästchen auf den Production Stack; markiere Lücken (z. B. kein Eval, kein Budget Cap, UX ruft SDK direkt).
4. Trage Pattern und groben Stack in die Feature-Spec (templates/ai-feature-spec.md, Architektur-Skizze) ein.
5. Als Nächstes: Adaptation-Stufe begründen — Entscheidungsrahmen: Adaptation und Vorlage adr-adaptation.md.