ki-buch/teil-02-agenten-mcp/kapitel-05-fortgeschrittene-architekturen.md

Kapitel 5: Fortgeschrittene Agenten-Architekturen & Kontext-Management

Teil II · Von LLMs zu autonomen Agenten – MCP als zentrale Schicht

---

Die flache Tool-Schleife aus Kapitel 4 reicht für Demos – und zerbricht, sobald Fähigkeiten, Kontext und Parallelität wachsen. Dann entstehen die klassischen Anti-Muster: ein System-Prompt als Roman, 80 Tools im Window, „alle Agenten sehen alles“, und Memory, das nur die Chat-Historie ist. Skalierung ist kein Mehr an Tokens; sie ist Schnitt und Disziplin.

These: Fähigkeiten und Kontext skalierst du über Skills, Progressive Disclosure, geteilten vs. privaten Kontext, Memory-Server und Harness Engineering – nicht über ein größeres Window allein. Multi-Agent und Shared Stores lohnen bei Struktur und Parallelität, nicht bei jedem Bugfix.

Leitfrage: Wie skalierst du Fähigkeiten und Kontext, ohne Window zum Archiv und Prompt zum Monolithen zu machen?

Dieses Kapitel vertieft die Architektur-Brücke: hierarchische Muster, Router und Skills, State-Machines, CA-MCP und Shared Stores, Multi-Agent-Koordination, Knowledge-Base- und Graph-Muster, Kontext-Lifecycle und Harness-Techniken (Hooks, Permissions, Verify). Die Bausteine kehren in Kapitel 6 (Frameworks), 8 (Teams), 10 (Hands-on) und 11 (Production) wieder – hier lernst du sie als bewusste Wahl, nicht als Default-Stack.

Lernziele

Nach diesem Kapitel kannst du:

• fortgeschrittene Muster (hierarchische Agenten, Router, Supervisor, Swarm) einordnen und auswählen,
• Agent Skills entwerfen, versionieren und von Sub-Agenten sowie MCP-Tools abgrenzen,
• Progressive Disclosure als Kontext- und Skill-Ladestrategie anwenden,
• Harness Engineering als Disziplin verstehen (Hooks, Permissions, Sandbox, Checkpoints, Verify-Loops),
• erklären, warum geteilter vs. privater Kontext in Multi-Agent-Systemen kritisch ist,
• Context-Aware MCP (CA-MCP) und Shared Context Stores als Architekturbausteine skizzieren,
• persistentes Projekt-Memory über MCP-Server (Knowledge Graph, Decision Log, codebase-memory) entwerfen,
• Multi-Agenten-Koordination mit MCP als Kommunikations- und Kontext-Schicht planen,
• typische Failure Modes (Kontext-Drift, Tool-Kollision, Deadlocks) und Gegenmaßnahmen benennen,
• eine hierarchische Markdown-Knowledge-Base (AGENTS.md / CLAUDE.md-Pattern) entwerfen und pflegen,
• Codebase Knowledge Graph und Markdown-KB sinnvoll abgrenzen und hybrid kombinieren,
• Kontext-Lifecycle-Strategien anwenden (manuelles Compact, neue Session, persistente Decisions).

Schicht	In diesem Kapitel	Stand
Stabil	Shared Context vs. private Traces, Trust, Multi-Agent-Rollen	Prinzipien
Mittelstabil	Skills, Progressive Disclosure, CA-MCP, Hybrid-KB, Handoffs	Muster
Volatil	Framework-Bindings, Host-Skill-Pfade	Juli 2026 / Companion

Context Trace (TRACE-DEMO-1): Welche KB-Artefakte in den Trace gehören – Kap. 5.12 / Praxis Kap. 10.8.6 & 10.13.

---

5.1 Jenseits der flachen Tool-Schleife

Kapitel 4 hat den einzelnen Agenten mit Perceive–Reason–Act beschrieben. Sobald Aufgaben länger, riskanter oder teamähnlich werden, reicht eine flache ReAct-Schleife oft nicht:

Druck	Symptom der flachen Schleife	Architekturantwort
Lange Horizonte	verliert den Plan, wiederholt sich	hierarchische Planung, expliziter State
Viele Tools	falsche Tool-Wahl, Schema-Bloat	Router, Just-in-Time Toolsets
Spezialwissen	Generalist medioker überall	Spezialisten-Agenten
Parallelität	sequentiell zu langsam	Worker-Pool, begrenzte Parallel-Branches
Team-Workflows	ein Agent „spielt“ alle Rollen schlecht	Rollen + Shared Artifacts
Kontextexplosion	Window voller Traces	private Working Sets + Shared Store

Analogie: Ein flacher Agent ist ein Allround-Freelancer. Fortgeschrittene Architekturen sind eine Firma mit Rollen, Aktenschrank (Shared Context) und definierten Übergabeprotokollen – MCP als Hausverkabelung.

---

5.2 Hierarchische Agenten: Planner, Supervisor, Worker

Planner / Executor

• Planner: zerlegt Ziele, setzt Reihenfolge, definiert Done-Kriterien.
• Executor/Worker: führt enge Schritte mit lokalem Kontext aus.
• Replanner: greift bei Blockern ein (Test rot, fehlende Info, Policy-Verstoß).

Konzept-Plate: Multi-Agenten-Organisation

{ width=100% }

Supervisor-Pattern

Der Supervisor:

• vergibt Tasks,
• prüft Outputs gegen Contracts (Schema, Tests),
• eskaliert an Menschen,
• hält den kanonischen Projekt-State (nicht jeder Worker schreibt „seine Wahrheit“).

Wann hierarchisch?

Ja: Feature über mehrere Module, Migrations, Incidents mit Runbook. Nein: einzeilige Rename-Refactors – Overhead frisst Nutzen.

---

5.3 Router, Skills und Tool-Bundles

Statt einem Agenten 80 Tools und einen Roman als System-Prompt zu geben:

1. Intent-Router (kleines/schnelles Modell oder Regeln) wählt Skill.
2. Skill aktiviert ein Tool-Bundle + Resource-Allowlist + Playbook-Text.
3. Spezialist läuft mit schlankem Window.

from dataclasses import dataclass


@dataclass(frozen=True)
class Skill:
    name: str
    tool_servers: tuple[str, ...]   # MCP server ids
    resource_globs: tuple[str, ...]
    model: str


SKILLS = {
    "debug": Skill(
        name="debug",
        tool_servers=("repo", "ci", "tests"),
        resource_globs=("repo://**", "ci://**"),
        model="frontier-coding",
    ),
    "docs": Skill(
        name="docs",
        tool_servers=("repo", "memory"),
        resource_globs=("repo://docs/**", "memory://adr/**"),
        model="cheap-fast",
    ),
}


def route(intent: str) -> Skill:
    key = "debug" if "fail" in intent.lower() or "bug" in intent.lower() else "docs"
    return SKILLS[key]

Just-in-Time Tools und Selective Resource Exposure (Kap. 3) sind hier Pflicht, nicht Kür. Der folgende Abschnitt vertieft Skills als zentrales Harness-Konzept 2026.

---

5.4 Agent Skills – der moderne Ersatz für riesige Prompts

Skills sind modulare, on-demand geladene Fähigkeitspakete (Playbooks, Metadaten, optional Assets und empfohlene Tools) – der Gegenentwurf zum monolithischen System-Prompt. Progressive Disclosure hält den Catalog billig und lädt Tiefe erst bei Bedarf. Für Softwareteams skaliert das Dutzende Workflows (Review, Incident, Migration), ohne jedes Rename mit dem vollen Regelwerk zu belasten. Spätere Hands-on-Umsetzung: Kapitel 10.12.

Was ist ein Agent Skill?

Ein Skill ist ein modulares, wiederverwendbares Fähigkeitspaket für den Harness: Anweisungen, optional Scripts/Assets, Metadaten und oft eine empfohlene Tool-/MCP-Menge – geladen nur wenn relevant.

Analogie: Der Core-System-Prompt ist die Verfassung. Skills sind Fachgesetze und Checklisten pro Ressort – du nimmst das Baurecht mit, wenn du baust, nicht beim Steuerbescheid.

In Produkten heißen sie je nach Host Skills, Rules-Pakete, Commands, Playbooks oder Workflows. Das Architekturprinzip ist dasselbe: Progressive Disclosure statt Monolith.

Progressive Disclosure als Schlüsselkonzept

Konzept-Plate: Progressive Disclosure (Catalog → Skill → Assets)

{ width=100% }

Level	Was im Context Window landet	Wann
0 Catalog	Dutzende Skill-Namen + Kurzbeschreibungen (billig)	Session-Start / Intent
1 Body	volles Playbook des einen Skills	nach Auswahl
2 Assets	Beispiele, Templates, Scripts	bei Bedarf
3 Tools	Schemas nur der nötigen MCP-Tools	vor Act

Warum das in der Softwareentwicklung mächtig ist: Teams haben nicht „einen“ Workflow, sondern Dutzende – PR-Review, Migration, Incident, Flaky-Test-Jagd. Würdest du alle Playbooks in den Core-Prompt legen, zahlst du bei jeder Rename-Variable den vollen Preis und verwässerst die harten Regeln. Progressive Disclosure trennt Entdeckbarkeit (Catalog) von Ausführungstiefe (Body/Assets/Tools). Du skalierst Fähigkeiten, ohne das Context Window zum Archiv zu machen.

Praktisch heißt das: Der Router oder das Intent-Matching darf billig und breit sein; teuer und präzise wird es erst nach der Skill-Wahl – idealerweise mit nur den MCP-Tools, die dieser Skill wirklich braucht.

Aufbau eines guten Skills

Empfohlenes Repo-Layout (wie Dotfiles – versioniert, reviewbar):

.skills/   # oder .cursor/skills, .agents/skills, team-skills/
  secure-pr-review/
    skill.md          # Pflicht: Zweck, Wann, Schritte, DoD
    examples/
      finding.md
    scripts/          # optional: formatter, checker
      check_secrets.sh
  flaky-test-hunt/
    skill.md
  release-notes/
    skill.md

skill.md – Minimal-Template

# Skill: secure-pr-review

## Wann nutzen
Pull Requests mit Auth, Payments, User-Input oder neuen Dependencies.

## Nicht nutzen
Reine Typo-/Docs-PRs ohne Security-Relevanz.

## Voraussetzungen
- Diff verfügbar (git/MCP)
- CI-Status lesbar

## Schritte
1. Lade Diff und geänderte Entry-Points.
2. Prüfe Injection, AuthZ, Secret-Handling, Deserialisierung.
3. Mappe Findings auf Severity (high/medium/low).
4. Schlage konkrete Fixes vor – ohne Scope-Creep.

## DoD
- Mindestens die Checkliste unten abgehakt oder als N/A begründet
- Keine „LGTM“ ohne Diff-Bezug

## Checkliste
- ☐ User-Input validiert/escaped?
- ☐ AuthZ an jeder neuen Route?
- ☐ Secrets nicht geloggt/committed?
- ☐ Dependencies mit bekannter CVE-Lage?

## Tools / MCP (empfohlen)
- git.diff, security.scan (read), memory://adr/security-*

Skill-Ökosystem 2026 (Praxisbeispiele)

Skill-Klasse	Beispiele	Nutzen
Quality	pr-review, add-tests, type-tightening	Standardisierung
Security	secure-pr-review, dependency-audit	wiederholbare Härte
Ops	incident-triage, oncall-handoff	Runbook as Skill
Data/Migrate	postgres-migration, backfill-plan	riskante Flows bändigen
Docs	adr-writer, api-changelog	Konsistenz
Team-Dotfiles	interne acme-billing-conventions	Domänenwissen on-demand

Viele Teams behandeln Skills wie interne Open-Source-Pakete: SemVer, Changelog, Owner, Deprecation.

Skills bauen und versionieren (wie Dotfiles)

1. Im Repo (projektlokal) für domänenspezifische Skills
2. Im User-/Org-Dotfiles-Repo für persönliche oder firmenweite Skills
3. SemVer: Breaking Change am Playbook = major (Agent-Verhalten ändert sich)
4. Review: jede Skill-Änderung wie Code (besser: mit Eval-Case)
5. Pinning: Teams pinnen Skill-Bundle-Versionen in CI-Agenten

# Skizze: Skills als Git-Subtree / Submodul
git submodule add ../company-agent-skills .agents/skills

Skills vs. Sub-Agenten vs. MCP-Tools

{ width=100% }

Konzept	Ist …	Wann
Skill	Anweisungspaket (+ optional Scripts), meist kein eigener Prozess	wiederkehrende Workflows, Checklisten, Domänenwissen
Sub-Agent	eigener Agenten-Lauf (oft eigener Context/Prompt)	Isolation, Parallelität, starke Rollentrennung
MCP-Tool	ausführbare Capability in der Welt	lesen/schreiben/prüfen außerhalb des reinen Texts
MCP-Resource	adressierbarer Kontext	on-demand Fakten ohne Side Effect
MCP-Prompt	host-wählbare Vorlage	verwandt mit Skills; oft UI-seitig exponiert

Kombination: Skill secure-pr-review nutzt MCP git.diff + security.scan und kann bei Bedarf einen Sub-Agenten „red team“ starten.

Anti-Pattern	Besser
Alles als Sub-Agent	Skill + ein Loop, bis Isolation wirklich nötig
Alles als ein MCP-Tool do_feature	enge Tools + Skill-Orchestrierung
Skill mit 20 kB immer geladen	Catalog + Progressive Disclosure

---

5.5 State Machines und Graph-Orchestrierung

Produktive Agenten sind oft explizite Graphen, keine reinen Chat-Historien:

• Nodes = Schritte (retrieve, edit, test, review),
• Edges = Bedingungen (tests_passed, needs_human),
• State = typisiertes Objekt (Dateien, Diff-Hash, Attempt).

Vorteile:

• reproduzierbare Transitions,
• einfacheres Tracing,
• time-travel debugging,
• klare Stellen für Policy-Hooks.

{ width=100% } Frameworks wie LangGraph (Kap. 6) implementieren genau dieses Denkmodell – MCP-Server bleiben die Blätter des Graphen (I/O), nicht der Graph selbst.

---

5.6 Private vs. geteilte Kontexte

Der häufigste Multi-Agent-Fehler: alle sehen alles oder niemand sieht das Kanonische.

Kontextart	Sichtbarkeit	Beispiele	Risiko
Private Working Memory	ein Agent/Step	Zwischenhypothesen, rohe Logs	Leak in Shared Store
Shared Task State	Team der Agenten	Plan, Datei-Locks, offene TODOs	Konflikte ohne Locking
Project Memory	sessions-übergreifend	ADRs, Owner, Conventions	veraltete Einträge
Immutable Artifacts	alle, versioniert	PR-Diff v3, Test-Report #812	Verwechslung der Version

Regel: Teilt Artefakte und Entscheidungen, nicht jeden Gedanken-Trace. Komprimiere vor dem Publish. Ein Shared Artifact trägt typischerweise id, kind, revision, URI, Summary und Producer – versioniert und adressierbar, nicht als Chat-Anhang.

---

5.7 Parallelität, Locks und Konflikte

Parallel Worker auf demselben Repo brauchen Konventionen:

1. Datei- oder Modul-Locks im Shared State
2. Branch-per-Worker + Integrations-Agent
3. Serielle kritische Sektion (Schema-Migrationen)
4. CRDT-/Merge-Strategien nur wo fachlich sinnvoll (selten für Code)

{ width=100% } Ohne Locking: klassisches „lost update“ mit höflichen Commit-Messages.

---

5.8 Context-Aware MCP (CA-MCP) und Shared Context Stores

Standard-MCP macht Discovery interoperabel, entscheidet aber nicht von selbst, welcher Kontext wann relevant ist. CA-MCP bezeichnet hier ein Muster: Policies, Scopes, Freshness und Shared Context Stores über dem Protokoll – nicht einen proprietären Ersatz-Standard. Statt Chat als Bus publizieren Agenten versionierte Artefakte an bekannte URIs. Unverzichtbar, sobald mehrere Rollen parallel arbeiten und Kontext-Drift zum Hauptfehler wird.

Problem

Standard-MCP macht Discovery und Aufruf interoperabel. Es spezifiziert nicht von selbst, welcher Kontext für welchen Agenten-Schritt relevant ist. Naive Hosts listen alle Tools/Resources und schieben zu viel in den Prompt.

Idee: Context-Aware MCP (CA-MCP)

CA-MCP bezeichnet in diesem Buch ein architektonisches Muster (kein einzelner proprietärer Ersatz-Standard): MCP-Nutzung wird mit Context-Engineering-Policies und optionalen Kontext-Metadaten angereichert, sodass Hosts und Server bewusst, budgetiert und oft shared Kontext bereitstellen.

Denk an CA-MCP als Policy- und Index-Schicht über dem Protokoll, nicht als Ersatz für MCP. MCP sagt: „Es gibt Resource X und Tool Y.“ CA-MCP-Denken sagt: „Agent A in Phase Implement darf X in Zusammenfassung sehen, Tool Y nur auf Pfad src/billing/**, und wenn CI fertig ist, invalidieren wir den alten Test-Report.“

Die Bausteine unten findest du in echten Systemen unter unterschiedlichen Namen (Context Store, Catalog, Scopes, Gateway-Policy). Wichtig ist die Funktion, nicht das Label.

Bausteine:

Baustein	Funktion
Context Store	kanonische, adressierbare Kontext-Objekte (oft selbst ein MCP-Server)
Affinity / Scopes	welcher Agent/Skill welche URIs und Tools sehen darf
Freshness Metadata	revision, asOf, ttl, branch
Relevance Hints	Tags, Entities, Task-Embeddings (server- oder host-seitig)
Subscription / Invalidation	Notifications wenn Resource sich ändert (wo unterstützt)
Projection	unterschiedliche Sichten desselben Objekts (summary vs. full)

{ width=100% }

Shared Context Store als MCP-Server

Der Shared Context Store ist die Antwort auf Chat-als-Bus: Statt dass Agenten einander lange Prosa schicken, publizieren sie versionierte Artefakte an bekannte URIs. Der nächste Agent liest den Plan, den Diff, den Report – nicht den Gedankenstrom des Vorgängers.

Statt Kontext nur in Message-Historien zu halten:

• context://tasks/{id}/plan
• context://tasks/{id}/working-set
• context://tasks/{id}/artifacts/{artifactId}
• context://locks/{path}

Tools am Store: upsert_artifact, claim_lock, release_lock, append_decision. Resources: lesende Sichten für alle Agenten.

Beispielimplementierung (Stand Juli 2026, FastMCP). Die konkrete API kann sich ändern – das zugrundeliegende Muster (Shared Context als MCP-Server) bleibt übertragbar.

from fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("shared-context")
_STORE: dict[str, dict] = {}


class Artifact(BaseModel):
    task_id: str
    kind: str
    summary: str
    body: str
    revision: str = "1"


@mcp.tool
def upsert_artifact(artifact: Artifact) -> dict:
    """Schreibt ein Shared Artifact (komprimiert, versioniert)."""
    key = f"{artifact.task_id}:{artifact.kind}:{artifact.revision}"
    _STORE[key] = artifact.model_dump()
    return {"ok": True, "uri": f"context://tasks/{artifact.task_id}/artifacts/{artifact.kind}/{artifact.revision}"}


@mcp.resource("context://tasks/{task_id}/catalog")
def catalog(task_id: str) -> str:
    items = [v for k, v in _STORE.items() if k.startswith(f"{task_id}:")]
    if not items:
        return f"Keine Artifacts für task={task_id}"
    lines = [f"- {i['kind']}@r{i['revision']}: {i['summary']}" for i in items]
    return "\n".join(lines)

Best Practice: Der Shared Store speichert Ergebnisse und Verträge, keine vollständigen Model-Traces. Traces gehören ins Observability-Backend.

Context-Aware Discovery

Erweitertes Muster (Host- oder Gateway-seitig):

1. Aus Goal Entities extrahieren (service:billing, file:invoice.py).
2. Catalog query: welche Resources/Tools sind getaggt?
3. Nur diese Capabilities dem Modell anbieten.
4. Nach Tool-Results Catalog aktualisieren (z. B. neue Diff-URI).

Das ist CA-MCP in einem Satz: Discovery folgt Kontext, Kontext folgt Task – nicht umgekehrt.

---

5.9 Persistentes und geteiltes Memory über MCP-Server

Chat-Logs sind kein autoritatives Gedächtnis. Dieser Abschnitt zeigt, wie Decisions, TODOs, Konventionen und Codebase-Struktur session- und host-übergreifend über MCP-Server (Project-Memory, Knowledge Graph, Runbooks) bereitstehen. Memory wird damit portable Infrastruktur mit Hygiene-Pflichten – nicht ein immer länger werdender Prompt. Vertiefung im Bau: Kapitel 10.7 und 10.13.

Warum Memory-Server statt „Chat speichern“?

Chat-Logs sind linear, redundant und schwer autoritativ. Softwareteams brauchen:

• Entscheidungen mit Datum und Begründung,
• TODOs mit Owner,
• Architektur-Fakten mit Gültigkeit,
• Codebase-Verständnis (Symbole, Abhängigkeiten),
• Abfrage über Sessions, Hosts und Agenten hinweg.

MCP macht genau das portabel.

Memory-Typen als Server-Schnitt

Server (Beispielname)	Primat	Typische Primitives
project-memory-mcp	ADRs, TODOs, Conventions	Tools record_decision / upsert/search; Resources memory://adr/…
codebase-memory-mcp	Graph: files, symbols, calls, tests	Tools reindex, impact_analysis; Resources graph://…
session-memory-mcp	kompakte Session-Summaries	ephemeral mit TTL
runbook-mcp	Procedural Knowledge	Prompts + Resources

Konzept-Plate: Codebase Knowledge Graph

{ width=100% }

Project-Memory und Codebase Graph sind die beiden langlebigen Server-Schnittstellen im Coding-Alltag. Graph-Nodes/Edges und Hybrid-Entscheidung: 5.12. Implementierung und Demo: 10.7 / 10.13, code/02-project-memory, code/03-codebase-graph.
Index-Aktualität: reindex auf Pull/CI; Antworten mit revision/Commit-SHA.

Memory-Hygiene

Problem	Gegenmittel
Veraltete ADRs	status: superseded, Links zu Nachfolgern
TODO-Friedhof	TTL, Auto-close bei PR-Merge, regelmäßige Sweeps
Widersprüchliche Facts	Single Writer (Supervisor) oder Merge-Policy
Secret-Leaks im Memory	gleiche Redaction wie im Window
Unbegrenztes Wachstum	Summarize + archivieren, nicht ewig append

---

5.10 Multi-Agenten-Koordination mit MCP als Kommunikations- und Kontext-Schicht

Anti-Pattern: Agent-zu-Agent-Chat als Bus

Freier Natürlichsprach-Chat zwischen Agenten wirkt flexibel und erzeugt:

• uneindeutige Contracts,
• verlorene Entscheidungen,
• schwer testbare Protokolle,
• Context-Bloat durch Höflichkeit und Wiederholung.

Besser: Coordination over Shared Context + enge Messages

{ width=100% } Koordination über Shared Context bedeutet: Die Wahrheit liegt in Artefakten, die Nachrichten sind nur Steuerimpulse. Das ist ungewohnt, wenn man Multi-Agent aus Chat-Demos kennt – und genau deshalb stabiler test- und auditierbar.

Kommunikationsformen (von stabil nach „weich“):

1. Artifact Exchange – Diff, Report, Plan als Resources. Das ist der Default: wenig Ambiguität, gut versionierbar.
2. Typed Handoffs – kleine JSON-Messages im Store (handoff://…). Gut für „wer ist dran?“ und DoD, schlecht als Ersatz für den Diff selbst.
3. Event Hooks – CI fertig → Supervisor weckt Verifier. Entkoppelt Wartezeiten vom Chat-Polling.
4. Prompts – rollenspezifische MCP-Prompts pro Agent. Steuern Verhalten, nicht den kanonischen Projektstand.

Handoff-Contract (Beispiel)

{
  "from": "implementer",
  "to": "verifier",
  "task_id": "PROJ-442",
  "artifact_uris": [
    "context://tasks/PROJ-442/artifacts/diff/3",
    "repo://tests/test_billing.py"
  ],
  "claims": ["fixes null total when currency missing"],
  "done_when": ["unit tests green", "typecheck clean"]
}

Der Contract wird über den Shared Store publiziert (z. B. Tool upsert_artifact mit kind: handoff) – der Verifier liest denselben JSON-Vertrag, nicht den Chat-Verlauf des Implementers.

Rollen-Matrix (Minimal-Team)

Agent	Liest	Schreibt	Tools
Planner	Issue, Memory	Plan, TODOs	issues, memory
Implementer	Plan, Graph, Code	Diff-Artifacts	repo write, graph read
Verifier	Diff	Test-Report	tests, ci (read/rerun)
Reviewer	Diff, Report, ADRs	Review-Notes, Decision	memory, repo read
Supervisor	alles Kanonische	Locks, Status	context store

Die Matrix ist absichtlich asymmetrisch: Nicht jeder liest alles, nicht jeder schreibt alles. Schreibrechte auf den Repo-Pfad und Schreibrechte auf den kanonischen Plan sind verschiedene Vertrauensstufen – wer beides vermischt, baut sich einen God-Agenten mit nettem Rollennamen.

Koordinations-Failure Modes

Wenn Multi-Agent „irgendwie nicht skaliert“, liegt es selten am fehlenden zehnten Worker. Häufiger sind die folgenden Failure Modes – sie sind die multiplizierte Form der Context- und Harness-Probleme aus den Kapiteln 3 und 4. Trust Boundaries, Injection über Shared Artifacts und Privilege Escalation über kollidierende Tools gehören ins Threat Model von Kapitel 11 – hier die Koordinations-Sicht; dort Security und Production-Härte.

Failure	Symptom	Mitigation
Kontext-Drift	Agenten arbeiten auf verschiedenem Diff	revisionierte URIs, Locks
Ping-Pong	Reviewer ↔ Implementer Endlos	max rounds, Supervisor
Tool-Kollision	zwei Writer auf eine Datei	locks / branches
Deadlock / Lock-Starvation	Worker warten ewig auf claim_lock	Timeouts, max hold time, Supervisor-Break
Silent Override	Memory überschreibt ohne Merge	append-only decisions + status
God-Supervisor	zentraler Flaschenhals	klare Automationen, nur Exceptions hoch
Over-Parallelism	Merge-Hölle	begrenzte Worker, domänen-geschnitten

Mensch in der Multi-Agent-Schleife

Menschen sind oft:

• Goal Setter (Issue-Qualität),
• Policy Owner,
• Final Approver (merge),
• Exception Handler.

MCP-Prompt human_review_gate + Tool request_approval halten das explizit – statt „der Agent hofft auf ein Nicken“.

---

Architektur-Blueprint: Coding Org im Kleinen

{ width=100% } Dieser Blueprint skaliert von „zwei Skills in einer IDE“ bis zu „interner Dev-Agenten-Plattform“. Die Konstante ist: Graph orchestriert, MCP I/O’t, Memory kanonisiert, Policy begrenzt.

---

5.11 Harness Engineering als eigene Disziplin

Die kanonische Gleichung und die Harness-Schichten stehen in Kap. 4.5 (Agent = Model + Harness). Hier geht es um die Engineering-Disziplin: Produktionsprobleme 2025/26 sind oft fehlende Permissions, Verify-Loops, Budgets, Hooks und Traces – und die willst du auditieren und schließen, statt das Modell auszutauschen. Der Leitsatz Don’t blame the model – improve the harness wird zum Methodenkoffer und zur Checkliste, nicht zu einer zweiten Definition des Stacks. Kapitel 10 übt die Laborform; Kapitel 11.10 hebt denselben Stack in die produktive Control Plane.

5.11.1 Warum der Harness oft wichtiger ist als das Modell

Zwei Teams, gleiches Frontier-Modell:

Team A	Team B
4 kB widersprüchlicher System-Prompt	40-Zeilen-Core + 12 Skills
freies shell	enge Tools + MCP + Allowlist
kein Test-Zwang	Verify-Loop hart verdrahtet
keine Traces	tool_id + context trace
„Modell halluziniert“	messbare Task Success (Eval) – Richtung, keine Branchenquote [E4]

Dasselbe Modell, anderer Harness – andere Realität. Daher der Leitsatz:

Leitsatz: Don’t blame the model – blame (and improve) the harness. [E4]

Natürlich gibt es Modellgrenzen (Kap. 3). Ein großer Teil der Produktionsprobleme 2025/26 liegt erfahrungsgemäß in Context, Tools, Permissions und fehlender Verification – nicht im „zu schwachen“ Modell allein [E4].

{ width=100% }

5.11.2 Praktische Techniken

Die Techniken unten sind das Werkzeugbrett, nicht die Reihenfolge eines Big-Bang-Rewrites. In bestehenden Teams wirkt meist diese Staffelung: zuerst Permissions und Verification (Schaden begrenzen und Wahrheit erzwingen), dann Hooks und Budgets (Kanten härten), dann Skills/Progressive Disclosure (Kosten und Klarheit), Observability durchgängig von Anfang an in Minimalform (sonst lernst du nichts).

Technik	Idee	Beispiel
Hooks	Code vor/nach Tool- oder Session-Events	pre-write: secret scan; post-test: parse summary
Permissions	Allow/Deny auf Tool-, Pfad-, Netz-Ebene	deny **/.env; HITL für git push
Sandboxing	Ausführung begrenzen	Workspace-Root, Container, Timeouts
Checkpoints	Zustand sichern / zurück	branch pro Lauf, file snapshots, undo
Verification Loops	Act ohne grünes Orakel ≠ Done	tests → lint → types
Budgets	Steps/Tokens/Zeit	kill switch
Skill Routing	Progressive Disclosure	Catalog → skill.md → tools
Observability	jeden Schritt erklärbar	OpenTelemetry-Spans pro tool

Hooks (Skizze)

def pre_tool_use(tool: str, args: dict) -> dict | None:
    """Hook: blockiert oder modifiziert Aufrufe."""
    path = str(args.get("path", ""))
    if tool in {"read_file", "write_file"} and ".env" in path:
        return {"block": True, "reason": "secret path denied"}
    return None


def post_tool_use(tool: str, result: dict) -> dict:
    """Hook: komprimiert Observations."""
    if tool == "run_unit_tests" and "tail" in result:
        result = {**result, "tail": result["tail"][-2000:]}
    return result

In Cursor/Claude-Code-ähnlichen Hosts heißen Entsprechungen je Produkt Hooks, Permissions, Allowlist – das Prinzip ist portabel.

Verification Loop (hart)

edit → run_unit_tests → (fail → diagnose → edit)* → lint/types → summary

Wer „fertig“ im Prompt fordert, aber Tests nur optional anbietet, hat Prompt-Theater, kein Harness Engineering.

5.11.3 Bestehenden Harness verbessern – Checkliste

Die Checkliste eignet sich als 1–2-Stunden-Audit an eurem aktuellen Host – nicht als vollständiges Plattformprogramm. Ziel ist ein ehrliches Bild: Welche der acht Punkte sind wirklich erzwungen, welche stehen nur in einem Wiki?

Ob Claude Code, Cursor, Copilot oder Custom:

1. Core Prompt auditieren – kürze, entferne Domänenromane → Skills
2. Skill-Catalog für Top-10-Workflows anlegen
3. MCP-Server für Memory/Issues/CI statt Copy-Paste
4. Permissions auf Least Privilege
5. Hooks für Secrets und Output-Clipping
6. DoD = Tools, nicht Hoffnung
7. Eval-Suite (Anhang C) vor Autonomy-Erhöhung
8. Traces in Reviews von Agent-PRs mitliefern

5.11.4 Konkrete „Don’t blame the model“-Beispiele

Symptom	Schneller Modell-Vorwurf	Harness-Fix
Agent commitet .env	„unsicher“	deny globs + pre-commit hook + kein read
Endlos-Refactor	„hängt fest“	max_steps + skill mit Stop-Kriterien
Falsches Modul	„halluziniert“	Working Set + graph impact skill
„Tests grün“ lügt	„lügt“	final answer blocken bis test tool ok
Ignoriert Style Guide	„folgt nicht“	Guide als Skill/Resource, nicht 1× im Prompt 2024
Zu teuer	„Model pricing“	Progressive Disclosure + Tool-Subset

5.11.5 Harness Engineering im Zusammenspiel mit MCP und Multi-Agent

(Definition und Schichtentabelle: 4.5.)

• MCP liefert portable Welt-Fähigkeiten.
• Skills liefern portable Verhaltens-Module.
• Harness orchestriert Loop, Policy, UX.
• Multi-Agent (5.10) multipliziert Harness-Bedarf: jede Rolle braucht Scope, nicht nur einen größeren Prompt.
• Projekt-Information (5.12) – AGENTS.md, Knowledge Graph, Memory – ist oft der größte Hebel innerhalb des Harness.

Kurz: MCP ohne Harness ist ein Kabelbaum ohne Fahrzeug; Harness ohne Projekt-Information ist ein Fahrzeug ohne Karte.

---

5.12 Projekt-Information: Hybrid-KB, Graph und Context-Lifecycle

Agenten scheitern selten an „zu wenig Intelligenz“ und häufig an falscher, fehlender oder aufgeblähter Projekt-Information.
Theorie und Entscheidungstabellen hier; Bau und Demo in Kap. 10.13 (Ordnerstruktur, Root-AGENTS.md, MCP-Anbindung, TRACE-DEMO).

Analogie: Handwerker ohne Hausordnung (AGENTS.md), ohne Grundriss (Graph) und ohne Aktenschrank (Memory/ADRs) – teuer und schief.

Querverweise: Memory 5.9 · Skills 5.4 · CA-MCP 5.8 · Hands-on 10.12–10.13.

5.12.1 Was Agenten brauchen – und wo es lebt

Informationsklasse	Beispiele	Ohne Pflege
Betrieb & Commands	Build, Test, Lint	falsche CLI, Step-Waste
Konventionen / Security	Layering, Verbote	stilfremder Code, Incidents
Architektur-Fakten	Modulgrenzen, Call-Chains	Riesen-Diffs
Entscheidungen	ADRs, „warum nicht X“	wiederholte Debatten
Task-State	TODOs, Branch-Intent	Session-Bruch

Drei Speicher – kombiniert, nicht wahlweise:

1. Markdown-KB im Repo (reviewbar, policy-stark)
2. Knowledge Graph / Index (querybar, strukturell)
3. Conversation Context (ephemer, teuer; Compact verlustbehaftet)

5.12.2 Hierarchische Markdown-KB (AGENTS.md)

Pattern 2026 (Dateinamen je Host unterschiedlich): Root-Datei + Overrides in Unterverzeichnissen + Progressive Disclosure.

{ width=100% }

In die Root	Nicht in die Root (Link/Tool stattdessen)
exakte Commands, Security-Grenzen, Test-DoD	vollständige API-Referenz, Monorepo-Dateilisten
nicht-offensichtliche Konventionen, kurze Landkarte	Tutorials, Session-State, offensichtliche Ordnernamen
Pointer zu ADRs/Skills/Docs	widersprüchliche Stil-Essays (→ Linter)

Praxis	Empfehlung
Länge Root	ideal <150–200 Zeilen, Soft-Limit ~300
Portabilität	eine kanonische AGENTS.md; Host-Dateien als dünne Wrapper
Laden	Root → path-Overrides (innermost wins, Team-Regel dokumentieren) → Skills → MCP
Ownership	Platform/Tech Lead; Domain-Overrides bei den Teams

Vollständige Vorlage und Repo-Layout: Kap. 10.13.

5.12.3 Graph vs. RAG vs. Markdown

Frage	Grep/Lesen	Vector-RAG	Knowledge Graph
„Wer ruft Invoice.total?“	laut/unvollständig	oft daneben	called_by
„Impact wenn X ändert?“	teuer manuell	unsicher	impact_analysis
„Incident-Notiz zu X?“	–	stark	schwach

Richtung 2025/26 (Research-Benchmarks, z. B. RepoGraph/AST-Graph-Arbeiten) [E3]: Graph schlägt reines RAG oft bei Struktur/Impact/multi-hop – nicht als Feld-ROI und nicht als „Graph immer“. Absolute Faktoren und Transfer messt ihr intern (Anhang C/F) [E4]. Pipeline-Skizze und Server-Bau: 5.9 + 10.7.2 / 10.13.

{ width=100% }

Ansatz	Ideal für
Markdown-KB	Regeln, Commands, Verbote
Knowledge Graph	Refactors, Navigation, Impact
Vector-RAG	unstrukturierte Docs/Tickets
Project-Memory	ADRs, TODOs über Sessions

5.12.4 Hybrid-Default 2026

kurze Root-Regeln  +  Graph-MCP  +  Skills (on-demand)
+  Project-Memory (ADRs)  +  Vector-RAG nur bei Bedarf

Konzept-Plate: Hybride Projekt-Information

{ width=100% }

Schicht	Medium	Budget
L0 Policy	AGENTS.md + Core Prompt	klein, immer
L1 Verfahren	Skills	ein Body pro Task-Typ
L2 Struktur	Graph-MCP	Queries statt Dateihalden
L3 Entscheidungen	Memory / docs/adr	punktuell
L4 Prosa	RAG	nur unstrukturiert
L5 Rohcode	read_file Top-N	nach Graph gerankt

Symptom	Zuerst
kennt Build/Test nicht	AGENTS.md Commands
bricht Security	Root-Verbote + Hooks (5.11)
falsches Modul / Riesen-Diff	Graph + Working Set
wiederholte Architekturdebatte	ADR / Memory
Window voll, Arbeit unfertig	Lifecycle 5.12.5 – nicht „weiterchatten“

Operationshebel und Demo-Checklisten (welche Datei, welcher Server, Recovery Pack): Kap. 10.13.

5.12.5 Context-Lifecycle: Compact, Session, Externalize

(Kanonische Window-Metapher: Kap. 2.3.) Auto-Compact ist Notventil, kein Wissensmanagement – es verliert Datei-State, implizite Decisions und Negative Constraints.

Situation	Aktion
Phasengrenze, State externalisiert	manuelles Compact mit Focus (AC, Pfade, Test-Fails)
Themenwechsel / Kontext-Vergiftung / anderer Branch	neue Session + Recovery Pack
Auslastung grob >75 %	kein neues Groß-Feature; Compact oder Schnitt jetzt

Was	Wohin (Disk, nicht RAM)
Architektur-Entscheidungen	ADR / Memory-MCP
Task-Fortschritt, offene AC	Issue, PR-Body, kurzes Recovery Pack
Strukturfakten	Graph reindex
Harte Regeln	AGENTS.md

{ width=100% }

Goldene Regeln: Window = RAM (Kap. 2.3), Repo/MCP = Disk · Compact mit Absicht · Slice → externalisieren · neue Session ohne Recovery Pack = Datenverlust. Labor und Hebel-Tabelle: Kap. 10.13.5–10.13.6.

---

Best Practices

1. Starte mit einem Agenten + Shared Memory + wenigen Skills; multipliziere Rollen erst bei messbarem Bedarf.
2. Orchestriere mit explizitem State/Graph, nicht nur mit Chat-Transcript.
3. Nutze Progressive Disclosure für Skills, Tools und Markdown-KB (Root kurz, Details tiefer).
4. Setze CA-MCP-Policies: Scope, Budget, Trust, Freshness.
5. Publish nur komprimierte Artifacts in den Shared Store.
6. Harte Verification Loops und Permissions schlagen längere Prompts.
7. Observability: task_id durch alle Server- und Skill-Calls propagieren.
8. Verbessere den Harness (4.5 / 5.11), bevor du das Modell upgradest – außer Evals zeigen Modellgrenze [E4].
9. Hybrid-KB und Lifecycle als Theorie hier (5.12); Bau, Demo und Recovery Packs in 10.13.

---

Pitfalls

Pitfall	Folge	Gegenmaßnahme	Kapitel-Querverweis
Multi-Agent aus Hype	Kosten ↑, Qualität ↓	erst Single-Agent Evals	Kap. 5
50 Skills immer voll im Prompt	Bloat	Catalog + on-demand Body	Kap. 5
Skill = verstecktes God-Tool	uneindeutig	Skill orchestriert enge MCP-Tools	Kap. 5
Shared Full Traces	Bloat, Leak, Drift	Artifacts + Summaries	Kap. 5; Leak → Kap. 11
Ein God-MCP-Server	unreleasbar, unsicher	domänen-geschnittene Server	Kap. 5 / 11
Memory ohne Ownership	Müllhalde	Writer-Rollen, Hygiene-Jobs	Kap. 5
Keine Locks	überschriebene Fixes	claim/release oder Branches	Kap. 5.10
Nur Prompt-Tuning bei Systemfehlern	Symptombekämpfung	Harness Engineering (4.5 / 5.11)	Kap. 5
800-Zeilen-AGENTS.md als Wiki	wird ignoriert / veraltet	Root kurz + Hierarchie + Links	Kap. 5
Nur RAG für Impact-/Dependency-Fragen	unvollständige oder falsche Module, hohe Halluzinationsgefahr	Knowledge Graph (AST/Tree-sitter); bei Bedarf hybrid mit gezieltem Dateilesen	Kap. 5
Auto-Compact als Wissensstrategie	stiller State-Verlust	Externalize + manuelles Compact / neue Session	Kap. 5
Host-spezifische Doppel-Wahrheiten	Drift Claude vs. Cursor	eine kanonische Datei, Wrapper verweisen	Kap. 5

---

Key Takeaways

• Fortgeschrittene Systeme nutzen Hierarchie, Router, Graph-State, Skills und klare Rollen.
• Skills ersetzen Riesenprompts via Progressive Disclosure; versioniere sie wie Dotfiles.
• Skills ≠ Sub-Agenten ≠ MCP-Tools – kombiniere sie bewusst.
• Harness Engineering (Hooks, Permissions, Sandbox, Checkpoints, Verify) – Schichten 4.5, Methoden 5.11 – bestimmt Produktionsqualität oft stärker als das Modell [E4].
• Private Working Sets und Shared Artifacts müssen bewusst getrennt werden.
• CA-MCP koppelt MCP-Discovery/Zugriff an Context Policies und Shared Stores.
• Multi-Agent-Koordination läuft über versionierte Artifacts, Locks und Handoffs (5.10); Trust/Threat Model: Kap. 11.
• Projekt-Information (Theorie 5.12, Bau 10.13): hierarchische Markdown-KB, Knowledge Graph und Memory.
• Hybrid 2026: kurze Root-Regeln + Graph-MCP + Skills + Memory; RAG nur gezielt.
• Context Window ist RAM (Kap. 2.3): strategisch compacten, rechtzeitig neue Session, State externalisieren.
• „Don’t blame the model“ – bis Context, Tools und Verify widerlegt sind.

---

Was als Nächstes kommt

Kapitel 6 hilft bei der Runtime-Wahl (Achsen, Eval, Build vs. Buy) – ohne Framework-Enzyklopädie. MCP und Hybrid-KB bleiben portabel; das Framework orchestriert nur.

Vertiefung in der Praxis: Kap. 10.12 (System Prompt + Skill Engineering), Kap. 10.13 (professionelle Projekt-Knowledge-Base: AGENTS.md, Graph-MCP, Memory, Recovery Packs) und Kap. 11.10 (Production Harness).

---

Übungsanregungen

1. Zeichne euren aktuellen AI-Workflow als Graph mit max. 8 Nodes.
2. Schreibe zwei skill.md für eure häufigsten Tasks (Body < 80 Zeilen).
3. Liste Harness-Lücken: Hooks, Permissions, Verify, Traces – was fehlt?
4. Nimm einen fehlgeschlagenen Agent-Lauf und wende den Diagnosebaum aus 5.11.1 an.
5. Entwirf Minimal-APIs für project-memory und codebase-memory (je 3 Tools, 3 Resources).
6. Skizziere eine Root-AGENTS.md (unter 80 Zeilen) für euer Haupt-Repo: Commands, 5 harte Regeln, Pointer – ohne Wiki-Ballast.
7. Nenne drei Fragen, die bei euch der Graph besser beantwortet als RAG, und drei umgekehrt.
8. Definiert Team-Regeln: ab welchem Context-Füllstand Compact vs. neue Session – und was ins Recovery Pack muss.