ki-buch/teil-03-praxis/kapitel-10-hands-on-mcp-coding-agent.md

Kapitel 10: Hands-on – Einen eigenen agentenbasierten Coding Agent mit MCP bauen

Teil III · Agentenbasierte Softwareentwicklung in der Praxis – MCP & Context Engineering im Fokus

---

Architektur-Kapitel erklären, was man tun sollte – und lassen oft die Lücke, wie man es spürbar macht. Ohne laufenden Loop, Trace und Policy-Deny bleibt Context Engineering Theorie. Dieses Kapitel ist die Werkstatt: du baust und misst eine referenzierbare Mini-Plattform – MCP-Server, Agent-Loop, Working Set, Context Traces, Permissions und Skills – anhand des Companions unter code/ (Stand Juli 2026).

These: Ziel ist nicht die schönste SDK-Syntax, sondern Schnitt, Policies, Context-Disziplin und Observability. Verify-Loop, Trust Boundaries und Progressive Disclosure müssen greifbar, beobachtbar und CI-tauglich werden – ohne Framework-Lock-in. Snippets im Buch sind Illustration; die Wahrheit der Implementierung liegt im Companion.

Leitfrage: Wie setzt du die Prinzipien der Kapitel 2–9 so um, dass Erfolg und Failure im Trace lesbar sind – nicht nur im Bauchgefühl?

Starte mit dem 5-Minuten-Pfad (10.0), arbeite die Lab-Stufen L0–L5, behandle volatile Host-/SDK-Details als zeitgebunden. Danach vertieft Kapitel 11 Security, Governance und Production-Harness – genau die Lücken, die ein Labor-Agent noch verzeihen darf, Produktion aber nicht.

Lernziele

Nach diesem Kapitel kannst du:

• in ≤ 5 Minuten den Offline-Agenten starten, einen Context Trace lesen und Erfolg/Failure unterscheiden,
• einen Minimal-MCP-Server nach dem Primitive-Muster aufsetzen und im Host oder LocalBus verbinden,
• Project-Memory, Codebase-Graph und Dev-Tools als domänengeschnittene Server betreiben,
• einen schlanken Coding-Agent-Loop mit Task-Brief, Working Set, max_steps und Verify-Orakel betreiben,
• Context-Engineering-Patterns anwenden und im Trace nachweisen,
• Core-System-Prompt + Skills mit Progressive Disclosure designen und versionieren,
• eine hybride Projekt-Knowledge-Base verdrahten,
• Permissions, Redaction, HITL und Policy-Violations im Labor erzwingen und per Test absichern,
• Baseline- vs. Context-Engineered-Läufe anhand vorgefertigter Traces vergleichen,
• entscheiden, was aus dem Hands-on Wegwerf ist und was Katalog-Server / Policy / Eval-Gate wird.

Faustregel: Dieses Kapitel ist Werkstatt, keine API-Bibel — Ziel sind Architektur und Context-Engineering-Muster, nicht die langfristige Gültigkeit einzelner API-Aufrufe.

Code im Repo: lauffähig unter code/ (examples/01…05, patterns/, traces/golden/, Tags book-2026-07 / latest). Host-/SDK-Matrix: code/COMPATIBILITY.md.

Schicht	In diesem Kapitel	Stand
Stabil	Server-Schnitt, Verify-Loop, Trust Boundaries, Hybrid-KB, Trace-Schema	Prinzipien
Mittelstabil	Skills, Progressive Disclosure, Context Policy, AGENTS.md	Muster
Volatil	FastMCP-Syntax, Host-JSON, Tool-Namen im Demo	Juli 2026 / Companion

Praxis-Tipp: Hands-on, LocalBus/Fake-MCP und Host-JSON in diesem Kapitel folgen MCP 2025-11-25 und dem Freeze-Tag book-2026-07. Die Revision 2026-07-28 ist im Companion nicht nachgezogen; sie ändert Session-/Request-Struktur, nicht die Lehrziele (Server-Schnitt, Working Set, Verify, Trace). Wer 2026-07-28 produktiv fährt, plant Client/Gateway-Anpassungen gesondert – Kapitel 4.8 und code/COMPATIBILITY.md.

---

10.0 Fünf-Minuten-Start (First Success)

Ziel: ohne Host, ohne API-Key, mit beobachtbarem Trace — in wenigen Minuten.
Setup identisch zu code/README.md (5-Minuten-Start).

cd code
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

python examples/05-coding-agent/agent.py --demo
# Kompatibilität: python 05-coding-agent/agent.py --demo

Erwartete Signale (DoD des Starts):

Signal	Bedeutung
Exit-Code 0	Loop endete kontrolliert
stdout enthält Context Trace	Observability aktiv
skill_id: fix-from-issue	Progressive Disclosure hat gegriffen
agents_files enthält Root + Override	Hybrid-KB geladen
tools_called enthält get_issue, run_unit_tests	Tool-Pfad, nicht nur Prosa
tests_ok: true, patch_applied: true	Verify-Orakel, nicht Self-Claim
runs/latest/context-trace.json	Audit-Artefakt auf Disk
timeline.md / working-set.md im Run-Ordner	lesbare Observability

Was du danach siehst: Der Agent fixt Issue DEMO-1 (missing currency in invoice.py) im demo_workspace, schreibt einen Context Trace (TRACE-DEMO-1) und lässt die Workspace-Tests grün. Interpretiere den Trace bevor du weiterliest: Welche Resources? Welche Tools? Was wurde blockiert?

Wenn es scheitert: python -m pytest tests -q, dann code/COMPATIBILITY.md. Host ist für den 5-Min-Pfad nicht nötig.

Optional: bash scripts/run_5min_check.sh.

Code im Repo: Offline-Demo nutzt LocalBus (examples/05-coding-agent/local_bus.py): dieselben Server-Funktionen in-process, ohne STDIO/JSON-RPC. Ideal zum Lernen des Loops. Echtes Host-MCP (Pfad B, 10.3) spricht die Server per STDIO an (host-config.example.json) – nicht denselben Transport verwechseln.

---

10.1 Zielbild und Architektur des Hands-on-Projekts

Wir bauen kein volles Produkt-IDE, sondern eine referenzierbare Mini-Plattform:

Konzept-Plate: Hands-on Zielarchitektur

{ width=100% }

Komponente	Verantwortung	Companion
project-memory	ADRs, TODOs, Conventions	examples/02-project-memory/
codebase-graph	Datei-/Symbol-Index, Impact	examples/03-codebase-graph/
dev-tools	read/write workspace, tests, mock issues	examples/04-dev-tools/
Markdown-KB	AGENTS.md, Overrides, Recovery Pack	demo_workspace/
Agent Loop + Harness	Plan → Tool/Resource → Observe → Done; Hooks, Budget	examples/05-coding-agent/
Fake-MCP / Fixtures	deterministische CI, Failure Injection	patterns/fake_mcp/
Observability	Context Trace, Timeline, Working-Set	runs/, traces/golden/

Nicht-Ziele: Multi-Tenant-SaaS, perfekter Language Server, Production-OAuth — Erweiterungen (Kap. 11–12). Lehr-KB und Graph-MCP gehören zum Kern.

Wegwerf vs. behalten (Vorschau 10.11): Demo-Policy und hardcodierter Fix sind Wegwerf. Server-Contracts, Trace-Schema, Deny-Hooks, Eval-Gates und AGENTS.md-Muster werden Plattform.

---

10.2 Voraussetzungen und Workspace

Tools

• Python 3.11+
• pip oder uv
• optional Node 20+ (nur falls du externe MCP-Hosts/SDKs ausprobierst; Companion ist Python-first)
• ein MCP-fähiger Host oder der Mini-Loop in code/examples/05-coding-agent

Repo-Layout

code/
  README.md                 # 5-Min-Pfad + Host-Matrix
  COMPATIBILITY.md
  patterns/                 # stabil: Fake-MCP, Trace-Schema, Permissions
  examples/
    01-minimal-server/ … 04-dev-tools/
    05-coding-agent/        # Agent, Skills, demo_workspace, profiles/
  01-… 05-…                 # Symlink-Shims → examples/ (alte Pfade)
  traces/golden/            # TRACE-DEMO-1, TRACE-BASELINE-1, …
  tests/
  runs/                     # Lauf-Artefakte (lokal)
  host-config.example.json

patterns/ = übertragbare Bausteine. examples/ = volatile Lab-Pfade. Top-Level-Shims halten ältere Copy-Paste-Befehle lauffähig.

---

10.3 Von null zum ersten Tool-Call (Pfad B: Host)

Schritt 1: Server starten

python examples/01-minimal-server/server.py

Schritt 2: Host-Config

Beispielkonfiguration (Stand Juli 2026). Feldnamen variieren je Host — das Muster (command/args/env bzw. URL) bleibt übertragbar.

Siehe code/host-config.example.json — Server per STDIO einbinden.

Schritt 3: Smoke-Test im Host

• Tool ping aufrufen lassen
• Resource info://status lesen

Wenn das sitzt: Transport, Lifecycle, Discovery. Offline-First (10.0) bleibt der kanonische Einstieg.

---

10.4 Der Agent-Loop – minimal, aber ehrlich

{ width=100% }

Prinzipien aus Kap. 4–7:

1. Pinned Context: Conventions + Issue + Core/AGENTS-Kurzform
2. On-demand: Dateien/Graph
3. Verify: Tests vor „fertig“ (done_reason nur bei Tool-Oracle)
4. Budget: max_steps + Token-/Char-Budget im Trace

Referenz: examples/05-coding-agent/agent.py. In Produktion ersetzt du den Mini-Loop typischerweise durch eine Graph-/Workflow-Runtime (Kap. 6) — MCP-Server und ihre Contracts bleiben die portable Schicht.

---

10.5 Working Set und Task-Brief

Bevor der Agent wild sucht, formuliere einen Task-Brief (MCP-Prompt oder Issue-Felder):

Ziel: ...
Akzeptanzkriterien: ...
Erlaubte Pfade: src/, tests/
Verbotene Pfade: .env, secrets/**
Done wenn: unit tests grün + kurze Summary
Autonomy-Level: L1 (kein unattended merge)

def task_brief(goal: str, paths: list[str], ac: list[str]) -> str:
    return (
        f"Ziel: {goal}\n"
        f"Erlaubte Pfade: {', '.join(paths)}\n"
        "Akzeptanzkriterien:\n- " + "\n- ".join(ac) + "\n"
        "Behaupte keine Testergebnisse ohne Tool."
    )

Working Set = die konkrete Menge geladener URIs/Pfade im Lauf. Der Trace speichert sie; working-set.md listet Trust-Level und Char-Kosten pro Block.

---

10.6 End-to-End-Happy-Path und TRACE-DEMO-1

Manuell nachspielbar (engineered demo_policy in agent.py):

1. Skill laden: fix-from-issue (Progressive Disclosure)
2. Issue-Mock: get_issue("DEMO-1")
3. Resource memory://conventions
4. search_symbols → impact_analysis
5. read_file("src/billing/invoice.py") → write_file(…) (Minimal-Patch)
6. run_unit_tests
7. record_decision (nach grünen Tests)
8. Trace schreiben (TRACE-DEMO-1)

Automatisiert:

python examples/05-coding-agent/agent.py --demo
# Default-Profil engineered → TRACE-DEMO-1
# explizit: --profile engineered | baseline

TRACE-DEMO-1 ist das kanonische Lehrstück (golden: traces/golden/TRACE-DEMO-1.json). Pflichtinhalte:

• resources_loaded, agents_files, skill_id
• tools_called + timeline (step, tool, ok, ms)
• working_set (ref, trust, chars)
• policy_decisions (allow/deny/redact/hitl)
• budget (steps, max_steps, approx_tokens/chars)
• tests_ok, patch_applied, done_reason

{ width=100% }

---

10.7 Praktischer Leitfaden: Einen eigenen MCP-Server für Softwareentwicklung bauen

Jetzt wird gebaut: von der stabilen Server-Anatomie über Knowledge-Graph- und Project-Memory-Server bis zu gehärteten Git-/Test-/Issue-Capabilities. Fokus auf Schnittmuster und Security-Defaults. Was du hier exponierst, bestimmt später Nutzbarkeit und Angriffsfläche — Kapitel 11.7 liest dieselben Server mit Threat-Model-Brille.

10.7.1 Grundstruktur eines MCP-Servers (Muster + Illustration)

Muster (stabil)

1. Server-Instanz mit klarem Namen / Identity
2. Tools (Aktionen, Schema, strukturiertes Result)
3. Resources (URI → lesbarer Kontext)
4. Prompts (kuratierte Workflow-Templates)
5. Transport (STDIO lokal, HTTP remote)

{ width=100% }

Beispielimplementierung (Stand Juli 2026, FastMCP). Vollständig: code/examples/01-minimal-server/server.py.

from fastmcp import FastMCP

mcp = FastMCP("minimal-dev-helper")

@mcp.tool
def ping(message: str = "pong") -> str:
    """Health-Check für Discovery und Tool-Calling."""
    return f"ping-ack: {message}"

@mcp.resource("info://status")
def status() -> str:
    return "ok | server=minimal-dev-helper | env=dev"

@mcp.prompt
def secure_code_review() -> str:
    return (
        "Du bist Security-Reviewer. Prüfe Diffs auf Injection, AuthZ, "
        "Secret-Leaks und unsichere Deserialisierung. Findings nach Severity."
    )

if __name__ == "__main__":
    mcp.run()

Design-Regeln für Tools

Regel	Beispiel gut	Beispiel schlecht
Enger Zweck	run_unit_tests	shell
Klare Types	path: str	options: Any
Strukturiertes Result	{ok, summary, ...}	freier Prosatext only
Timeouts	60s tests	endlos
Fehler als Daten	ok: false, stderr	ungefangene Exception

Resources vs. Tools: kanonischen Kontext lesen → Resource; Aktion/Query mit Side Effect → Tool.

10.7.2 Codebase Knowledge Graph MCP-Server

Ziel: Struktur statt nur Volltext — Dateien, grobe Symbole, Kanten (imports/mentions), Tool impact_analysis.

Vollständig: code/examples/03-codebase-graph/server.py

{ width=100% }

Primitive	Name	Nutzen
Tool	reindex	Index neu aufbauen
Tool	search_symbols	Symbol-/Pfad-Suche
Tool	impact_analysis	abhängige Dateien
Resource	graph://file/{path}	Karteikarte Datei
Resource	graph://stats	Index-Metriken

Realwelt: Tree-sitter, SCIP, Language Server. Das Beispiel lehrt MCP-Schnittstelle und Graph-Semantik, nicht Compiler-Qualität.

10.7.3 Persistenter Project-Memory MCP-Server

Ziel: Entscheidungen und TODOs über Sessions halten. Vollständig: code/examples/02-project-memory/server.py.

Tool	Zweck
record_decision	ADR-ähnlich speichern
add_todo / complete_todo	Aufgaben
search_memory	Volltext leichtgewichtig
set_convention	Key-Value Conventions

Resource	Zweck
memory://conventions	Conventions gerendert
memory://adr/{id}	einzelne Entscheidung
memory://todos	offene TODOs
memory://catalog	Übersicht

Hygiene: stabile IDs, status active|superseded, keine Secrets, optional TTL.

10.7.4 Integration von Git, Issues, Tests via MCP

Vollständig (kompakt): code/examples/04-dev-tools/server.py. In größeren Systemen splitten: git-mcp, tests-mcp, issues-mcp.

Git/Workspace (gehärtet, Demo-Stand): git_status, git_diff; Schreiben nur über write_file im Workspace mit Allowlist (kein generisches shell, kein apply_patch-Tool im Companion).

FORBIDDEN_PARTS = (".env", "secrets/", ".git/")

def safe_path(root: Path, rel: str) -> Path:
    p = (root / rel).resolve()
    if not str(p).startswith(str(root.resolve())):
        raise ValueError("Path escape denied")
    if any(f in str(p) for f in FORBIDDEN_PARTS):
        raise ValueError("Forbidden path")
    return p

Tests: run_unit_tests mit Timeout und strukturiertem Result — nie shell_raw, wenn ein enges Tool reicht.

Issues (Mock): DEMO-1 hält Agent-Prompts stabil; Remote (GitHub/Jira) später hinter denselben Tool-Namen.

10.7.5 Security, Sandboxing und Permissions (Hands-on-hart)

Bedrohung	Beispiel	Gegenmittel im Labor
Path traversal	../../.ssh/id_rsa	resolve + root prefix
Secret exfiltration	.env lesen	deny globs + Redaction
Command injection	path ; rm -rf	keine Shell, argv-Listen
Over-broad tools	shell	enge Tools + Allowlist
Destruktive Aktionen	blindes write_file	HITL-Gate
Prompt injection via file	„ignore instructions“	Trust-Levels im Trace; Kap. 11

Sandbox-Stufen

Stufe	Maßnahmen	Companion?
S0 Dev PoC	path checks, deny globs	ja (Labor)
S1 Team	+ timeouts, allowlist, read-only default, redaction	ja (Labor)
S2 Hardened	+ container, seccomp, egress deny	nein
S3 Multi-Tenant	+ strong authn/z, Isolation	nein

Hands-on zielt bewusst nur auf S0–S1 (Labor). Kein Production-Claim: kein Container-Sandboxing, kein seccomp, kein Multi-Tenant, keine produktiven Credentials. Was in Produktion fehlt (S2+, Gateway, Org-Policy, Error Budgets), steht in Kap. 11.10 und code/README.md (Security).

Pflicht-Labor (L3): Versuch read_file(".env") → block → Trace policy_decisions → CI tests/test_policy_violations.py grün. HITL: --hitl auto-deny (CI-Default) für destruktive Tools; Fake-MCP-Fixture hitl_destructive.json.

Companion-Bausteine: patterns/permissions/ (allowlist, redaction, hitl), patterns/fake_mcp/.

Best Practices Checkliste Server-Bau

• ☐ Ein Server = eine Domäne
• ☐ Stabile Tool-Namen und Return-Shapes
• ☐ Timeouts überall
• ☐ Deny-Listen + Redaction getestet (ohne LLM)
• ☐ README: install, env, threat notes
• ☐ Keine Default-Credentials

---

10.8 Context Engineering Patterns mit MCP

Die Patterns aus Kapitel 3.7 und 7.8 werden hier umsetzbar und messbar.

Pattern	Labor-Nachweis
On-demand Loading	Trace: Graph vor Full-Repo; wenige gezielte read_file
Selective Exposure	Deny-URI / forbidden path im Trace
Prompt-Templates	MCP Prompt oder Skill-Body geladen
Observation Compression	clipped: true / kurze test tails
Pinned + Dynamic	Conventions pinned; Dateien dynamic
Context Trace	TRACE-DEMO-1 vs. TRACE-BASELINE-1

10.8.1 On-Demand Context Loading

{ width=100% }

def load_on_demand(mcp_graph, mcp_dev, query: str, budget: int = 3) -> list[str]:
    hits = mcp_graph.call_tool("search_symbols", {"query": query, "limit": budget})
    blocks = []
    for h in hits.get("hits", [])[:budget]:
        path = h["path"]
        blocks.append(mcp_dev.call_tool("read_file", {"path": path})["content"])
    return blocks

10.8.2 Selective Resource Exposure

ALLOW_PREFIXES = ("memory://", "graph://", "info://")
DENY_SUBSTR = (".env", "secrets/")

def allowed_resource(uri: str) -> bool:
    if any(d in uri for d in DENY_SUBSTR):
        return False
    return uri.startswith(ALLOW_PREFIXES) or uri.startswith("repo://")

10.8.3 Prompt-Templates, Compression, Pinned Split

• MCP-Prompts versionieren (fix_from_issue, secure_code_review)
• Test-Outputs auf Summary + Tail clippen
• Immer pinnen: Conventions, Task-Brief, Policy-Kurzform
• Dynamisch: Dateien, Graph-Impact, CI-Logs

10.8.4 Context Trace und Baseline-Vergleich (zentrales Lehrstück)

Durchgängiges Beispiel: Issue DEMO-1 (Billing Currency). Derselbe Trace-Faden erscheint in Kap. 3 (Waste), 5.12/10.13 (KB), 11.7.7 (Audit) und Anhang C.12.

{ width=100% }

Lauf	Context Policy	Erwartung
TRACE-BASELINE-1	kein AGENTS.md, kein Memory, keine Skills, greedy Reads	mehr Steps/read_file, schwächere Grounding-Quellen
TRACE-DEMO-1	AGENTS + Skill + Memory + Graph + Verify	engere Tool-Sequenz, nachvollziehbare Policy, tests_ok

python examples/05-coding-agent/agent.py --demo --profile engineered   # TRACE-DEMO-1
python examples/05-coding-agent/agent.py --demo --profile baseline     # TRACE-BASELINE-1
python -m pytest tests/test_trace_compare.py -q

Scorecard-Felder (an Anhang C.2): Task Success, Steps, Anzahl read_file, Context Hit Rate, approx Tokens/Chars, Tool-Failures, Human Edit Rate (manuell; Offline-Demo = 0).

Der Vergleich misst Prozess- und Kontextqualität unter Mock-LLM – didaktisch und reproduzierbar [E3]*, nicht generalisierbar auf Team-ROI oder Feld-Produktivität (Anhang C.12 / F).

Erfolg der Übung: eine Vergleichstabelle + eine Policy-Entscheidung („welche Context-Policy behalten wir?“) — keine ROI-Hochrechnung.

Faustregel: Golden Traces und Demo-Proxies steuern Context Policy und Harness im Labor [E3]*. Business Case und Autonomy-Stufen brauchen die 90-Tage-Scorecard (Kap. 7.9) und Feld-Proxies – nicht den Demo-Exit-Code. [E4]

---

10.9 Zusammenbau: Mini Coding Agent

Datei / Modul	Rolle
examples/05-coding-agent/agent.py	Loop, Budgets, Profiles, Trace-Write
examples/05-coding-agent/local_bus.py	LocalBus: in-process, kein STDIO-MCP
patterns/fake_mcp	Fixtures + Violations (CI)
patterns/trace_schema	Schema v1 + Renderer
patterns/permissions	Allowlist, Redaction, HITL
Server 02–04	Capabilities (Host: STDIO; Demo: LocalBus)

Praxis-Tipp: LocalBus ≠ echtes STDIO-MCP. LocalBus registriert dieselben Tool-Funktionen der Server 02–04 und ruft sie im selben Prozess auf. JSON-RPC, Lifecycle-Handshake und Host-Transport entfallen bewusst. Für Host-Smoke: 10.3 + host-config.example.json (echte STDIO-Prozesse). Matrix: code/COMPATIBILITY.md.

Entscheidungs-Policy im Loop

if state.steps >= state.max_steps:
    return "budget_exhausted"
if last_tool == "run_unit_tests" and result.get("ok") and state.patch_applied:
    return "success"  # nur Tool-Oracle

Mock-LLM / demo_policy sequenziert feste Tool-Calls, damit du ohne API-Key die MCP-Kette verstehst [E3]*. Echtes Modell ersetzt nur die Entscheidungsfunktion — nicht die Contracts, Hooks oder Traces. Ein grüner Demo-Lauf ist kein Feldbeleg für Produktivität.

---

10.10 Übungslabor (L0–L5)

Eine Leiter, steigende Schwierigkeit. Jede Stufe: Lernziel · DoD · Metriken · Failure Mode.

L0 — First Success (10.0)

Lernziel	Offline-Agent + Trace lesen
DoD	--demo exit 0; runs/latest/context-trace.json; tests_ok: true
Metriken	steps ≤ 12; tools enthält run_unit_tests
Failure Mode	kaputte deps → README Troubleshooting / COMPATIBILITY.md

L1 — Minimal-Server & Discovery

Lernziel	Tools/Resources/Prompts exponieren
DoD	pytest tests/test_minimal_server.py grün; optional Host-ping
Metriken	list_tools ≥ 2; resource info://status
Failure Mode	falscher Transport/Pfad → Discovery leer

L2 — Memory + Graph Working Set

Lernziel	Persistent Memory + Impact vor Read
DoD	engineered Trace: resources_loaded + graph tools; Decision optional über Restart
Metriken	invoice-Pfad in Working Set; resources ≥ 1
Failure Mode	Index ohne Ignore → Secret-Pfad (muss deny/rot sein)

L3 — Permissions, Redaction, HITL

Lernziel	Allowlist, Secret-Deny, Redaction, destruktives Tool mit HITL
DoD	pytest tests/test_policy_violations.py grün; TRACE-POLICY-DENY-1 Keys verstehen
Metriken	erwartete Policy-Failure = 1; keine Secret-Substrings im Trace
Failure Mode	Hook greift nicht → CI rot

L4 — Full DEMO-1 + Skills + Hybrid-KB

Lernziel	Skill Progressive Disclosure + AGENTS-Hierarchie + Verify
DoD	TRACE-DEMO-1 (wesentliche Keys); workspace pytest grün
Metriken	skill_loaded; agents_files ≥ 2; tests_ok; Budget nicht exhausted
Failure Mode	Done ohne Tests → done_reason ≠ tests_passed

L5 — Baseline vs. Engineered + Plattform-Schnitt

Lernziel	Messbarer Context-Vergleich; behalten/wegwerfen
DoD	Compare-Test grün; 5-Punkte-Plattform-Memo (10.11)
Metriken	Δ steps, Δ read_file, KB-Signale (skill/memory/AGENTS)
Failure Mode	„ein grüner Lauf = Wahrheit“ — Übung verlangt zwei Profile

Erweiterungsaufgaben (optional): eigener Skill · run_linter · Recovery Pack · zweiter Host-Wrapper · Core kürzen bei grünem Demo · Threat-Model-Skizze 11.7.0.

---

10.11 Von der Übung zur Team-Plattform

Hands-on-Artefakt	Urteil	Nächster Schritt
demo_policy / hardcodierter Patch	Wegwerf	echtes Model-Tool-Calling
LocalBus in-process	Wegwerf für Prod	STDIO/HTTP MCP-Clients
Server-Contracts (Tool/Resource-Shapes)	Behalten	Katalog-Server, SemVer
Deny-Hooks, Allowlist, Redaction, HITL	Behalten	Policy-as-Code / Gateway (Kap. 9/11)
Trace-Schema + golden traces	Behalten	Eval-Gates in CI
Fake-MCP Fixtures	Behalten	Release-Policy (Anhang C)
AGENTS.md + Skills + Core	Behalten	Review wie Code
demo_workspace Billing	Lehr-Fixture	Produkt-Repo ersetzen
host-config.example.json	Muster behalten	org-spezifische Reference Config
patterns/	Behalten	interne Platform-Lib

Plattform-Reife (Checkliste):

1. Server splitten und versionieren
2. Gateway + Auth
3. Eval-Suite mit Fake-MCP in CI
4. IDE Reference Config im Anwendungs-Repo
5. CA-MCP / Autonomy-Level pro Rolle (Kap. 5/8)
6. Trace-Retention + Audit
7. Threat Model (Kap. 11.7) pro Katalog-Server

---

10.12 System Prompt + Skill Engineering (Hands-on)

Umsetzung aus 4.5 und 5.4/5.11: knapper Core-Prompt als Verfassung, Skills mit Progressive Disclosure als Fachgesetze, Verify als Definition of Done. Reviewbarer Harness-Inhalt im Repo — analog zu Dotfiles.

Repo: code/examples/05-coding-agent/prompts/core_system.md, skills/*/skill.md.
Demo: python examples/05-coding-agent/agent.py --demo lädt Catalog → Skill Body → MCP-Tools → Tests.

10.12.1 Vom Riesenprompt zum Core + Skills

Monolith (Anti-Pattern)	Core + Skills (Zielbild)
5–15 kB System-Prompt mit allen Domänen	Core ≤ ~1–2 Bildschirme
Jede Regel immer im Window	Catalog billig; Body nur bei Bedarf
Breaking Change = ein Riesen-Diff	Skill-SemVer, Core stabil

Konzept-Plate: Context Stack (Core · Task · Skill · MCP)

{ width=100% }

10.12.2 Core bauen

Kerninhalt: Rolle · harte Regeln (keine erfundenen Tests, keine Secret-Pfade, kein Raw-Shell) · Arbeitsweise Brief→Skill→Working Set→Patch→Verify · Done = Tools · knappe Ausgabe.

10.12.3 Skills im Demo

Skill-ID	Zweck
fix-from-issue	Issue → Working Set → Patch → Tests
secure-diff-review	Security-Checkliste am Diff
record-and-summarize	Decision + Summary

10.12.4 Progressive Disclosure im Loop

Step	Context-Ereignis	Window-Kosten
Start	Core + Catalog + Task-Brief	niedrig–mittel
1	Skill Body	+1 Skill
2–n	MCP on-demand	variabel
Ende	Context Trace	Audit

10.12.5 MCP-Prompts vs. Skills vs. Core

Du brauchst …	Nimm …
Regeln für jeden Lauf	Core
Wiederholbaren Workflow mit DoD	Skill
Vorlage in der Host-UI / MCP-discoverbar	MCP Prompt
Einmaligen Auftrag	Task-Brief / Issue

10.12.6 Mini-Harness-Hooks

def pre_tool_use(tool: str, args: dict) -> dict | None:
    path = str(args.get("path", ""))
    if tool in {"read_file", "write_file"} and any(
        f in path for f in (".env", "secrets/", ".git/")
    ):
        return {"block": True, "reason": f"forbidden path: {path}"}
    return None

Im Loop: zuerst pre-hook → bei Block Observation blocked → sonst Tool → post-hook (Clip/Redact) → Observation. Done nur über Verify-Tools.

10.12.7 Done-Kriterien (Skills + Demo-Trace)

Nach python examples/05-coding-agent/agent.py --demo --profile engineered gilt 10.12 als Done, wenn der Trace (runs/latest/context-trace.json bzw. golden TRACE-DEMO-1) mindestens enthält:

Trace-Feld / Signal	Erwartung
skill_id	fix-from-issue
skill_loaded	true
tools_called	u. a. get_issue, read_file, write_file, run_unit_tests
tests_ok	true
done_reason	an Verify gekoppelt (nicht reiner Self-Claim)

Skill-eigene DoD (skills/*/skill.md) und Core-DoD (prompts/core_system.md) bleiben die inhaltliche Checkliste; der Trace ist der messbare Nachweis.

---

10.13 Aufbau einer professionellen Projekt-Knowledge-Base

Hybride Wissensbasis im Demo-Workspace: hierarchische AGENTS.md, Index, ADRs, Skills, Core-Prompt, Memory- und Graph-MCP. Theorie aus Kapitel 5.12 wird Betriebsstandard.

Im Repo: demo_workspace/AGENTS.md (+ Override, CLAUDE.md, docs/agent/, ADR) · Server 02–04 · host-config.example.json

10.13.1 Zielbild

{ width=100% }

Schicht	Demo-Pfad / Server	Rolle
Policy (Markdown)	AGENTS.md, Overrides	Commands, Security, Done
Navigation	docs/agent/index.md	Progressive Disclosure
Entscheidungen	docs/adr/ + Memory-MCP	„Warum“ über Sessions
Struktur	codebase-graph MCP	Impact, Symbole
Aktionen	dev-tools MCP	read/write/test/issue
Verfahren	skills/*	Workflows on-demand
Runtime-Regeln	prompts/core_system.md	immer gültiger Core

10.13.2 Root-AGENTS.md und Overrides

Root bewusst kurz: Commands · harte Regeln · Nicht-Offensichtliches · Done-Policy · Landkarte · Pointer.
Override (src/billing/AGENTS.md) nur Deltas. Merge: innermost wins für Konflikte; Root-Security immer gültig. Host-Wrapper (CLAUDE.md) verweisen nur.

10.13.3 Graph + Memory anbinden

WORKSPACE_ROOT=examples/05-coding-agent/demo_workspace \
  python examples/03-codebase-graph/server.py
MEMORY_PATH=examples/05-coding-agent/.agent/project-memory.json \
  python examples/02-project-memory/server.py

ADRs im Git = Source of Truth für Reviews; Memory-MCP = querybare Schicht für Agenten.

10.13.4 End-to-End-Ladereihenfolge (DEMO-1)

Phase	Was laden	Medium
Start	Core Prompt	prompts/core_system.md
Start	Root + Override AGENTS	Markdown
Start	Skill Catalog L0	in agent.py
Step 1	Skill Body	skills/…
Step 2+	Issue, Conventions, Graph, Files, Tests	MCP
Trace	agents_files, skill_id, timeline, budget	JSON

10.13.5 Context-Lifecycle im Labor

Situation	Aktion	Artefakt
Slice fertig	Recovery Pack	docs/agent/recovery-pack.template.md
Window ~50–75 % voll	Compact mit Focus	Host /compact
Themenwechsel	neue Session + Pack	Issue/PR-Kommentar
Entscheidung	ADR + record_decision	überlebt Compact

Recovery Pack (Kern): goal, acceptance[], paths_in_scope[], decisions[], next_step, verify.last_result, skill_id.

10.13.6 Wann welchen Hebel?

Frage / Symptom	Primär
„Welchen Test-Befehl?“	AGENTS.md Commands
„Darf ich .env lesen?“	AGENTS.md + Hook
„Welche Dateien hängen an total?“	Graph MCP
„Warum 0.0 bei missing currency?“	ADR / Memory
„Wie fixe ich Issues standardmäßig?“	Skill fix-from-issue
„Session voll, Task nicht fertig“	Recovery Pack

10.13.7 Checkliste Produkt-Repo

• ☐ Root-AGENTS.md unter ~200 Zeilen
• ☐ Host-Wrapper nur Pointer
• ☐ Domain-Override an kritischem Pfad
• ☐ docs/agent/index.md + ADR-Ordner
• ☐ Graph-MCP mit Ignore-Listen
• ☐ Skills für Top-3-Workflows
• ☐ Recovery-Pack-Template
• ☐ Host-Config ohne Secrets
• ☐ CI: Policy-Tests + Trace-Schema

10.13.8 Done-Kriterien (Hybrid-KB + Demo-Trace)

Nach engineered Demo gilt 10.13 als Done, wenn der Trace zusätzlich zu 10.12.7 zeigt:

Trace-Feld / Signal	Erwartung
agents_files	≥ 2 (Root-AGENTS.md + src/billing/AGENTS.md)
resources_loaded	enthält memory://conventions (oder äquivalent im Working Set)
working_set	Pfad src/billing/invoice.py (oder Invoice-Hits aus Graph)
Graph-Tools	search_symbols und/oder impact_analysis in tools_called / timeline
optional	record_decision nach tests_ok

Lab-Check: python examples/05-coding-agent/agent.py --demo --profile engineered und Keys in runs/latest/context-trace.json abhaken – nicht nur „fühlt sich geladen an“.

---

Best Practices

1. Zuerst Server-Unit-Tests und Fake-MCP, dann LLM-Loop.
2. Stabile Tool-Namen und Return-Shapes.
3. Workspace-Root explizit setzen.
4. Outputs clippen; Secrets redakten; Traces speichern.
5. Memory = Entscheidungen, Graph = Struktur, Dev-Tools = Aktionen.
6. Offline-Demo für Onboarding.
7. Policy-Violations als automatisierte Tests.
8. Core kurz; Domäne in Skills.
9. Progressive Disclosure: Catalog → Body → Tools.
10. Done nur über Verify-Orakel.
11. AGENTS.md kanonisch; Host-Dateien nur Wrapper.
12. Vor Compact: Recovery Pack.
13. Lab-Code nummeriert/volatil; stabile Bausteine in patterns/.

---

Pitfalls

Pitfall	Folge	Gegenmaßnahme	Kapitel-Querverweis
God-Server mit Shell	Compromise	Domänen-Server	Kap. 10
Relative Paths ohne Root	Data leak	safe_path	Kap. 10
Unbegrenzte Diffs/Logs	Context death	clip + summary	Kap. 10
Index ohne Ignore	Secrets im Graph	deny + Test	Kap. 10
Agent „fertig“ ohne Tests	Scheinqualität	hard Oracle	Kap. 10
Host-Config mit Tokens in Git	Incident	env only	Kap. 10
10 kB Core mit allen Skills	Bloat	Core + Catalog	Kap. 10
Nur Happy-Path-CI	blinde Regression	Fake-MCP Violations	Kap. 10
Compact ohne Recovery Pack	Amnesie	Template + Memory/ADR	Kap. 10
Demo-Code 1:1 in Prod	Scheinsicherheit	10.11-Tabelle	Kap. 10

---

Key Takeaways

• Hands-on-Kern: Memory + Graph + Dev-Tools + Loop + Trace + Policy über MCP — als Architektur, nicht als Framework-Lock-in.
• First Success in 5 Minuten ist Teil der Architekturqualität, nicht nur DX-Kosmetik.
• Context Engineering ist messbar (Baseline vs. engineered Traces).
• Permissions, Redaction und HITL gehören ins Labor, nicht nur ins Security-Kapitel.
• Fake-MCP und golden Traces machen den Companion CI-first-class.
• Server-SDKs (Illustration: FastMCP, Stand Juli 2026) machen Primitives schnell exponierbar; Design der Tools entscheidet über Sicherheit und Nutzbarkeit.
• System Prompt Engineering: knapper Core, versioniert, Done = Tools. Skill Engineering: Progressive Disclosure, DoD, empfohlene MCP-Tools.
• Hybrid-KB: hierarchische AGENTS.md + Graph + Memory + Skills.
• Der Weg zur Plattform ist Versionierung, Eval, Gateway und Policy — nicht ein größerer Prompt.
• Konkrete APIs sind zeitgebunden; übertragbar sind Schnitt, Policies und Observability.

---

Was als Nächstes kommt

Kapitel 11 vertieft Risiken und verantwortungsvollen Einsatz — Threat Modeling für MCP, Governance der Kontextqualität und Harness Engineering für Produktions-Agenten (Permissions, Hooks, SLOs, Autonomy-Gates). Jeder Control-Plane-Hebel dort hatte einen Lab-Vorgänger in 10.10 L3 und 10.8 Traces.

---

Schnellstart (Copy-Paste)

cd code
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m pytest tests -q
python examples/05-coding-agent/agent.py --demo --profile engineered
python examples/05-coding-agent/agent.py --demo --profile baseline
# Artefakte: runs/latest/context-trace.json

Übungsanregungen (mit Definition of Done)

1. L0: Companion-Demo + Trace speichern · DoD: ☐ tests_ok ☐ runs/latest existiert
2. L3: Policy-Tests grün · DoD: ☐ .env deny ☐ Redaction ☐ HITL
3. L5: Baseline vs. engineered Tabelle · DoD: ☐ zwei Profiles ☐ Policy-Entscheidung notiert
4. Plattform: 10.11-Memo (5 Artefakte behalten/wegwerfen) · Zeit: ~20 Min