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).
| Fonte | Cosa carica | Posizione |
|---|---|---|
"project" | CLAUDE.md del progetto, .claude/rules/*.md, skills del progetto, hooks del progetto, settings.json del progetto | <cwd>/.claude/ per settings.json e hooks; <cwd> e ogni directory padre per CLAUDE.md e rules; <cwd> e ogni directory padre fino alla radice del repository per skills |
"user" | CLAUDE.md dell’utente, ~/.claude/rules/*.md, skills dell’utente, impostazioni dell’utente | ~/.claude/ |
"local" | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ per settings.local.json; <cwd> e ogni directory padre per CLAUDE.local.md |
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:
| Input | Comportamento | Per disabilitare |
|---|---|---|
| Impostazioni dei criteri gestiti | Sempre caricate quando presenti sull’host | Rimuovi il file delle impostazioni gestite |
Configurazione globale ~/.claude.json | Sempre letta | Riposiziona con CLAUDE_CONFIG_DIR in env |
Memoria automatica in ~/.claude/projects/<project>/memory/ | Caricata per impostazione predefinita nel prompt di sistema | Imposta autoMemoryEnabled: false nelle impostazioni, o CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env |
| Connettori MCP da claude.ai | Caricati quando il metodo di autenticazione attivo è un abbonamento a claude.ai. Passare mcpServers: {} non li sopprime | Imposta strictMcpConfig: true, o ENABLE_CLAUDEAI_MCP_SERVERS=false in env |
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
| Livello | Posizione | Quando caricato |
|---|---|---|
| Progetto (root) | <cwd>/CLAUDE.md o <cwd>/.claude/CLAUDE.md | settingSources include "project" |
| Regole del progetto | <cwd>/.claude/rules/*.md e .claude/rules/*.md in ogni directory padre | settingSources include "project" |
| Progetto (directory padre) | File CLAUDE.md nelle directory sopra cwd | settingSources include "project", caricato all’inizio della sessione |
| Progetto (directory figlie) | File CLAUDE.md nelle sottodirectory di cwd | settingSources include "project", caricato su richiesta quando l’agente legge un file in quel sottoalbero |
| Locale | <cwd>/CLAUDE.local.md e CLAUDE.local.md in ogni directory padre | settingSources include "local" |
| Utente | ~/.claude/CLAUDE.md | settingSources include "user" |
| Regole dell’utente | ~/.claude/rules/*.md | settingSources include "user" |
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
| Tipo di hook | Migliore per |
|---|---|
Filesystem (settings.json) | Condividere gli hooks tra le sessioni CLI e SDK. Supporta "command" (script shell), "http" (POST a un endpoint), "mcp_tool" (chiama lo strumento di un server MCP connesso), "prompt" (LLM valuta un prompt), e "agent" (genera un agente verificatore). Questi si attivano nell’agente principale e in qualsiasi subagente che genera. |
Programmatic (callback in query()) | Logica specifica dell’applicazione, decisioni strutturate e integrazione in-process. Questi si attivano anche all’interno dei subagenti. Il callback riceve agent_id e agent_type per distinguere. |
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.| Vuoi… | Usa | Superficie SDK |
|---|---|---|
| Impostare le convenzioni del progetto che il tuo agente segue sempre | CLAUDE.md | settingSources: ["project"] lo carica automaticamente |
| Dare all’agente materiale di riferimento che carica quando rilevante | Skills | opzione settingSources + skills |
| Eseguire un flusso di lavoro riutilizzabile (deploy, review, release) | Skills invocabili dall’utente | opzione settingSources + skills |
| Delegare un sottocompito isolato a un contesto fresco (ricerca, review) | Subagenti | parametro agents + allowedTools: ["Agent"] |
| Coordinare più istanze di Claude Code con elenchi di attività condivisi e messaggistica diretta tra agenti | Team di agenti | Non configurato direttamente tramite le opzioni SDK. I team di agenti sono una funzionalità CLI in cui una sessione agisce come il capo del team, coordinando il lavoro tra i compagni di squadra indipendenti |
| Eseguire logica deterministica sulle chiamate di strumenti (audit, block, transform) | Hooks | parametro hooks con callback, o script shell caricati tramite settingSources |
| Dare a Claude accesso strutturato agli strumenti di un servizio esterno | MCP | parametro mcpServers |
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