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"] :
<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/ pour settings.json et hooks ; <cwd> et chaque répertoire parent pour CLAUDE.md et rules ; <cwd> et chaque répertoire parent jusqu’à la racine du dépôt pour les compétences |
"user" | CLAUDE.md utilisateur, ~/.claude/rules/*.md, compétences utilisateur, paramètres utilisateur | ~/.claude/ |
"local" | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ pour settings.local.json ; <cwd> et chaque répertoire parent pour CLAUDE.local.md |
settingSources équivaut à ["user", "project", "local"].
L’option cwd détermine où le SDK recherche les entrées au niveau du projet. CLAUDE.md et les rules se chargent à partir de <cwd> et de chaque répertoire parent. Les compétences se chargent à partir de <cwd> et de chaque répertoire parent jusqu’à la racine du dépôt. Le settings.json du projet et les hooks se chargent uniquement à partir de <cwd>/.claude/ sans secours au répertoire parent.
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 |
| Connecteurs MCP de claude.ai | Chargés quand la méthode d’authentification active est un abonnement claude.ai. Passer mcpServers: {} ne les supprime pas | Définissez strictMcpConfig: true, ou ENABLE_CLAUDEAI_MCP_SERVERS=false dans env |
Instructions de projet (CLAUDE.md et règles)
Les fichiersCLAUDE.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 et .claude/rules/*.md dans chaque répertoire parent | 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 | <cwd>/CLAUDE.local.md et CLAUDE.local.md dans chaque répertoire parent | settingSources inclut "local" |
| Utilisateur | ~/.claude/CLAUDE.md | settingSources inclut "user" |
| Règles utilisateur | ~/.claude/rules/*.md | settingSources inclut "user" |
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. Quand skills est défini, le SDK ajoute automatiquement l’outil Skill à allowedTools. Si vous passez également une liste tools explicite, incluez "Skill" dans cette liste pour que Claude puisse invoquer les compétences.
Les compétences doivent être créées en tant qu’artefacts du système de fichiers (
.claude/skills/<name>/SKILL.md). Le SDK n’a pas d’API programmatique pour enregistrer les compétences. Voir Agent Skills dans le SDK pour les détails complets.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.
.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 {} signifie permettre à l’outil de procéder. Pour bloquer l’exécution, retournez un objet hookSpecificOutput avec permissionDecision: "deny" et une permissionDecisionReason. La raison est envoyée à Claude comme résultat de l’outil. Les champs decision et reason au niveau supérieur sont dépréciés pour PreToolUse. Voir le guide des hooks pour la signature de rappel complète et les types de retour.
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, décisions structurées et intégration en processus. Ceux-ci s’exécutent également à l’intérieur des sous-agents. Le rappel reçoit agent_id et agent_type pour distinguer. |
Le SDK TypeScript supporte des événements de hook supplémentaires au-delà de Python, notamment
SessionStart, SessionEnd, TeammateIdle, et TaskCompleted. Voir le guide des hooks pour le tableau complet de compatibilité des événements.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 |
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