--- title: "Claude Code Subagents erklaert (mit Beispielen)" description: "Was Claude Code Subagents sind, wann du sie nutzt und wie du einen in .claude/agents mit YAML-Frontmatter erstellst. Built-in Subagents, Beispiele und der /agents-Befehl." type: "guide" locale: "de-CH" category: "Claude Code" canonical: "https://agenticschool.dev/de/ratgeber/claude-code-subagents" datePublished: "2026-06-13" dateModified: "2026-06-13" --- # Claude Code Subagents erklaert (mit Beispielen) - Kategorie: Claude Code - Keywords: claude code subagents, claude code agents, how to create a subagent, claude code agent teams, subagent vs main agent - Kanonische URL: https://agenticschool.dev/de/ratgeber/claude-code-subagents - Sprache: de-CH > Was Claude Code Subagents sind, wann du sie nutzt und wie du einen in .claude/agents mit YAML-Frontmatter erstellst. Built-in Subagents, Beispiele und der /agents-Befehl. Ein Claude Code Subagent ist ein spezialisierter Assistent, an den der Hauptagent eine fokussierte Aufgabe delegiert, der in seinem eigenen separaten Context Window mit eigenem System Prompt und eigenem, eingegrenztem Tool-Set läuft. Statt dass die Hauptsession alles macht und sich mit lautem Output füllt, übergibt sie einen Job (prüfe diesen Code, recherchiere diese Frage, führe diese Tests aus) an einen Subagent, der isoliert arbeitet und nur eine saubere Zusammenfassung zurückgibt. Dieser Guide erklärt, was Subagents sind, wann sie sich lohnen, welche Built-in-Subagents Claude Code mitbringt und wie genau du eigene mit dem /agents-Befehl oder einer Markdown-Datei in .claude/agents erstellst. ## Was ein Subagent tatsächlich ist Jeder Subagent läuft in seinem eigenen Context Window mit einem eigenen System Prompt, spezifischem Tool-Zugriff und unabhängigen Permissions. Wenn Claude auf eine Aufgabe trifft, die zur Beschreibung eines Subagents passt, delegiert er an diesen Subagent, der unabhängig arbeitet und sein Ergebnis zurückgibt. Das Schlüsselwort ist Isolation: All die unordentliche Zwischenarbeit, das Dutzend Dateien, das er gelesen hat, die fehlgeschlagenen Ansätze, der rohe Befehls-Output, bleibt im Fenster des Subagents und berührt die Hauptkonversation nie. Der Hauptagent bekommt nur die Schlussfolgerung. - Separates Context Window: Der Subagent erbt nicht deine ganze Hauptkonversation. - Eigener System Prompt: ein kurzes, fokussiertes Briefing, auf seinen einen Job zugeschnitten. - Eingegrenzte Tools und Permissions: nur was die Aufgabe braucht, oft read-only. - Gibt eine Zusammenfassung zurück: Die laute Arbeit wird absorbiert, die Hauptsession bekommt das saubere Ergebnis. ## Wann du einen Subagent nutzt Greif zu einem Subagent, wenn eine Nebenaufgabe deine Hauptkonversation mit Suchergebnissen, Logs oder Dateiinhalten fluten würde, auf die du nie wieder zurückgreifst. Der Subagent erledigt diese Arbeit in seinem eigenen Kontext und gibt nur die Antwort zurück, sodass dein Hauptfenster scharf bleibt und du die Performance-Klippe vermeidest, die zuschlägt, wenn sich ein Context Window mit Lärm füllt. Definiere einen eigenen Subagent, wenn du immer wieder dieselbe Art Arbeiter mit denselben Anweisungen startest: einen Code Reviewer, einen Test-Writer, einen Docs-Generator. - Kontext schonen: Halte Exploration und Massen-Lesen aus deiner Hauptkonversation heraus. - Constraints durchsetzen: Beschränke einen Subagent auf read-only Tools, damit ein Reviewer nicht editieren kann. - Verhalten spezialisieren: Ein fokussierter System Prompt macht ihn bei seinem einen Job zuverlässiger. - Kosten steuern: Leite enge Arbeit an ein schnelleres, günstigeres Modell wie Haiku. ## Built-in Subagents, die du schon hast Claude Code bringt Built-in-Subagents mit, die er automatisch nutzt, sodass du von Subagents profitierst, bevor du je einen erstellst. Explore ist ein schneller, read-only Agent zum Durchsuchen und Verstehen einer Codebasis, oft auf Haiku, um ihn günstig zu halten. Plan ist der Recherche-Agent, der im Plan-Modus Kontext sammelt, bevor er einen Plan vorschlägt. General-purpose erledigt komplexe, mehrstufige Aufgaben, die sowohl Exploration als auch Änderungen brauchen. Du kannst einen Built-in-Typ bei Bedarf über Permissions blockieren, aber meistens lässt du sie ihren Job machen. - Explore: schnelle, read-only Codebase-Suche und -Analyse (oft Haiku). - Plan: read-only Recherche-Agent, der im Plan-Modus Kontext sammelt. - General-purpose: Voll-Tool-Agent für komplexe, mehrstufige Arbeit. ## Einen eigenen Subagent erstellen Subagents sind Markdown-Dateien mit YAML-Frontmatter. Der einfachste Weg, einen zu erstellen, ist der /agents-Befehl, der ein geführtes Interface öffnet, in dem du den Subagent benennst, seine Beschreibung schreibst, seine Tools und sein Modell wählst und Claude den System Prompt für dich entwerfen lassen kannst. Projekt-Subagents leben in .claude/agents/ (committe sie in die Versionskontrolle, damit dein Team sie teilt); persönliche leben in ~/.claude/agents/ und folgen dir über Projekte hinweg. Im Frontmatter sind nur name und description Pflicht; die description ist das, was Claude liest, um zu entscheiden, wann er delegiert, also schreib sie klar. ```markdown --- name: code-reviewer description: Reviews code for quality and best practices. Use proactively after code changes. tools: Read, Glob, Grep model: sonnet --- You are a senior code reviewer. When invoked, analyse the changed code and return a concise, prioritised list of issues covering correctness, security and readability. Do not edit files; only report. Cite the file and line for each issue and suggest the smallest fix. ``` Ein echter read-only Code-Reviewer-Subagent unter .claude/agents/code-reviewer.md. Nur name und description sind Pflicht. Direkt auf der Platte angelegte Dateien werden beim Session-Start geladen, also starte Claude Code neu (oder erstell ihn über /agents, was sofort wirkt), um eine neue Datei zu übernehmen. Das model-Feld akzeptiert sonnet, opus, haiku oder inherit; das tools-Feld erbt standardmässig alle Tools, wenn du es weglässt. ## Subagents aufrufen und mit ihnen arbeiten Meistens rufst du einen Subagent nicht von Hand auf: Claude liest die description jedes Subagents und delegiert automatisch, wenn eine Aufgabe passt. Du kannst ihn auch explizit anstossen, zum Beispiel "nutze den code-reviewer Agent, um diesen Diff zu prüfen". Ein gutes Muster ist, das Feature mit deinem Hauptagenten zu schreiben und dann das Review an einen read-only Reviewer-Subagent zu delegieren, der den Diff in seinem eigenen Kontext inspiziert und eine knappe Issue-Liste zurückgibt, woraufhin der Hauptagent sie behebt. Weil das Review-Reasoning nie in dein Hauptfenster geladen wurde, bleibt die Session sauber. ## Schritte ### 1. Das Subagents-Interface öffnen Führe in einer Claude-Code-Session /agents aus, um das geführte Interface zum Erstellen und Verwalten von Subagents zu öffnen. ### 2. Einen Scope wählen und erstellen Wähle Project (.claude/agents/, geteilt via Versionskontrolle) oder Personal (~/.claude/agents/, all deine Projekte), dann erstelle einen neuen Agenten. Du kannst Claude den Identifier, die Beschreibung und den System Prompt generieren lassen. ### 3. Eine klare Beschreibung schreiben Die description ist das, womit Claude entscheidet, wann er delegiert, also sag genau, wann dieser Subagent genutzt werden soll. name und description sind die einzigen Pflichtfelder. ### 4. Tools und Modell eingrenzen Beschränke die Tools auf das, was die Aufgabe braucht (für einen Reviewer: read-only), und wähle ein Modell. Leite enge Arbeit an ein günstigeres Modell wie Haiku, um Kosten zu steuern. ### 5. Speichern und ausprobieren Speichere den Subagent und teste ihn, indem du Claude bittest, ihn zu nutzen. Wenn du die Datei stattdessen direkt auf der Platte angelegt hast, starte die Session neu, damit sie geladen wird. ## Häufige Fragen ### Was ist ein Claude Code Subagent? Es ist ein spezialisierter Assistent, an den der Hauptagent eine fokussierte Aufgabe delegiert. Jeder Subagent läuft in seinem eigenen Context Window mit eigenem System Prompt, eingegrenzten Tools und unabhängigen Permissions, erledigt die Arbeit isoliert und gibt nur eine Zusammenfassung zurück, damit die Hauptkonversation sauber bleibt. ### Wo leben Claude Code Subagents? Projekt-Subagents leben in .claude/agents/ in deinem Repo (committe sie, damit dein Team sie teilt). Persönliche Subagents leben in ~/.claude/agents/ und sind über all deine Projekte verfügbar. Jeder ist eine Markdown-Datei mit YAML-Frontmatter. ### Wie erstelle ich einen Subagent in Claude Code? Führe /agents aus, um das geführte Interface zu öffnen, wähle einen Scope (project oder personal), schreib eine klare description, grenze Tools und Modell ein und speichere. Du kannst die Markdown-Datei auch von Hand in .claude/agents/ anlegen, mit name und description im Frontmatter, und dann die Session neu starten, damit sie geladen wird. ### Wann sollte ich einen Subagent statt des Hauptagenten nutzen? Nutze einen, wenn eine Nebenaufgabe deine Hauptkonversation mit Output fluten würde, den du nicht wiederverwendest, etwa viele Dateien lesen, suchen oder reviewen. Der Subagent absorbiert diesen Lärm in seinem eigenen Kontext und gibt nur das Ergebnis zurück, hält dein Hauptfenster scharf und vermeidet die Kontext-Klippe. ### Teilt ein Subagent den Kontext des Hauptagenten? Nein. Ein Subagent läuft in einem separaten Context Window und sieht nur seinen eigenen System Prompt und die delegierte Aufgabe, nicht deine ganze Konversation. Diese Isolation ist der ganze Sinn: Sie verhindert, dass sich der Hauptkontext mit Lärm füllt. ### Kann ein Subagent ein günstigeres Modell als mein Hauptagent nutzen? Ja. Setze das model-Feld im Subagent-Frontmatter auf haiku (oder sonnet, opus oder inherit). Enge Extraktions- oder Review-Aufgaben an ein schnelles, günstiges Modell zu leiten, während dein Hauptagent ein stärkeres nutzt, ist ein guter Weg, Kosten zu steuern.