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

​
Comprensione dei prompt di sistema

Un prompt di sistema è l’insieme di istruzioni iniziali che modella come Claude si comporta durante una conversazione. Il prompt di sistema predefinito 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: Crea 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 appendSystemPrompt

L’opzione appendSystemPrompt aggiunge le tue istruzioni personalizzate al prompt di sistema predefinito preservando tutte le funzionalità integrate. 
import { query } from "@anthropic-ai/claude-code"

const messages = []

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

​
Metodo 3: Utilizzo di customSystemPrompt

L’opzione customSystemPrompt sostituisce l’intero prompt di sistema predefinito con le tue istruzioni personalizzate. 
import { query } from "@anthropic-ai/claude-code"

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: {
    customSystemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Confronto di tutti e tre gli approcci

CaratteristicaStili di OutputappendSystemPromptcustomSystemPrompt
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 predefinito⚠️ Solo aggiunte✅ Controllo completo
Controllo versione✅ Sì✅ Con codice✅ Con codice
Scoperta✅ /output-style❌ Non scopribile❌ Non scopribile

​
Casi d’uso e migliori pratiche

​
Quando usare gli stili di output

Migliore per:
  • Modifiche comportamentali persistenti tra sessioni
  • Configurazioni condivise dal team
  • Assistenti specializzati (revisore 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 usare appendSystemPrompt

Migliore per:
  • Aggiungere standard di codifica o preferenze specifiche
  • Personalizzare la formattazione dell’output
  • Aggiungere conoscenza specifica del dominio
  • Modificare la verbosità delle risposte

​
Quando usare customSystemPrompt

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

​
Combinazione degli approcci

Puoi combinare questi metodi per la massima flessibilità:

​
Esempio: Stile di output con aggiunte specifiche della sessione

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

// 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: {
    appendSystemPrompt: `
      Per questa revisione, dai priorità a:
      - Conformità OAuth 2.0
      - Sicurezza memorizzazione token
      - Gestione sessioni
    `
  }
})) {
  messages.push(message)
}

​
Vedi anche