Utiliser les fonctionnalités de Claude Code dans le SDK
Chargez les instructions de projet, les compétences, les hooks et autres fonctionnalités de Claude Code dans vos agents SDK.
Le SDK Agent est construit sur la même base que Claude Code, ce qui signifie que vos agents SDK ont accès aux mêmes fonctionnalités basées sur le système de fichiers : instructions de projet (CLAUDE.md et règles), compétences, hooks, et bien plus.
Lorsque vous omettez settingSources, query() lit les mêmes paramètres du système de fichiers que l'interface de ligne de commande Claude Code : paramètres utilisateur, projet et locaux, fichiers CLAUDE.md, et compétences, agents et commandes .claude/. Pour fonctionner sans ces éléments, passez settingSources: [], ce qui limite l'agent à ce que vous configurez par programmation. Les paramètres de politique gérée et la configuration globale ~/.claude.json sont lus indépendamment de cette option. Voir Ce que settingSources ne contrôle pas.
Pour une vue d'ensemble conceptuelle de ce que chaque fonctionnalité fait et quand l'utiliser, voir Étendre Claude Code.
Contrôler les paramètres du système de fichiers avec settingSources
L'option des sources de paramètres (setting_sources en Python, settingSources en TypeScript) contrôle quels paramètres basés sur le système de fichiers le SDK charge. Passez une liste explicite pour accepter des sources spécifiques, ou passez un tableau vide pour désactiver les paramètres utilisateur, projet et locaux.
Cet exemple charge à la fois les paramètres au niveau utilisateur et au niveau projet en définissant settingSources sur ["user", "project"] :
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}`);
}
}
Chaque source charge les paramètres à partir d'un emplacement spécifique, où <cwd> est le répertoire de travail que vous passez via l'option cwd, ou le répertoire courant du processus s'il n'est pas défini. Pour la définition de type complète, voir SettingSource (TypeScript) ou SettingSource (Python).
| Source | Ce qu'elle charge | Emplacement |
|---|---|---|
"project" |
CLAUDE.md du projet, .claude/rules/*.md, compétences du projet, hooks du projet, settings.json du projet |
<cwd>/.claude/ et chaque répertoire parent jusqu'à la racine du système de fichiers (arrêt quand un .claude/ est trouvé ou qu'il n'y a plus de parents) |
"user" |
CLAUDE.md utilisateur, ~/.claude/rules/*.md, compétences utilisateur, paramètres utilisateur |
~/.claude/ |
"local" |
CLAUDE.local.md (ignoré par git), .claude/settings.local.json |
<cwd>/ |
Omettre settingSources équivaut à ["user", "project", "local"].
L'option cwd détermine où le SDK recherche les paramètres du projet. Si ni cwd ni aucun de ses répertoires parents ne contient un dossier .claude/, les fonctionnalités au niveau du projet ne se chargeront pas.
Ce que settingSources ne contrôle pas
settingSources couvre les paramètres utilisateur, projet et locaux. Quelques entrées sont lues indépendamment de sa valeur :
| Entrée | Comportement | Pour désactiver |
|---|---|---|
| Paramètres de politique gérée | Toujours chargés quand présents sur l'hôte | Supprimez le fichier de paramètres gérés |
Configuration globale ~/.claude.json |
Toujours lue | Relocalisez avec CLAUDE_CONFIG_DIR dans env |
Mémoire automatique à ~/.claude/projects/<project>/memory/ |
Chargée par défaut dans l'invite système | Définissez autoMemoryEnabled: false dans les paramètres, ou CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dans env |
Instructions de projet (CLAUDE.md et règles)
Les fichiers CLAUDE.md et les fichiers .claude/rules/*.md donnent à votre agent un contexte persistant sur votre projet : conventions de codage, commandes de construction, décisions architecturales et instructions. Quand settingSources inclut "project" (comme dans l'exemple ci-dessus), le SDK charge ces fichiers en contexte au démarrage de la session. L'agent suit ensuite vos conventions de projet sans que vous ayez besoin de les répéter dans chaque invite.
Emplacements de chargement de CLAUDE.md
| Niveau | Emplacement | Quand chargé |
|---|---|---|
| Projet (racine) | <cwd>/CLAUDE.md ou <cwd>/.claude/CLAUDE.md |
settingSources inclut "project" |
| Règles du projet | <cwd>/.claude/rules/*.md |
settingSources inclut "project" |
| Projet (répertoires parents) | Fichiers CLAUDE.md dans les répertoires au-dessus de cwd |
settingSources inclut "project", chargés au démarrage de la session |
| Projet (répertoires enfants) | Fichiers CLAUDE.md dans les sous-répertoires de cwd |
settingSources inclut "project", chargés à la demande quand l'agent lit un fichier dans ce sous-arbre |
| Local (ignoré par git) | <cwd>/CLAUDE.local.md |
settingSources inclut "local" |
| Utilisateur | ~/.claude/CLAUDE.md |
settingSources inclut "user" |
| Règles utilisateur | ~/.claude/rules/*.md |
settingSources inclut "user" |
Tous les niveaux sont additifs : si les fichiers CLAUDE.md du projet et de l'utilisateur existent tous les deux, l'agent voit les deux. Il n'y a pas de règle de précédence stricte entre les niveaux ; si les instructions entrent en conflit, le résultat dépend de la façon dont Claude les interprète. Écrivez des règles sans conflit, ou énoncez explicitement la précédence dans le fichier plus spécifique (« Ces instructions de projet remplacent tout défaut au niveau utilisateur en conflit »).
Pour savoir comment structurer et organiser le contenu de CLAUDE.md, voir Gérer la mémoire de Claude.
Compétences
Les compétences sont des fichiers markdown qui donnent à votre agent des connaissances spécialisées et des flux de travail invocables. Contrairement à CLAUDE.md (qui se charge à chaque session), les compétences se chargent à la demande. L'agent reçoit les descriptions des compétences au démarrage et charge le contenu complet quand c'est pertinent.
Les compétences sont découvertes à partir du système de fichiers via settingSources. Quand l'option skills sur query() est omise, les compétences utilisateur et projet découvertes sont activées et l'outil Skill est disponible, ce qui correspond au comportement de la CLI. Pour contrôler quelles compétences sont activées, passez skills comme "all", une liste de noms de compétences, ou [] pour désactiver toutes les compétences. Le SDK active automatiquement l'outil Skill quand skills est défini, donc vous n'avez pas besoin de l'ajouter à allowedTools.
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);
}
}
Pour en savoir plus sur la création et l'utilisation des compétences, voir Agent Skills dans le SDK.
Hooks
Le SDK supporte deux façons de définir les hooks, et ils s'exécutent côte à côte :
- Hooks du système de fichiers : commandes shell définies dans
settings.json, chargées quandsettingSourcesinclut la source pertinente. Ce sont les mêmes hooks que vous configureriez pour les sessions Claude Code interactives. - Hooks programmatiques : fonctions de rappel passées directement à
query(). Celles-ci s'exécutent dans votre processus d'application et peuvent retourner des décisions structurées. Voir Contrôler l'exécution avec les hooks.
Les deux types s'exécutent pendant le même cycle de vie des hooks. Si vous avez déjà des hooks dans le .claude/settings.json de votre projet et que vous définissez settingSources: ["project"], ces hooks s'exécutent automatiquement dans le SDK sans configuration supplémentaire.
Les rappels de hook reçoivent l'entrée de l'outil et retournent un dictionnaire de décision. Retourner {} (un dictionnaire vide) signifie permettre à l'outil de procéder. Retourner {"decision": "block", "reason": "..."} empêche l'exécution et la raison est envoyée à Claude comme résultat de l'outil. Voir le guide des hooks pour la signature de rappel complète et les types de retour.
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);
}
}
Quand utiliser quel type de hook
| Type de hook | Meilleur pour |
|---|---|
Système de fichiers (settings.json) |
Partager les hooks entre les sessions CLI et SDK. Supporte "command" (scripts shell), "http" (POST à un point de terminaison), "mcp_tool" (appeler l'outil d'un serveur MCP connecté), "prompt" (l'LLM évalue une invite), et "agent" (génère un agent vérificateur). Ceux-ci s'exécutent dans l'agent principal et tous les sous-agents qu'il génère. |
Programmatique (rappels dans query()) |
Logique spécifique à l'application ; retour de décisions structurées ; intégration en processus. Limité à la session principale uniquement. |
Pour les détails complets sur les hooks programmatiques, voir Contrôler l'exécution avec les hooks. Pour la syntaxe des hooks du système de fichiers, voir Hooks.
Choisir la bonne fonctionnalité
Le SDK Agent vous donne accès à plusieurs façons d'étendre le comportement de votre agent. Si vous n'êtes pas sûr de celle à utiliser, ce tableau mappe les objectifs courants à la bonne approche.
| Vous voulez... | Utiliser | Surface SDK |
|---|---|---|
| Définir les conventions de projet que votre agent suit toujours | CLAUDE.md | settingSources: ["project"] le charge automatiquement |
| Donner à l'agent du matériel de référence qu'il charge quand c'est pertinent | Skills | settingSources + option skills |
| Exécuter un flux de travail réutilisable (déployer, examiner, publier) | User-invocable skills | settingSources + option skills |
| Déléguer une sous-tâche isolée à un contexte frais (recherche, examen) | Subagents | Paramètre agents + allowedTools: ["Agent"] |
| Coordonner plusieurs instances de Claude Code avec des listes de tâches partagées et la messagerie directe inter-agents | Agent teams | Non configuré directement via les options SDK. Les équipes d'agents sont une fonctionnalité CLI où une session agit comme le chef d'équipe, coordonnant le travail entre les coéquipiers indépendants |
| Exécuter une logique déterministe sur les appels d'outils (audit, blocage, transformation) | Hooks | Paramètre hooks avec rappels, ou scripts shell chargés via settingSources |
| Donner à Claude un accès structuré aux outils pour un service externe | MCP | Paramètre mcpServers |
Chaque fonctionnalité que vous activez ajoute à la fenêtre de contexte de votre agent. Pour les coûts par fonctionnalité et comment ces fonctionnalités se superposent, voir Extend Claude Code.
Ressources connexes
- Étendre Claude Code : Vue d'ensemble conceptuelle de toutes les fonctionnalités d'extension, avec tableaux de comparaison et analyse des coûts de contexte
- Compétences dans le SDK : Guide complet pour utiliser les compétences par programmation
- Sous-agents : Définir et invoquer les sous-agents pour les sous-tâches isolées
- Hooks : Intercepter et contrôler le comportement de l'agent aux points d'exécution clés
- Permissions : Contrôler l'accès aux outils avec les modes, les règles et les rappels
- Invites système : Injecter du contexte sans fichiers CLAUDE.md