claude_code per strumenti di codifica simili a CLI o IDE dove un utente osserva e guida il lavoro. Scrivi il tuo prompt per agenti con una superficie, identità o modello di autorizzazione diverso.
Questa pagina copre:
- Come funzionano i system prompt, con una tabella decisionale per scegliere tra il preset, il preset con
append, e un prompt personalizzato - Personalizza il comportamento dell’agente con file CLAUDE.md, stili di output,
append, o una stringa personalizzata - Confronta i quattro approcci per persistenza, ambito, e cosa preservano
- Combina gli approcci per stratificare i metodi di personalizzazione insieme
Come funzionano i system prompt
Un system prompt è l’insieme iniziale di istruzioni che modella il comportamento di Claude durante una conversazione. Agent SDK ha tre punti di partenza per esso:- Default minimalista: quando non impostate
systemPromptin TypeScript osystem_promptin Python, l’SDK utilizza un prompt minimalista che copre la chiamata degli strumenti ma omette le linee guida di codifica di Claude Code, lo stile di risposta e il contesto del progetto. Questo differisce daclaude -p, che utilizza il prompt completo di Claude Code per impostazione predefinita. Se state migrando dalla CLI e desiderate un comportamento corrispondente, impostate il presetclaude_code. - Preset
claude_code: il system prompt completo che utilizza la CLI di Claude Code, con istruzioni di utilizzo degli strumenti, linee guida di stile e formattazione del codice, regole di tono e verbosità della risposta, istruzioni di sicurezza e protezione, e contesto sulla directory di lavoro e sull’ambiente. ImpostatesystemPrompt: { type: "preset", preset: "claude_code" }in TypeScript osystem_prompt={"type": "preset", "preset": "claude_code"}in Python, facoltativamente conappendper aggiungere le vostre istruzioni alla fine. - Stringa personalizzata: un prompt che scrivete voi stessi. L’SDK invia solo ciò che fornite.
Decidere un punto di partenza
Il fattore decisivo è quanto strettamente il vostro agente assomiglia a Claude Code: un agente di codifica che opera in un repository, con un umano che osserva l’output in streaming e guida il lavoro. Più il vostro prodotto si allontana da questo, più vorrete scrivere il vostro prompt.
“Diverso da Claude Code” di solito significa uno dei seguenti:
- Superficie diversa: l’output non viene letto in un terminale dalla persona che lo ha attivato. Le interfacce chat, i consumatori di output strutturato e l’automazione non di codifica hanno ciascuno bisogno di un prompt che corrisponda a come il loro output viene renderizzato e revisionato. L’automazione di codifica incustodita, come un lavoro CI che corregge gli errori di lint o esamina i diff, si adatta comunque al preset perché il lavoro stesso è quello per cui il preset è scritto.
- Identità diversa: l’agente non dovrebbe presentarsi come Claude Code. Un bot di supporto, un assistente di analisi dei dati, o qualsiasi agente specifico del dominio ha bisogno del suo proprio nome, ambito e persona.
- Modello di permessi diverso: l’agente viene eseguito autonomamente senza che un umano approvi ogni passaggio, o opera su un insieme ristretto di risorse. Il prompt di Claude Code presuppone che un umano sia nel ciclo con accesso a un set di strumenti completo.
- Attività non di codifica: la maggior parte del prompt di Claude Code è guida di codifica. Per agenti di ricerca, contenuto o operazioni, quella guida compete con le istruzioni di cui avete effettivamente bisogno.
Personalizzare il comportamento dell’agente
Gli stili di output,append, e una stringa di prompt personalizzata modificano direttamente il system prompt. CLAUDE.md segue un percorso diverso: l’SDK lo legge e inietta il suo contenuto nella conversazione come contesto del progetto, non nel system prompt, quindi modella il comportamento insieme a qualsiasi system prompt Lei scelga. Skills, hooks, e permissions modellano anche il comportamento al di fuori del system prompt e sono trattati in pagine separate.
File CLAUDE.md per istruzioni a livello di progetto
I file CLAUDE.md forniscono a Claude contesto e istruzioni persistenti a livello di progetto. L’SDK inietta il loro contenuto nella conversazione, non nel system prompt, quindi funzionano con qualsiasi configurazione di system prompt. Per sapere cosa mettere in CLAUDE.md, dove posizionarlo e come scrivere istruzioni efficaci, vedi Come Claude ricorda il tuo progetto. Questa sezione copre ciò che è specifico dell’SDK: come CLAUDE.md si carica. L’SDK legge CLAUDE.md quando la corrispondente fonte di impostazione è abilitata:'project' carica CLAUDE.md o .claude/CLAUDE.md dalla directory di lavoro, e 'user' carica ~/.claude/CLAUDE.md. Le opzioni predefinite di query() abilitano entrambe le fonti, quindi CLAUDE.md si carica automaticamente. Se impostate settingSources in TypeScript o setting_sources in Python esplicitamente, includete le fonti di cui avete bisogno. Il caricamento di CLAUDE.md è controllato dalle fonti di impostazione, non dal preset claude_code.
Caricare CLAUDE.md con l’SDK
Per caricare CLAUDE.md, impostatesettingSources per includere il livello in cui vive il vostro CLAUDE.md. L’esempio seguente carica un CLAUDE.md a livello di progetto insieme al preset claude_code, quindi Claude ha sia il prompt completo dell’agente di codifica che le convenzioni del vostro progetto:
settingSources vuoto.
Stili di output per configurazioni persistenti
Gli stili di output sono configurazioni salvate che modificano il system prompt di Claude. Vengono archiviati come file markdown e possono essere riutilizzati in sessioni e progetti diversi.Creare uno stile di output
Uno stile di output è un file markdown con frontmatter per i metadati, seguito dal contenuto del prompt. Salvatelo in~/.claude/output-styles/ per uno stile a livello di utente disponibile in ogni progetto, o .claude/output-styles/ nel vostro repository per uno stile a livello di progetto che potete committare e condividere con il vostro team.
Per impostazione predefinita, uno stile di output personalizzato sostituisce le istruzioni di ingegneria del software del preset claude_code con le vostre. Per mantenerle e stratificare le vostre istruzioni sopra, impostate keep-coding-instructions: true nel frontmatter. Mantenetele quando il vostro agente sta ancora facendo lavoro di ingegneria del software. Omettete quando state sostituendo completamente il ruolo.
L’esempio seguente definisce una persona di revisione del codice che mantiene le istruzioni di codifica, poiché la revisione del codice beneficia ancora della guida sulla sicurezza e la qualità del codice di Claude Code. Salvatelo come ~/.claude/output-styles/code-reviewer.md per renderlo disponibile in tutti i progetti:
~/.claude/output-styles/code-reviewer.md
Attivare uno stile di output
Una volta creato, attivate gli stili di output tramite:-
CLI: eseguite
/confige selezionate uno stile di output -
Impostazioni: impostate
outputStylein.claude/settings.local.json -
TypeScript SDK: impostate
outputStyleall’interno dell’oggettosettingsinline passato aquery(), oppure puntatesettingsa un file di impostazioni che lo imposta.outputStylenon è un campoOptionsdi livello superiore:
.claude/settings.local.json, usate append o una stringa di prompt personalizzata invece.
Nota per gli utenti dell’SDK: Gli stili di output vengono caricati quando includete settingSources: ['user'] o settingSources: ['project'] (TypeScript) / setting_sources=["user"] o setting_sources=["project"] (Python) nelle vostre opzioni.
Aggiungere al preset claude_code
Potete usare il preset Claude Code con una proprietà append per aggiungere le vostre istruzioni personalizzate preservando tutte le funzionalità integrate.
Migliorare il prompt caching tra utenti e macchine
Per impostazione predefinita, due sessioni che utilizzano lo stesso presetclaude_code e lo stesso testo append non possono comunque condividere una voce della cache del prompt se vengono eseguite da directory di lavoro diverse. Questo perché il preset incorpora il contesto per sessione nel system prompt prima del vostro testo append: la directory di lavoro, se è un repository git, la piattaforma, la shell attiva, la versione del sistema operativo, e i percorsi della memoria automatica. Qualsiasi differenza in quel contesto produce un system prompt diverso e un cache miss. Il contenuto di CLAUDE.md non influisce sulla cache del system prompt perché l’SDK lo inietta nella conversazione, non nel system prompt.
Per rendere il system prompt identico tra le sessioni, impostate excludeDynamicSections: true in TypeScript o "exclude_dynamic_sections": True in Python. Il contesto per sessione si sposta nel primo messaggio dell’utente, lasciando solo il preset statico e il vostro testo append nel system prompt in modo che le configurazioni identiche condividano una voce della cache tra utenti e macchine.
excludeDynamicSections richiede @anthropic-ai/claude-agent-sdk v0.2.98 o successivo, o claude-agent-sdk v0.1.58 o successivo per Python. Si applica solo alla forma dell’oggetto preset e non ha effetto quando systemPrompt è una stringa.append condiviso con excludeDynamicSections in modo che una flotta di agenti in esecuzione da directory diverse possa riutilizzare lo stesso system prompt memorizzato nella cache:
--exclude-dynamic-system-prompt-sections.
System prompt personalizzati
Potete fornire una stringa personalizzata comesystemPrompt per sostituire completamente il valore predefinito con le vostre istruzioni.
Confronto dei quattro approcci
I quattro metodi di personalizzazione differiscono per dove risiedono, come vengono condivisi e cosa preservano dal presetclaude_code.
“Con append” significa utilizzare
systemPrompt: { type: "preset", preset: "claude_code", append: "..." } in TypeScript o system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} in Python. CLAUDE.md non modifica il prompt di sistema stesso: l’SDK ne inietta il contenuto nella conversazione come contesto del progetto.
Casi d’uso e best practice
Quando utilizzare CLAUDE.md
Utilizzare CLAUDE.md per le istruzioni che dovrebbero applicarsi a ogni sessione in un progetto, indipendentemente dal prompt di sistema utilizzato dalla sessione: standard di codifica, comandi comuni, contesto dell’architettura e convenzioni del team. CLAUDE.md è sottoposto a commit nel vostro repository, quindi rimane sincronizzato con il codice che descrive. Consultare When to add to CLAUDE.md per una guida completa. I file CLAUDE.md vengono caricati quando la fonte di impostazioneproject è abilitata, il che avviene per le opzioni predefinite di query(). Se impostate esplicitamente settingSources in TypeScript o setting_sources in Python, includete 'project' per continuare a caricare CLAUDE.md a livello di progetto.
Quando utilizzare gli stili di output
Gli stili di output sono per le persone che desiderate riutilizzare tra la CLI e l’SDK senza modificare il codice dell’applicazione. Poiché risiedono come file in.claude/output-styles, la stessa persona è disponibile da /config nella CLI e da qualsiasi sessione SDK che carica la fonte di impostazione corrispondente.
Ideale per:
- Modifiche di comportamento persistenti tra sessioni
- Configurazioni condivise dal team
- Assistenti specializzati come un revisore del codice, un data scientist o un assistente DevOps
- Modifiche di prompt complesse che necessitano di versionamento
- Creazione di un assistente dedicato per l’ottimizzazione SQL
- Creazione di un revisore del codice incentrato sulla sicurezza
- Sviluppo di un assistente didattico con una pedagogia specifica
Quando utilizzare systemPrompt con append
Utilizzare append quando il preset claude_code si adatta già al vostro prodotto e avete solo bisogno di aggiungere istruzioni extra. Mantenete la guida degli strumenti del preset, le regole di sicurezza e le convenzioni di codifica senza reimplementarle.
Ideale per:
- Aggiunta di standard di codifica o preferenze specifiche
- Personalizzazione della formattazione dell’output
- Aggiunta di conoscenze specifiche del dominio
- Modifica della verbosità della risposta
- Miglioramento del comportamento predefinito di Claude Code senza perdere le istruzioni degli strumenti
Quando utilizzare systemPrompt personalizzato
Utilizzare un prompt personalizzato quando la superficie, l’identità o il modello di autorizzazione dell’agente differisce da quello di Claude Code, come descritto in Decide on a starting point. Definite l’intero set di istruzioni, inclusa qualsiasi guida degli strumenti e regole di sicurezza di cui l’agente ha bisogno.
Ideale per:
- Controllo completo sul comportamento di Claude
- Attività specializzate a sessione singola
- Test di nuove strategie di prompt
- Situazioni in cui gli strumenti predefiniti non sono necessari
- Creazione di agenti specializzati con comportamento unico
Combinazione di approcci
Questi metodi si compongono insieme. Uno stile di output persistente o CLAUDE.md imposta il comportamento a lungo termine, eappend sovrappone le istruzioni specifiche della sessione senza toccare la configurazione salvata.
Combinare uno stile di output con aggiunte specifiche della sessione
L’esempio seguente presuppone che uno stile di output Code Reviewer sia già attivo. Il bloccoappend sovrappone le aree di focus specifiche della sessione sulla persona, in modo che una singola sessione di revisione possa dare priorità a OAuth e all’archiviazione dei token senza modificare lo stile di output salvato:
Vedi anche
- Stili di output: crea, gestisci e condividi stili di output per la CLI, inclusi il formato del file e i percorsi di archiviazione
- Come Claude ricorda il tuo progetto: cosa inserire in CLAUDE.md, dove posizionarlo e come scrivere istruzioni di progetto efficaci
- Riferimento TypeScript SDK: il tipo
Optionscompleto, inclusisystemPrompt,settingSourcesesettings - Riferimento Python SDK: il tipo
ClaudeAgentOptionscompleto, inclusisystem_promptesetting_sources - Impostazioni: il riferimento
settings.json, incluso dove sono archiviati gli stili di output e altre configurazioni