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.
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 il resto del contenuto del presetclaude_code, incluse le istruzioni di sicurezza e protezione. Questo differisce daclaude -p, che utilizza il system prompt 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 che utilizza la CLI di Claude Code, con istruzioni di utilizzo degli strumenti e istruzioni di sicurezza e protezione. 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
append e una stringa di prompt personalizzata modificano direttamente il system prompt, e uno stile di output cambia le istruzioni che Claude Code fornisce a Claude per ogni risposta. CLAUDE.md segue un percorso diverso: l’SDK lo legge e inietta il suo contenuto nella conversazione come contesto del progetto, 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 e lascia il system prompt intatto, quindi funzionano con qualsiasi configurazione di system prompt. Per sapere cosa mettere in CLAUDE.md, dove posizionarlo e come scrivere istruzioni efficaci, vedi Quando aggiungere a CLAUDE.md e il resto di 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 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 ruolo, il tono e il formato di output 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.
Uno stile di output personalizzato esclude le istruzioni di ingegneria del software del preset claude_code e usa le tue. Per mantenerle e aggiungere le tue istruzioni sopra di esse, imposta keep-coding-instructions: true nel frontmatter. Queste istruzioni sono presenti solo nel prompt di sistema completo di Claude Code, quindi l’impostazione non ha effetto in una sessione con il prompt di sistema più breve; imposta CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT su 0 per selezionare il prompt completo su qualsiasi modello. Mantienile quando il tuo agente svolge ancora lavoro di ingegneria del software. Escludile quando sostituisci 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
/output-style <style>, ad esempio/output-style concise, oppure eseguite/confige selezionate uno. Il comando/output-stylerichiede Claude Code v2.1.269 o successivo. -
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:
outputStyle tramite l’opzione settings, che accetta una stringa JSON come '{"outputStyle": "Explanatory"}' o un percorso a un file di impostazioni che lo imposta.
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 quando le loro posizioni di memoria automatica differiscono. Il preset incorpora quella posizione nel system prompt prima del vostro testo append. La posizione predefinita è un percorso assoluto sotto ~/.claude/projects/ denominato in base al percorso del repository su disco, quindi differisce tra utenti, macchine e checkout.
Il contenuto di CLAUDE.md e i dettagli dell’ambiente come la directory di lavoro, la piattaforma, la shell e la versione del sistema operativo non influiscono sulla cache del system prompt, perché Claude Code li fornisce 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 utente 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. Impostatelo solo sulla forma dell’oggetto preset. L’SDK lo ignora quando passate un prompt personalizzato invece del preset; per mantenere le istruzioni di un prompt personalizzato memorizzate nella cache nell’SDK TypeScript, vedi Memorizzare nella cache la parte statica di un prompt personalizzato.append condiviso con excludeDynamicSections in modo che una flotta di agenti 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.
system_prompt={"type": "file", "path": "..."} invece di passarlo come stringa. L’SDK Python passa un prompt stringa come un argomento della riga di comando al subprocess CLI, quindi un prompt che supera il limite di lunghezza dell’argomento del sistema operativo fallisce al spawn del processo prima che venga inviata qualsiasi richiesta API. Su Linux l’errore è Argument list too long. Vedi SystemPromptFile per le soglie della piattaforma e il comportamento di Windows.
Memorizzare nella cache la parte statica di un prompt personalizzato
Nell’SDK TypeScript, potete passare un prompt personalizzato come un array di stringhe invece di una stringa, con il marcatoreSYSTEM_PROMPT_DYNAMIC_BOUNDARY tra la parte statica e il resto. Usate questo quando il vostro prompt combina istruzioni che sono uguali su ogni richiesta con contesto che cambia per richiesta, come il cliente o il ticket che l’agente sta gestendo. Quando passate entrambe le parti come una stringa, un cambiamento alla parte per richiesta cambia l’intero system prompt, quindi le istruzioni statiche perdono la cache anche. La forma array non è disponibile nell’SDK Python; ClaudeAgentOptions elenca le forme che system_prompt accetta.
L’SDK divide il prompt solo quando chiama direttamente l’API Claude o viene eseguito su Claude Platform on AWS. In ogni altra configurazione, come Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, o un LLM gateway, e ogni volta che impostate
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, l’SDK invia l’intero prompt come un blocco, lo stesso che passare una stringa.SYSTEM_PROMPT_DYNAMIC_BOUNDARY da @anthropic-ai/claude-agent-sdk e passatelo come elemento array proprio tra le due parti. L’SDK invia le stringhe prima del marcatore come un blocco di testo e le stringhe dopo come un secondo blocco, ognuno con il suo punto di interruzione della cache. Nell’esempio seguente, un agente di supporto carica le sue istruzioni di triage da un file e riceve dettagli su un ticket su ogni richiesta, quindi le istruzioni rimangono memorizzate nella cache mentre i dettagli del ticket cambiano:
TypeScript
cache_creation_input_tokens e cache_read_input_tokens su ogni messaggio di risultato.
L’SDK assembla i blocchi dall’array come segue:
- L’SDK unisce le stringhe su ogni lato del marcatore con una riga vuota tra di loro e rimuove il marcatore stesso, quindi il testo del marcatore non raggiunge Claude.
- Se includete il marcatore più di una volta, il primo è la divisione e l’SDK rimuove gli altri.
- Se lasciate fuori il marcatore, l’SDK unisce tutte le stringhe in un blocco, lo stesso che passare una stringa.
--system-prompt o --system-prompt-file della CLI, il prompt è una stringa, quindi non c’è un array per portare il marcatore. Includete una riga contenente solo __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ tra le parti statiche e per richiesta. Claude Code divide il prompt alla prima riga di questo tipo nei due blocchi e rimuove quella riga. Richiede Claude Code v2.1.275 o successivo.
Nell’SDK, preferite la forma array, che porta il confine senza una riga marcatore.
Cambiare il prompt di una sessione esistente
Per impostazione predefinita, se passate unappend o prompt personalizzato diverso quando tornate a una sessione con resume o continue, Claude non lo vede al turno successivo. Claude Code registra il system prompt alla prima richiesta di una sessione e riutilizza quel record fino a quando la sessione non viene compattata. Il nuovo testo ha effetto dopo quella compattazione, o in una nuova sessione.
Aggiornare le istruzioni di Claude a metà sessione
Se le istruzioni che mettete nel system prompt devono cambiare mentre una sessione è in esecuzione, ad esempio perché il vostro utente ha cambiato l’agente in una modalità di sola lettura o ha modificato la sua configurazione nella vostra app, inviate le nuove istruzioni nella conversazione invece di cambiaresystemPrompt:
- Nel vostro prossimo messaggio: includete le nuove istruzioni nel prossimo messaggio dell’utente che inviate.
- Da un hook: restituite
additionalContextda un callback di hookUserPromptSubmitoPostToolUsehook callback, scritto come un’affermazione fattuale come “L’area di lavoro è ora di sola lettura”. L’SDK inserisce il testo nella conversazione nel punto in cui l’hook si è attivato, quindi il prompt registrato rimane invariato.
Disattivare la registrazione mentre iterate sulla formulazione
Mentre iterate sulla formulazione del prompt e volete che ogni modifica raggiunga una sessione che riprendete, impostatesnapshot a false sulla forma dell’oggetto del system prompt. Claude Code quindi ricostruisce il prompt su ogni richiesta. Il campo è disponibile sulla forma preset e personalizzata di systemPrompt in TypeScript e di system_prompt in Python, e richiede @anthropic-ai/claude-agent-sdk v0.3.257 o successivo, o claude-agent-sdk v0.2.153 o successivo.
Mantenete la registrazione attiva in produzione. Con la registrazione disattivata, un append o prompt personalizzato diverso su una sessione ripresa raggiunge Claude al turno successivo, e quella richiesta non può riutilizzare la prompt cache della sessione. Dove l’API applica il preserved thinking, Claude perde anche il suo thinking dai turni precedenti.
Al di fuori delle cloud sessions, se avviate Claude Code in bare mode passando --bare tramite extraArgs o impostando CLAUDE_CODE_SIMPLE=1, la registrazione rimane disattivata a meno che non impostiate snapshot: true.
La registrazione di un append o prompt personalizzato per impostazione predefinita richiede Claude Code v2.1.265 o successivo, che l’Agent SDK TypeScript raggruppa dalla v0.3.265 e l’Agent SDK Python dalla v0.2.153. Prima di Claude Code v2.1.268, le sessioni che non recuperano i flag delle funzionalità, incluse le sessioni su Amazon Bedrock, Google Cloud’s Agent Platform, e Microsoft Foundry, ricostruivano il prompt su ogni richiesta e snapshot non aveva effetto.
Contesto che Claude Code aggiunge al di fuori del prompt di sistema
I promemoria di sistema sono messaggi che Claude Code aggiunge alla conversazione durante una sessione per fornire a Claude il contesto, come il contenuto dei tuoi file CLAUDE.md o una nota che un file è cambiato su disco. Claude Code li invia nella conversazione, non nel prompt di sistema, quindi la maggior parte raggiunge Claude indipendentemente dal fatto che tu utilizzi il presetclaude_code o passi una tua stringa come systemPrompt.
Questa sezione copre i promemoria più probabili a cambiare il comportamento del vostro agente, come disattivare quelli che il vostro agente sostituisce, e come vedere cosa Claude ha ricevuto in una richiesta specifica.
Promemoria che Claude Code aggiunge alla conversazione
I promemoria di sistema sono testi che Claude Code aggiunge alla conversazione insieme ai prompt che il vostro codice invia. I seguenti promemoria sono quelli più probabili a cambiare il comportamento del vostro agente:- Istruzioni del progetto: i file CLAUDE.md che la vostra opzione
settingSourcescarica - Istruzioni di stile di output: le istruzioni dello stile di output attivo, nella conversazione principale
- Attribuzione di commit e pull request: il trailer
Co-Authored-Bye il footer della pull request dall’impostazioneattribution - Output di hook: testo che i vostri hooks restituiscono come
additionalContext - Skill disponibili: i nomi e le descrizioni delle skill che Claude può chiamare
- Subagenti disponibili: i nomi e le descrizioni dei subagenti che Claude può avviare
- Spinte dell’elenco attività: in una sessione che ha gli strumenti di tracciamento delle attività, un prompt per aggiornare l’elenco attività quando Claude non lo ha toccato per diversi turni
- Note di file modificati: una nota che un file che Claude ha letto in precedenza è cambiato su disco
systemPrompt, aggiungete una frase che dica cos’è un promemoria di sistema. Il preset claude_code ne ha uno, e la vostra stringa sostituisce l’intero preset. Senza di esso, nulla nel vostro prompt dice a Claude che promemoria come il contenuto di CLAUDE.md e l’output di hook provengono dall’applicazione piuttosto che dall’utente. Ad esempio:
Disattivare il contesto che il vostro agente sostituisce
Disattivate un pezzo di contesto integrato quando il vostro agente fornisce la sua versione della stessa guida. Ad esempio, se il vostro prompt dice a Claude di scrivere messaggi di commit comePROJ-142: fix login redirect senza trailer, Claude Code comunque dice a Claude di terminare ogni messaggio di commit con un trailer Co-Authored-By, quindi Claude riceve due istruzioni conflittuali per lo stesso commit.
Passate le chiavi delle impostazioni attraverso l’opzione settings in TypeScript o settings in Python, e le variabili di ambiente attraverso l’opzione env. In TypeScript, env sostituisce l’ambiente ereditato, quindi diffondete process.env in esso.
Imposta
includeGitInstructions a false per escludere le istruzioni integrate di commit e pull request, che fanno parte della descrizione dello strumento Bash e raggiungono Claude anche con un systemPrompt personalizzato. Con il valore predefinito minimo, un systemPrompt personalizzato o un agente personalizzato del thread principale che ha un proprio prompt, tuttavia, la sessione si avvia senza lo snapshot dello stato git.
Se imposti CLAUDE_CODE_DISABLE_ATTACHMENTS, Claude Code invia anche le menzioni di file @ come testo semplice invece di espanderle nel contenuto del file. L’elenco dei subagent disponibili e le notifiche delle attività in background arrivano comunque. Per impedire solo l’espansione delle menzioni di file @, imposta invece CLAUDE_CODE_DISABLE_FILE_MENTIONS=1, su Claude Code v2.1.299 o versioni successive. Claude riceve quindi i percorsi menzionati insieme a una nota per leggerli con i suoi strumenti per i file.
L’esempio seguente è per un agente che porta le sue regole di commit in append. Imposta entrambe le chiavi attribution a stringhe vuote per rimuovere il trailer e il footer, e disattiva includeGitInstructions in modo che le istruzioni del flusso di lavoro di commit di Claude Code non competano con le vostre:
git log -1. Il messaggio termina senza un trailer Co-Authored-By.
Vedere cosa Claude ha ricevuto
Il flusso di messaggi SDK non include promemoria di sistema, quindi leggere i messaggi che il vostro codice riceve non vi mostrerà cosa Claude ha visto. Per vederli, registrate le richieste che Claude Code invia:- Registrazione delle richieste raw: impostate
OTEL_LOG_RAW_API_BODIESafile:<dir>. Claude Code scrive ogni corpo della richiesta in quella directory. - Un gateway che controllate: puntate
ANTHROPIC_BASE_URLa un proxy che registra i corpi delle richieste.
messages. Un promemoria appare all’interno di un messaggio utente avvolto in tag <system-reminder> o, su alcuni modelli, come un messaggio separato con il ruolo system.
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.
Combinare gli approcci
Gli approcci si compongono. 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 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