I prompt di sistema definiscono il comportamento, le capacità e lo stile di risposta di Claude. L’SDK Claude Agent fornisce tre modi per personalizzare i prompt di sistema: utilizzando stili di output (configurazioni persistenti basate su file), aggiungendo al prompt di Claude Code, o utilizzando un prompt completamente personalizzato.

​
Comprendere i prompt di sistema

Un prompt di sistema è il set di istruzioni iniziale che modella come Claude si comporta durante una conversazione.
Comportamento predefinito: L’SDK Agent utilizza un prompt di sistema vuoto per impostazione predefinita per la massima flessibilità. Per utilizzare il prompt di sistema di Claude Code (istruzioni degli strumenti, linee guida del codice, ecc.), specificare systemPrompt: { preset: "claude_code" } in TypeScript o system_prompt="claude_code" in Python.
Il prompt di sistema di Claude Code include:
  • Istruzioni per l’uso degli strumenti e strumenti disponibili
  • Linee guida per lo stile e la formattazione del codice
  • Impostazioni del tono di risposta e verbosità
  • Istruzioni di sicurezza e protezione
  • Contesto sulla directory di lavoro corrente e ambiente

​
Metodi di modifica

​
Metodo 1: Stili di output (configurazioni persistenti)

Gli stili di output sono configurazioni salvate che modificano il prompt di sistema di Claude. Sono memorizzati come file markdown e possono essere riutilizzati tra sessioni e progetti.

​
Creazione di uno stile di output

import { writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { homedir } from 'os'

async function createOutputStyle(name: string, description: string, prompt: string) {
  // Livello utente: ~/.claude/output-styles
  // Livello progetto: .claude/output-styles
  const outputStylesDir = join(homedir(), '.claude', 'output-styles')
  
  await mkdir(outputStylesDir, { recursive: true })
  
  const content = `---
name: ${name}
description: ${description}
---

${prompt}`
  
  const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, '-')}.md`)
  await writeFile(filePath, content, 'utf-8')
}

// Esempio: Creare uno specialista di revisione del codice
await createOutputStyle(
  'Code Reviewer',
  'Assistente completo per la revisione del codice',
  `Sei un esperto revisore di codice.

Per ogni invio di codice:
1. Controlla bug e problemi di sicurezza
2. Valuta le prestazioni
3. Suggerisci miglioramenti
4. Valuta la qualità del codice (1-10)`
)

​
Utilizzo degli stili di output

Una volta creati, attiva gli stili di output tramite:
  • CLI: /output-style [nome-stile]
  • Impostazioni: .claude/settings.local.json
  • Crea nuovo: /output-style:new [descrizione]

​
Metodo 2: Utilizzo di systemPrompt con append

Puoi utilizzare il preset Claude Code con una proprietà append per aggiungere le tue istruzioni personalizzate preservando tutte le funzionalità integrate. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const messages = []

for await (const message of query({
  prompt: "Aiutami a scrivere una funzione Python per calcolare i numeri di fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Includi sempre docstring dettagliate e type hints nel codice Python."
    }
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Metodo 3: Prompt di sistema personalizzati

Puoi fornire una stringa personalizzata come systemPrompt per sostituire completamente il default con le tue istruzioni. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const customPrompt = `Sei uno specialista di programmazione Python.
Segui queste linee guida:
- Scrivi codice pulito e ben documentato
- Usa type hints per tutte le funzioni
- Includi docstring complete
- Preferisci pattern di programmazione funzionale quando appropriato
- Spiega sempre le tue scelte di codice`

const messages = []

for await (const message of query({
  prompt: "Crea una pipeline di elaborazione dati",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Confronto di tutti e tre gli approcci

CaratteristicaStili di OutputsystemPrompt con appendsystemPrompt Personalizzato
Persistenza✅ Salvati come file❌ Solo sessione❌ Solo sessione
Riutilizzabilità✅ Tra progetti❌ Duplicazione codice❌ Duplicazione codice
Gestione✅ CLI + file⚠️ Nel codice⚠️ Nel codice
Strumenti predefiniti✅ Preservati✅ Preservati❌ Persi (a meno che inclusi)
Sicurezza integrata✅ Mantenuta✅ Mantenuta❌ Deve essere aggiunta
Contesto ambiente✅ Automatico✅ Automatico❌ Deve essere fornito
Livello personalizzazione⚠️ Sostituisce default⚠️ Solo aggiunte✅ Controllo completo
Controllo versione✅ Sì✅ Con codice✅ Con codice
Scoperta✅ /output-style❌ Non scopribile❌ Non scopribile
Nota: “Con append” significa utilizzare systemPrompt: { type: "preset", preset: "claude_code", append: "..." } in TypeScript o system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} in Python.

​
Casi d’uso e migliori pratiche

​
Quando utilizzare gli stili di output

Migliore per:
  • Cambiamenti di comportamento persistenti tra sessioni
  • Configurazioni condivise dal team
  • Assistenti specializzati (revisore di codice, data scientist, DevOps)
  • Modifiche complesse del prompt che necessitano versioning
Esempi:
  • Creare un assistente dedicato per l’ottimizzazione SQL
  • Costruire un revisore di codice focalizzato sulla sicurezza
  • Sviluppare un assistente didattico con pedagogia specifica

​
Quando utilizzare systemPrompt con append

Migliore per:
  • Aggiungere standard di codifica o preferenze specifiche
  • Personalizzare la formattazione dell’output
  • Aggiungere conoscenza specifica del dominio
  • Modificare la verbosità delle risposte
  • Migliorare il comportamento predefinito di Claude Code senza perdere le istruzioni degli strumenti

​
Quando utilizzare systemPrompt personalizzato

Migliore per:
  • Controllo completo sul comportamento di Claude
  • Compiti specializzati per singola sessione
  • Testare nuove strategie di prompt
  • Situazioni dove gli strumenti predefiniti non sono necessari
  • Costruire agenti specializzati con comportamento unico

​
Combinare gli approcci

Puoi combinare questi metodi per la massima flessibilità:

​
Esempio: Stile di output con aggiunte specifiche della sessione

import { query } from "@anthropic-ai/claude-agent-sdk"

// Assumendo che lo stile di output "Code Reviewer" sia attivo (tramite /output-style)
// Aggiungi aree di focus specifiche della sessione
const messages = []

for await (const message of query({
  prompt: "Rivedi questo modulo di autenticazione",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Per questa revisione, dai priorità a:
        - Conformità OAuth 2.0
        - Sicurezza dell'archiviazione token
        - Gestione delle sessioni
      `
    }
  }
})) {
  messages.push(message)
}

​
Vedi anche