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).
Omettre
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 :
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
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. 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
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.
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