Claude Code-Funktionen im SDK verwenden
Laden Sie Projektanweisungen, Skills, Hooks und andere Claude Code-Funktionen in Ihre SDK-Agenten.
Das Agent SDK basiert auf der gleichen Grundlage wie Claude Code, was bedeutet, dass Ihre SDK-Agenten Zugriff auf die gleichen dateisystemgestützten Funktionen haben: Projektanweisungen (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:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async for message in query(
prompt="Help me refactor the auth module",
options=ClaudeAgentOptions(
# "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
# Together they give the agent access to CLAUDE.md, skills, hooks, and
# permissions from both locations.
setting_sources=["user", "project"],
allowed_tools=["Read", "Edit", "Bash"],
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
if isinstance(message, ResultMessage) and message.subtype == "success":
print(f"\nResult: {message.result}")
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me refactor the auth module",
options: {
// "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
// Together they give the agent access to CLAUDE.md, skills, hooks, and
// permissions from both locations.
settingSources: ["user", "project"],
allowedTools: ["Read", "Edit", "Bash"]
}
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "text") console.log(block.text);
}
}
if (message.type === "result" && message.subtype === "success") {
console.log(`\nResult: ${message.result}`);
}
}
Jede Quelle lädt Einstellungen von einem bestimmten Ort, wobei <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/ und jedes übergeordnete Verzeichnis bis zur Dateisystemwurzel (Stopp, wenn ein .claude/ gefunden wird oder keine weiteren übergeordneten Verzeichnisse vorhanden sind) |
"user" |
Benutzer-CLAUDE.md, ~/.claude/rules/*.md, Benutzer-Skills, Benutzereinstellungen |
~/.claude/ |
"local" |
CLAUDE.local.md (gitignoriert), .claude/settings.local.json |
<cwd>/ |
Das Weglassen von settingSources entspricht ["user", "project", "local"].
Die cwd-Option bestimmt, wo das SDK nach Projekteinstellungen sucht. Wenn weder cwd noch eines seiner übergeordneten Verzeichnisse einen .claude/-Ordner enthält, werden Funktionen auf Projektebene nicht geladen.
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 |
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 |
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 (gitignoriert) | <cwd>/CLAUDE.local.md |
settingSources enthält "local" |
| Benutzer | ~/.claude/CLAUDE.md |
settingSources enthält "user" |
| Benutzerregeln | ~/.claude/rules/*.md |
settingSources enthält "user" |
Alle Ebenen sind additiv: Wenn sowohl Projekt- als auch Benutzer-CLAUDE.md-Dateien vorhanden sind, sieht der Agent beide. Es gibt keine harte Vorrangregel zwischen Ebenen; wenn Anweisungen in Konflikt geraten, hängt das Ergebnis davon ab, wie Claude sie interpretiert. Schreiben Sie nicht in Konflikt stehende Regeln, oder geben Sie den Vorrang explizit in der spezifischeren Datei an („Diese Projektanweisungen überschreiben alle in Konflikt stehenden Benutzer-Level-Standardwerte").
Informationen zur Strukturierung und Organisation von CLAUDE.md-Inhalten finden Sie unter Claudes Speicher verwalten.
Skills
Skills sind Markdown-Dateien, die Ihrem Agenten spezialisiertes Wissen und aufrufbare Workflows geben. Im Gegensatz zu CLAUDE.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. Das SDK aktiviert das Skill-Tool automatisch, wenn skills gesetzt ist, daher müssen Sie es nicht zu allowedTools hinzufügen.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
prompt="Review this PR using our code review checklist",
options=ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
import { query } from "@anthropic-ai/claude-agent-sdk";
// Skills in .claude/skills/ are discovered automatically
// when settingSources includes "project"
for await (const message of query({
prompt: "Review this PR using our code review checklist",
options: {
settingSources: ["user", "project"],
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
Weitere Informationen zum Erstellen und Verwenden von Skills finden Sie unter Agent Skills im SDK.
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.
Beide Typen werden während des gleichen Hook-Lebenszyklus ausgeführt. Wenn Sie bereits Hooks in der .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 {} (ein leeres Dict) bedeutet, dass das Tool fortfahren darf. Das Zurückgeben von {"decision": "block", "reason": "..."} verhindert die Ausführung und der Grund wird Claude als Tool-Ergebnis gesendet. Siehe das Hooks-Handbuch für die vollständige Callback-Signatur und Rückgabetypen.
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
# PreToolUse hook callback. Positional args:
# input_data: HookInput dict with tool_name, tool_input, hook_event_name
# tool_use_id: str | None, the ID of the tool call being intercepted
# context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
command = input_data.get("tool_input", {}).get("command", "")
if "rm -rf" in command:
return {"decision": "block", "reason": "Destructive command blocked"}
return {} # Empty dict: allow the tool to proceed
# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
prompt="Refactor the auth module",
options=ClaudeAgentOptions(
setting_sources=["project"], # Loads hooks from .claude/settings.json
hooks={
"PreToolUse": [
HookMatcher(matcher="Bash", hooks=[audit_bash]),
]
},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";
// PreToolUse hook callback. HookInput is a discriminated union on
// hook_event_name, so narrowing on it gives TypeScript the right
// tool_input shape for this event.
const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
if (input.hook_event_name !== "PreToolUse") return {};
const toolInput = input.tool_input as { command?: string };
if (toolInput.command?.includes("rm -rf")) {
return { decision: "block", reason: "Destructive command blocked" };
}
return {}; // Empty object: allow the tool to proceed
};
// Filesystem hooks from .claude/settings.json run automatically
// when settingSources loads them. You can also add programmatic hooks:
for await (const message of query({
prompt: "Refactor the auth module",
options: {
settingSources: ["project"], // Loads hooks from .claude/settings.json
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
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; Rückgabe strukturierter Entscheidungen; In-Process-Integration. Auf die Hauptsitzung beschränkt. |
Vollständige Details zu programmgesteuerten Hooks finden Sie unter Ausführung mit Hooks kontrollieren. Für Dateisystem-Hook-Syntax siehe Hooks.
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 |
Jede Funktion, die Sie aktivieren, trägt zu Ihrem Agent-Kontextfenster bei. Für Pro-Funktion-Kosten und wie diese Funktionen zusammen funktionieren, siehe Claude Code erweitern.
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