CLAUDE.md und Regeln), Skills, Hooks und mehr.
Wenn Sie settingSources weglassen, liest query() die gleichen Dateisystemeinstellungen wie die Claude Code CLI: Benutzer-, Projekt- und lokale Einstellungen, CLAUDE.md-Dateien und .claude/-Skills, Agenten und Befehle. Um ohne diese auszuführen, übergeben Sie settingSources: [], was den Agenten auf das beschränkt, was Sie programmgesteuert konfigurieren. Verwaltete Richtlinieneinstellungen und die globale ~/.claude.json-Konfiguration werden unabhängig von dieser Option gelesen. Siehe Was settingSources nicht kontrolliert.
Für einen konzeptionellen Überblick über das, was jede Funktion tut und wann sie verwendet werden sollte, siehe Claude Code erweitern.
Dateisystemeinstellungen mit settingSources kontrollieren
Die Einstellungsquellen-Option (setting_sources in Python, settingSources in TypeScript) kontrolliert, welche dateisystemgestützten Einstellungen das SDK lädt. Übergeben Sie eine explizite Liste, um sich für bestimmte Quellen anzumelden, oder übergeben Sie ein leeres Array, um Benutzer-, Projekt- und lokale Einstellungen zu deaktivieren.
Dieses Beispiel lädt sowohl Benutzer- als auch Projektebenen-Einstellungen, indem settingSources auf ["user", "project"] gesetzt wird:
<cwd> das Arbeitsverzeichnis ist, das Sie über die cwd-Option übergeben, oder das aktuelle Verzeichnis des Prozesses, falls nicht gesetzt. Für die vollständige Typdefinition siehe SettingSource (TypeScript) oder SettingSource (Python).
| Quelle | Was wird geladen | Ort |
|---|---|---|
"project" | Projekt-CLAUDE.md, .claude/rules/*.md, Projekt-Skills, Projekt-Hooks, Projekt-settings.json | <cwd>/.claude/ für settings.json und Hooks; <cwd> und jedes übergeordnete Verzeichnis für CLAUDE.md und Regeln; <cwd> und jedes übergeordnete Verzeichnis bis zur Repository-Root für Skills |
"user" | Benutzer-CLAUDE.md, ~/.claude/rules/*.md, Benutzer-Skills, Benutzereinstellungen | ~/.claude/ |
"local" | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ für settings.local.json; <cwd> und jedes übergeordnete Verzeichnis für CLAUDE.local.md |
settingSources entspricht ["user", "project", "local"].
Die cwd-Option bestimmt, wo das SDK nach Projekteinstellungen sucht. CLAUDE.md und Regeln werden aus <cwd> und aus jedem übergeordneten Verzeichnis geladen. Skills werden aus <cwd> und aus jedem übergeordneten Verzeichnis bis zur Repository-Root geladen. Projekt-settings.json und Hooks werden nur aus <cwd>/.claude/ geladen, ohne Fallback für übergeordnete Verzeichnisse.
Was settingSources nicht kontrolliert
settingSources umfasst Benutzer-, Projekt- und lokale Einstellungen. Einige Eingaben werden unabhängig von ihrem Wert gelesen:
| Eingabe | Verhalten | Zum Deaktivieren |
|---|---|---|
| Verwaltete Richtlinieneinstellungen | Immer geladen, wenn auf dem Host vorhanden | Entfernen Sie die verwaltete Einstellungsdatei |
~/.claude.json globale Konfiguration | Immer gelesen | Verschieben Sie mit CLAUDE_CONFIG_DIR in env |
Automatisches Gedächtnis unter ~/.claude/projects/<project>/memory/ | Standardmäßig in die Systemaufforderung geladen | Setzen Sie autoMemoryEnabled: false in Einstellungen oder CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env |
| claude.ai MCP-Konnektoren | Geladen, wenn die aktive Authentifizierungsmethode ein claude.ai-Abonnement ist. Das Übergeben von mcpServers: {} unterdrückt sie nicht | Setzen Sie strictMcpConfig: true oder ENABLE_CLAUDEAI_MCP_SERVERS=false in env |
Projektanweisungen (CLAUDE.md und Regeln)
CLAUDE.md-Dateien und .claude/rules/*.md-Dateien geben Ihrem Agenten persistenten Kontext über Ihr Projekt: Codierungskonventionen, Build-Befehle, Architekturentscheidungen und Anweisungen. Wenn settingSources "project" enthält (wie im obigen Beispiel), lädt das SDK diese Dateien beim Sitzungsstart in den Kontext. Der Agent folgt dann Ihren Projektkonventionen, ohne dass Sie sie in jedem Prompt wiederholen müssen.
CLAUDE.md-Ladeorte
| Ebene | Ort | Wann geladen |
|---|---|---|
| Projekt (Wurzel) | <cwd>/CLAUDE.md oder <cwd>/.claude/CLAUDE.md | settingSources enthält "project" |
| Projektregeln | <cwd>/.claude/rules/*.md und .claude/rules/*.md in jedem übergeordneten Verzeichnis | settingSources enthält "project" |
| Projekt (übergeordnete Verzeichnisse) | CLAUDE.md-Dateien in Verzeichnissen über cwd | settingSources enthält "project", geladen beim Sitzungsstart |
| Projekt (Unterverzeichnisse) | CLAUDE.md-Dateien in Unterverzeichnissen von cwd | settingSources enthält "project", bei Bedarf geladen, wenn der Agent eine Datei in diesem Unterbaum liest |
| Lokal | <cwd>/CLAUDE.local.md und CLAUDE.local.md in jedem übergeordneten Verzeichnis | settingSources enthält "local" |
| Benutzer | ~/.claude/CLAUDE.md | settingSources enthält "user" |
| Benutzerregeln | ~/.claude/rules/*.md | settingSources enthält "user" |
Skills
Skills sind Markdown-Dateien, die Ihrem Agenten spezialisiertes Wissen und aufrufbare Workflows geben. Im Gegensatz zuCLAUDE.md (das jede Sitzung geladen wird) werden Skills bei Bedarf geladen. Der Agent erhält Skill-Beschreibungen beim Start und lädt den vollständigen Inhalt, wenn relevant.
Skills werden durch settingSources vom Dateisystem entdeckt. Wenn die skills-Option bei query() weggelassen wird, werden entdeckte Benutzer- und Projekt-Skills aktiviert und das Skill-Tool ist verfügbar, was dem CLI-Verhalten entspricht. Um zu steuern, welche Skills aktiviert sind, übergeben Sie skills als "all", eine Liste von Skill-Namen oder [], um alle zu deaktivieren. Wenn skills gesetzt ist, fügt das SDK das Skill-Tool automatisch zu allowedTools hinzu. Wenn Sie auch eine explizite tools-Liste übergeben, fügen Sie "Skill" in diese Liste ein, damit Claude Skills aufrufen kann.
Skills müssen als Dateisystem-Artefakte erstellt werden (
.claude/skills/<name>/SKILL.md). Das SDK hat keine programmgesteuerte API zum Registrieren von Skills. Siehe Agent Skills im SDK für vollständige Details.Hooks
Das SDK unterstützt zwei Möglichkeiten, Hooks zu definieren, und sie laufen nebeneinander:- Dateisystem-Hooks: Shell-Befehle, die in
settings.jsondefiniert sind und geladen werden, wennsettingSourcesdie relevante Quelle enthält. Dies sind die gleichen Hooks, die Sie für interaktive Claude Code-Sitzungen konfigurieren würden. - Programmgesteuerte Hooks: Callback-Funktionen, die direkt an
query()übergeben werden. Diese laufen in Ihrem Anwendungsprozess und können strukturierte Entscheidungen zurückgeben. Siehe Ausführung mit Hooks kontrollieren.
.claude/settings.json Ihres Projekts haben und Sie settingSources: ["project"] setzen, werden diese Hooks automatisch im SDK ohne zusätzliche Konfiguration ausgeführt.
Hook-Callbacks erhalten die Tool-Eingabe und geben ein Entscheidungs-Dict zurück. Das Zurückgeben von {} bedeutet, dass das Tool fortfahren darf. Um die Ausführung zu blockieren, geben Sie ein hookSpecificOutput-Objekt mit permissionDecision: "deny" und einem permissionDecisionReason zurück. Der Grund wird Claude als Tool-Ergebnis gesendet. Die Top-Level-Felder decision und reason sind für PreToolUse veraltet. Siehe das Hooks-Handbuch für die vollständige Callback-Signatur und Rückgabetypen.
Wann welcher Hook-Typ verwendet werden sollte
| Hook-Typ | Am besten für |
|---|---|
Dateisystem (settings.json) | Gemeinsame Nutzung von Hooks zwischen CLI- und SDK-Sitzungen. Unterstützt "command" (Shell-Skripte), "http" (POST an einen Endpunkt), "mcp_tool" (Aufrufen eines Tools eines verbundenen MCP-Servers), "prompt" (LLM wertet einen Prompt aus) und "agent" (spawnt einen Verifier-Agenten). Diese werden im Haupt-Agenten und allen Subagenten, die er spawnt, ausgeführt. |
Programmgesteuert (Callbacks in query()) | Anwendungsspezifische Logik, strukturierte Entscheidungen und In-Process-Integration. Diese werden auch in Subagenten ausgeführt. Der Callback empfängt agent_id und agent_type, um zu unterscheiden. |
Das TypeScript SDK unterstützt zusätzliche Hook-Events über Python hinaus, einschließlich
SessionStart, SessionEnd, TeammateIdle und TaskCompleted. Siehe das Hooks-Handbuch für die vollständige Ereigniskompatibilitätstabelle.Wählen Sie die richtige Funktion
Das Agent SDK gibt Ihnen Zugriff auf mehrere Möglichkeiten, das Verhalten Ihres Agenten zu erweitern. Wenn Sie unsicher sind, welche Sie verwenden sollten, ordnet diese Tabelle häufige Ziele dem richtigen Ansatz zu.| Sie möchten… | Verwenden Sie | SDK-Oberfläche |
|---|---|---|
| Projektkonventionen festlegen, die Ihr Agent immer befolgt | CLAUDE.md | settingSources: ["project"] lädt es automatisch |
| Dem Agenten Referenzmaterial geben, das er bei Bedarf lädt | Skills | settingSources + skills-Option |
| Einen wiederverwendbaren Workflow ausführen (bereitstellen, überprüfen, freigeben) | Benutzer-aufrufbare Skills | settingSources + skills-Option |
| Eine isolierte Teilaufgabe an einen frischen Kontext delegieren (Recherche, Überprüfung) | Subagenten | agents-Parameter + allowedTools: ["Agent"] |
| Mehrere Claude Code-Instanzen mit gemeinsamen Aufgabenlisten und direkter Inter-Agent-Messaging koordinieren | Agent-Teams | Nicht direkt über SDK-Optionen konfiguriert. Agent-Teams sind eine CLI-Funktion, bei der eine Sitzung als Team-Lead fungiert und die Arbeit über unabhängige Teammates koordiniert |
| Deterministische Logik auf Tool-Aufrufe ausführen (Audit, Block, Transform) | Hooks | hooks-Parameter mit Callbacks oder Shell-Skripte, die über settingSources geladen werden |
| Claude strukturierten Tool-Zugriff auf einen externen Service geben | MCP | mcpServers-Parameter |
Verwandte Ressourcen
- Claude Code erweitern: Konzeptioneller Überblick über alle Erweiterungsfunktionen mit Vergleichstabellen und Kontextkostenanalyse
- Skills im SDK: Vollständiges Handbuch zur programmgesteuerten Verwendung von Skills
- Subagenten: Definieren und rufen Sie Subagenten für isolierte Teilaufgaben auf
- Hooks: Abfangen und Kontrollieren des Agent-Verhaltens an wichtigen Ausführungspunkten
- Berechtigungen: Kontrollieren Sie Tool-Zugriff mit Modi, Regeln und Callbacks
- Systemaufforderungen: Injizieren Sie Kontext ohne CLAUDE.md-Dateien