CLAUDE.md e regole), skills, hooks e altro ancora.
Quando ometti settingSources, query() legge le stesse impostazioni del filesystem di Claude Code CLI: impostazioni utente, progetto e locali, file CLAUDE.md e skills, agenti e comandi in .claude/. Per eseguire senza questi, passa settingSources: [], che limita l’agente a ciò che configuri programmaticamente. Le impostazioni dei criteri gestiti e la configurazione globale ~/.claude.json vengono lette indipendentemente da questa opzione. Vedi Cosa settingSources non controlla.
Per una panoramica concettuale di ciò che ogni funzionalità fa e quando usarla, vedi Estendi Claude Code.
Controlla le impostazioni del filesystem con settingSources
L’opzione delle fonti di impostazione (setting_sources in Python, settingSources in TypeScript) controlla quali impostazioni basate sul filesystem carica l’SDK. Passa un elenco esplicito per acconsentire a fonti specifiche, oppure passa un array vuoto per disabilitare le impostazioni utente, progetto e locali.
Questo esempio carica sia le impostazioni a livello di utente che a livello di progetto impostando settingSources su ["user", "project"]:
<cwd> è la directory di lavoro che passi tramite l’opzione cwd, o la directory corrente del processo se non impostata. Per la definizione del tipo completo, vedi SettingSource (TypeScript) o SettingSource (Python).
Omettere
settingSources equivale a ["user", "project", "local"].
L’opzione cwd determina dove l’SDK cerca gli input a livello di progetto. CLAUDE.md e rules vengono caricati da <cwd> e da ogni directory padre. Skills vengono caricate da <cwd> e da ogni directory padre fino alla radice del repository. settings.json e hooks del progetto vengono caricati solo da <cwd>/.claude/ senza fallback di directory padre.
Cosa settingSources non controlla
settingSources copre le impostazioni utente, progetto e locali. Alcuni input vengono letti indipendentemente dal suo valore:
Istruzioni del progetto (CLAUDE.md e regole)
I fileCLAUDE.md e i file .claude/rules/*.md forniscono al tuo agente un contesto persistente sul tuo progetto: convenzioni di codifica, comandi di compilazione, decisioni architettoniche e istruzioni. Quando settingSources include "project" (come nell’esempio sopra), l’SDK carica questi file nel contesto all’inizio della sessione. L’agente quindi segue le tue convenzioni di progetto senza che tu le ripeta in ogni prompt.
Posizioni di caricamento di CLAUDE.md
Tutti i livelli sono additivi: se esistono sia file
CLAUDE.md di progetto che di utente, l’agente vede entrambi. Non esiste una regola di precedenza rigida tra i livelli; se le istruzioni entrano in conflitto, il risultato dipende da come Claude le interpreta. Scrivi regole non conflittuali, o dichiara esplicitamente la precedenza nel file più specifico (“Queste istruzioni di progetto sostituiscono qualsiasi impostazione predefinita conflittuale a livello di utente”).
Per come strutturare e organizzare il contenuto di CLAUDE.md, vedi Gestisci la memoria di Claude.
Skills
Le skills sono file markdown che danno al tuo agente conoscenze specializzate e flussi di lavoro invocabili. A differenza diCLAUDE.md (che si carica ogni sessione), le skills si caricano su richiesta. L’agente riceve le descrizioni delle skills all’avvio e carica il contenuto completo quando rilevante.
Le skills vengono scoperte dal filesystem tramite settingSources. Quando l’opzione skills su query() viene omessa, le skills di utente e progetto scoperte vengono abilitate e lo strumento Skill è disponibile, corrispondendo al comportamento della CLI. Per controllare quali skills sono abilitate, passa skills come "all", un elenco di nomi di skills, o [] per disabilitare tutte. Quando skills è impostato, l’SDK aggiunge automaticamente lo strumento Skill a allowedTools. Se passi anche un elenco esplicito di tools, includi "Skill" in quell’elenco in modo che Claude possa invocare le skills.
Le skills devono essere create come artefatti del filesystem (
.claude/skills/<name>/SKILL.md). L’SDK non ha un’API programmatica per registrare le skills. Vedi Agent Skills nell’SDK per i dettagli completi.Hooks
L’SDK supporta due modi per definire gli hooks, e vengono eseguiti fianco a fianco:- Filesystem hooks: comandi shell definiti in
settings.json, caricati quandosettingSourcesinclude la fonte rilevante. Questi sono gli stessi hooks che configureresti per sessioni interattive di Claude Code. - Programmatic hooks: funzioni di callback passate direttamente a
query(). Questi vengono eseguiti nel tuo processo di applicazione e possono restituire decisioni strutturate. Vedi Controlla l’esecuzione con gli hooks.
.claude/settings.json del tuo progetto e imposti settingSources: ["project"], quegli hooks vengono eseguiti automaticamente nell’SDK senza configurazione aggiuntiva.
I callback degli hooks ricevono l’input dello strumento e restituiscono un dict di decisione. Restituire {} significa consentire allo strumento di procedere. Per bloccare l’esecuzione, restituisci un oggetto hookSpecificOutput con permissionDecision: "deny" e un permissionDecisionReason. Il motivo viene inviato a Claude come risultato dello strumento. I campi di primo livello decision e reason sono deprecati per PreToolUse. Vedi la guida degli hooks per la firma completa del callback e i tipi di ritorno.
Quando usare quale tipo di hook
L’SDK TypeScript supporta eventi hook aggiuntivi rispetto a Python, inclusi
SessionStart, SessionEnd, TeammateIdle e TaskCompleted. Vedi la guida degli hooks per la tabella di compatibilità degli eventi completa.Scegli la funzionalità giusta
L’Agent SDK ti dà accesso a diversi modi per estendere il comportamento del tuo agente. Se non sei sicuro di quale usare, questa tabella mappa gli obiettivi comuni all’approccio giusto.
Ogni funzionalità che abiliti aggiunge alla finestra di contesto del tuo agente. Per i costi per funzionalità e come queste funzionalità si stratificano insieme, vedi Estendi Claude Code.
Risorse correlate
- Estendi Claude Code: Panoramica concettuale di tutte le funzionalità di estensione, con tabelle di confronto e analisi dei costi di contesto
- Skills nell’SDK: Guida completa all’utilizzo delle skills a livello programmatico
- Subagenti: Definisci e invoca subagenti per sottocompiti isolati
- Hooks: Intercetta e controlla il comportamento dell’agente nei punti di esecuzione chiave
- Permessi: Controlla l’accesso agli strumenti con modalità, regole e callback
- Prompt di sistema: Inietta il contesto senza file CLAUDE.md