Claude Code Intensivschulung: agentische Systeme und Agent SDK

Agentische Architekturen verstehen und den Agentic Loop beherrschen

• Agentische Architektur und Orchestrierung: Modell, Werkzeuge, Steuerlogik und Zustand
• Aufbau und Funktionsweise des Agentic Loop: Anfrage, Werkzeugaufruf, Ergebnis, nächste Runde
• Das Feld stop_reason korrekt interpretieren: end_turn, tool_use, max_tokens und weitere Werte
• Auf tool_use gezielt verzweigen und mehrere Werkzeugaufrufe einer Antwort abarbeiten
• Werkzeugergebnisse als tool_result mit passender ID sauber an die Historie anhängen
• Den Loop kontrolliert und korrekt fortsetzen
• Zustandsinformationen zwischen Iterationen bewahren
• Fehler durch unvollständige Historie vermeiden: fehlende Ergebnisse, vertauschte Reihenfolge
• Zu frühes Beenden des Agentic Loop erkennen
• Robuste Abbruchbedingungen für produktive Systeme definieren: Rundenlimit, Zeit, Budget
• Agent SDK als fertiger Loop: wann der eigene Loop über die Messages API sinnvoller ist

Hub-and-Spoke-Architekturen für Multi-Agenten-Systeme entwerfen

• Grundlagen des Hub-and-Spoke-Modells: ein Koordinator, spezialisierte Subagenten
• Kommunikationsflüsse zwischen Koordinator und Subagenten
• Komplexe Aufgaben sinnvoll zerlegen
• Subagenten gezielt aufrufen und steuern
• Relevanten Kontext vollständig im Auftrag an spezialisierte Agenten übergeben
• Ergebnisse mehrerer Agenten konsolidieren
• Fehler einzelner Subagenten kontrolliert behandeln
• Fehlendes Gedächtnis zwischen Koordinator und Subagent verstehen: jeder Subagent startet ohne Vorgeschichte
• Unvollständige Koordinatorausgaben diagnostizieren
• Rollen, Verantwortlichkeiten und Übergabepunkte sauber definieren
• Wann ein einzelner Agent genügt: Mehrkosten und Fehlerquellen von Multi-Agenten-Systemen

Agent-Tool (früher Task-Tool) und parallele Ausführung strategisch einsetzen

• Einführung in das Werkzeug Agent zum Starten von Subagenten (bis Version 2.1.63 Task-Tool)
• Agent läuft ohne Rückfrage: Delegation über tools oder disallowedTools steuern, nicht über allowedTools
• Subagenten parallel ausführen
• Sequenzielle und parallele Aufrufe unterscheiden
• Abhängigkeiten zwischen Teilaufgaben erkennen
• Ergebnisse paralleler Prozesse zusammenführen
• Risiken konkurrierender Agentenaktivitäten bewerten: gleiche Dateien, Git-Worktrees zur Trennung
• Die Stakes-Proportionate-Regel praktisch anwenden: Kontrolle wächst mit der Tragweite
• Kosten, Geschwindigkeit und Kontrollbedarf austarieren

Programmatic Control, Gates und Hooks für belastbare Abläufe

• Programmatic Gates verstehen: Code entscheidet, nicht die Formulierung im Prompt
• Kritische Aktionen technisch absichern
• Tool Call Interception mit PreToolUse-Hooks: erlauben, ablehnen, nachfragen
• PostToolUse-Hooks verstehen
• Ergebnisse nach Werkzeugaufrufen prüfen und Rückmeldung an den Agenten geben
• Regelverstöße programmatisch erkennen
• Promptsteuerung und technische Kontrolle kombinieren
• Grenzen rein sprachlicher Instruktionen erkennen
• Kontrollpunkte für sensible Workflows entwerfen
• Hooks in Claude Code und Hook-Callbacks im Agent SDK vergleichen

Tool Design und MCP-Integration professionell gestalten

• Grundlagen guten Tool Designs: ein Zweck, klare Namen, kleine Ein- und Ausgaben
• MCP-Integration strukturiert planen
• Einfluss von Werkzeugbeschreibungen auf die Auswahl durch das Modell
• Vage Beschreibungen identifizieren
• Tool-Fehlselektion systematisch diagnostizieren
• Vollständige Werkzeugbeschreibungen verfassen
• Eingaben, Ausgaben und Grenzen eindeutig dokumentieren
• Den Abschnitt „vs. similar tools“ gezielt einsetzen
• Überlappende Werkzeuge voneinander abgrenzen
• Tool-Portfolios für zuverlässige Auswahl optimieren
• Eigene MCP-Server mit dem offiziellen SDK in TypeScript oder Python bauen und mit dem MCP Inspector testen

Fehlerbehandlung für produktive Agentensysteme entwickeln

• Transiente Fehler erkennen und behandeln: Zeitüberschreitung, Rate Limits, Überlastung
• Validierungsfehler sauber zurückgeben
• Business-Logic-Fehler modellieren
• Permission Failures unterscheiden
• Zugriffsfehler von gültigen leeren Ergebnissen trennen
• Eindeutig unterscheidbare Fehlerantworten entwerfen, z. B. is_error im Werkzeugergebnis
• Retry-Strategien passend zum Fehlertyp definieren
• Fehlerkontext für nachgelagerte Agenten erhalten
• Unnötige Wiederholungen und Retry-Schleifen vermeiden

MCP-Konfiguration zwischen Projekt und Benutzer sauber organisieren

• Projektweite MCP-Konfiguration in .mcp.json verstehen
• Benutzerbezogene und lokale MCP-Konfiguration einordnen
• Zuständigkeiten der Konfigurationsebenen trennen
• Teamweit benötigte Serverzugriffe planen: Umgebungsvariablen statt Zugangsdaten im Repository
• Persönliche Entwicklungswerkzeuge abgrenzen
• Fehlenden MCP-Server-Zugriff diagnostizieren: /mcp, Freigabe projektweiter Server, Anmeldung
• Konfigurationskonflikte erkennen
• Reproduzierbare Setups für Teams entwickeln

Tool Scoping und Agentenrollen präzise zuschneiden

• Auswirkungen zu großer Werkzeugmengen verstehen: Fehlauswahl und Kontextverbrauch
• Sinnvolle Werkzeuganzahl pro Agent bestimmen
• Werkzeuge nach Agentenrolle zuschneiden: tools bzw. disallowedTools; allowedTools gibt nur frei, schränkt nicht ein
• Verantwortungsbereiche voneinander trennen
• Spezialagenten statt Universalagenten entwerfen
• Werkzeugüberschneidungen reduzieren
• Least Capability als Designprinzip nutzen
• Agentenrollen für Wartbarkeit und Skalierung strukturieren
• Werkzeugsuche mit Laden bei Bedarf, wenn viele MCP-Werkzeuge unvermeidbar sind

CLAUDE.md-Hierarchie für konsistente Entwicklungsworkflows nutzen

• Einführung in die CLAUDE.md-Hierarchie: Organisation, Benutzer, Projekt, Unterverzeichnis
• Projektweite Konventionen definieren
• Verzeichnisspezifische Regeln einsetzen
• Benutzerbezogene Vorgaben verwalten
• Gültigkeitsbereiche verschiedener Ebenen verstehen: was immer, was erst beim Zugriff geladen wird
• Teamstandards konsistent abbilden
• Ignorierte Konventionen diagnostizieren
• Widersprüchliche Instruktionen erkennen
• Konfigurationsstrukturen für größere Repositories und Monorepos planen
• Wiederverwendung über @-Importe statt kopierter Abschnitte

Agent Skills entwickeln, strukturieren und skalieren

• CLAUDE.md und Agent Skills unterscheiden
• Unterschiedliche Lademechanismen verstehen: immer geladen gegenüber bei Bedarf über die Beschreibung
• Universelle Standards richtig platzieren
• Aufgabenspezifische Workflows modularisieren
• Grundlagen von Agent Skills: SKILL.md, Frontmatter, Skripte und Referenzdateien
• Skills erstellen und strukturieren
• Passende Einsatzgebiete identifizieren
• Skills mit Subagents, Hooks und Slash-Befehlen vergleichen
• Konfiguration fortgeschrittener Skills: erlaubte Werkzeuge, Modell, Aufruf nur durch Menschen
• Skill-Landschaften für größere Teams skalieren: Plugins und Marktplätze
• Skills im Agent SDK und über die API wiederverwenden

Context Fork und pfadspezifische Regeln gezielt einsetzen

• context: fork verstehen: Skill läuft in eigenem Subagent-Kontext
• Geeignete Einsatzszenarien erkennen
• Pfadspezifische Regeln in .claude/rules/ einführen
• Path Specific Rules von CLAUDE.md in Unterverzeichnissen unterscheiden
• Kontextvererbung kontrollieren
• Auswirkungen auf das Token-Budget bewerten
• Regeln nur dort laden, wo sie relevant sind
• Große Codebasen kontextbewusst strukturieren

Claude Code über CLI-Flags und CI/CD automatisieren

• Bedeutung des Flags -p: einmaliger, nicht interaktiver Lauf
• Nicht interaktive Aufrufe planen: Rechte, Werkzeuge und Rundenlimit per Flag festlegen
• Claude Code in CI/CD-Pipelines integrieren: GitHub Actions, GitLab CI/CD (Beta)
• Automatisierte Prüfprozesse gestalten
• Reproduzierbare Prompt-Abläufe entwickeln: Prompt-Dateien versionieren, Konfiguration fixieren
• Ausgaben für nachgelagerte Schritte nutzbar machen: --output-format json und stream-json
• Fehlerzustände in Pipelines behandeln: Exit-Codes, Zeitlimits, Wiederaufnahme
• Kontrollmechanismen für automatisierte Agentenläufe einbauen
• Vom CLI-Aufruf zum Agent SDK: dieselben Werkzeuge programmatisch in Python oder TypeScript

Match Criteria und Few-Shot-Beispiele präzise formulieren

• Grenzen subjektiver Confidence-Formulierungen verstehen
• Explizite Match Criteria definieren
• Positive Trefferbedingungen beschreiben
• Non-Matches eindeutig formulieren
• Edge Cases systematisch erfassen
• Few-Shot-Beispiele gezielt einsetzen
• Geeignete Anzahl von Beispielen bestimmen
• Entscheidungslogik statt bloßer Antworten demonstrieren
• Beispiele auf reale Grenzfälle ausrichten
• Kriterien mit einem Evaluationsdatensatz messen statt nach Gefühl nachschärfen

JSON Schema und Structured Output zuverlässig einsetzen

• Strukturierte Ausgaben mit tool_use und Eingabeschema gestalten
• JSON Schema zur Syntaxkontrolle einsetzen; Structured Outputs garantieren schemakonforme Antworten
• Pflichtfelder sinnvoll definieren
• Risiken erfundener Werte verstehen
• Empty Field Fabrication erkennen
• Optionale Felder gezielt nutzen
• Nullable Fields korrekt modellieren
• Enum-Werte bei Mehrdeutigkeit einsetzen, mit Ausweichwert wie unklar
• Schema-Design und fachliche Validierung kombinieren
• Strukturierte Ausgabe im headless Lauf und im Agent SDK

API-Auswahl zwischen Kosten, Latenz und Durchsatz treffen

• Synchrone API-Aufrufe einordnen
• Geeignete Szenarien für synchrone Verarbeitung
• Message Batches API verstehen: asynchron, deutlich günstiger, Ergebnis später
• Batch-Verarbeitung wirtschaftlich einsetzen
• Kosten gegen Latenz abwägen
• Durchsatzanforderungen und Rate Limits berücksichtigen
• Nutzererwartungen in die Architekturentscheidung einbeziehen
• Unterschiedliche Verarbeitungspfade kombinieren
• Prompt Caching für wiederkehrende Systemprompts und Werkzeugdefinitionen

Context Window Management für lange und komplexe Aufgaben

• Strategien für zuverlässiges Context Management
• Progressive Summarization kritisch bewerten
• Detailverlust über lange Abläufe erkennen, auch nach automatischer Compaction
• Case-Facts-Blöcke aufbauen: unveränderliche Fakten getrennt vom Verlauf
• Das Lost-in-the-Middle-Problem verstehen
• Schlüsselerkenntnisse an prominenter Stelle platzieren
• Strukturierte Tags zur Orientierung nutzen
• Ausführliche Werkzeugergebnisse kürzen
• Relevanz und Vollständigkeit austarieren
• Lang laufende Agentenprozesse stabilisieren
• Zustand außerhalb des Kontexts halten: Notizdateien, Memory-Werkzeug, Fortschrittsprotokoll

Eskalationstrigger für Human-in-the-Loop-Prozesse definieren

• Direkte menschliche Anfragen als Trigger erkennen
• Authority Gaps identifizieren
• Verification Flags korrekt behandeln
• Frustration von echter Eskalationsnotwendigkeit unterscheiden
• Komplexität nicht automatisch mit Eskalation gleichsetzen
• Frustrierte Kund:innen bei einfachen Anliegen sinnvoll führen
• Sofortige Eskalationsfälle definieren
• Untersuchungsbedarf vor Eskalation bewerten
• Human-in-the-Loop-Regeln nachvollziehbar gestalten
• Übergabe an Menschen mit vollständigem Fallprotokoll statt Rohverlauf

Fehlerkontext in Multi-Agenten-Systemen bewahren

• Strukturierten Fehlerkontext modellieren
• Fehler zwischen Agenten weiterreichen
• Bereits getestete Ansätze dokumentieren
• Alternative Vorgehensweisen sichtbar machen
• Wiederholung gescheiterter Strategien verhindern
• Fehlerursachen von Symptomen trennen
• Frühzeitig alternative Pfade aktivieren
• Nicht bis zur vollständigen Retry-Erschöpfung warten
• Multi-Agenten-Systeme aus Fehlschlägen handlungsfähiger machen
• Läufe beobachtbar machen: Traces je Agent und Werkzeugaufruf, Auswertung von Fehlschlägen

Claude Code und Agent SDK im Betrieb absichern: Rechte, Fremdinhalte, Budgets

• Werkzeugfreigaben im Agent SDK per Callback und Permission-Modus statt pauschaler Rechte
• Claude Code headless in CI nur mit expliziter Werkzeugliste und ohne Schreibrecht auf geschützte Branches
• Prompt Injection über MCP-Ergebnisse: Subagent mit Webzugriff erhält keine schreibenden Werkzeuge
• Budgets je Lauf: maximale Runden, Kostenobergrenze, Abbruch mit Statusbericht an den Koordinator
• Unbeaufsichtigte Läufe in Sandbox oder Container, jeder Werkzeugaufruf per Hook protokolliert

Praxisprojekt: Vorprüfung von Bauanträgen als Multi-Agenten-System

• Koordinator verteilt einen Bauantrag an Subagenten für Vollständigkeit, Abstandsflächen und Stellplätze
• Eigener MCP-Server liefert Bebauungsplan-Auszüge; Ergebnisse je Prüfung als JSON nach Schema
• Gates und Hooks verhindern Bescheide ohne Sachbearbeitung; unklare Fälle eskalieren mit Fallprotokoll
• Nächtliche Batch-Vorprüfung über die Pipeline, Kosten- und Fehlerauswertung am nächsten Morgen

Lernziele

• Sie implementieren einen Agentic Loop mit korrekter Behandlung von stop_reason, Werkzeugergebnissen und Abbruchbedingungen
• Sie entwerfen Hub-and-Spoke-Systeme mit vollständigen Übergaben, parallelen Subagenten und konsolidierten Ergebnissen
• Sie schreiben Werkzeugbeschreibungen und Fehlerantworten, die Fehlauswahl und Retry-Schleifen messbar verringern
• Sie verteilen Regeln passend auf CLAUDE.md-Ebenen, Skills, pfadspezifische Regeln und programmatische Gates
• Sie automatisieren Claude Code in CI/CD mit strukturierter Ausgabe und wählen zwischen synchroner API und Batch-Verarbeitung
• Sie halten lange Abläufe mit Case-Facts-Blöcken und Fehlerkontext stabil und definieren nachvollziehbare Eskalationstrigger

Zielgruppe

• Erfahrene Entwickler:innen, Software-Architekt:innen und AI Engineers, die Agentensysteme mit Claude Code oder dem Agent SDK produktiv betreiben
• DevOps- und Plattformteams, die Claude Code in Pipelines und automatisierte Prüfprozesse einbinden
• Voraussetzungen: sichere Praxis mit Claude Code, Programmiererfahrung in Python oder TypeScript, Grundkenntnisse der Messages API