Modifica dei system prompt

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

Comprensione dei system prompt

Un system prompt è l'insieme iniziale di istruzioni che modella il comportamento di Claude durante una conversazione.

Comportamento predefinito: Agent SDK utilizza un system prompt minimalista per impostazione predefinita. Contiene solo istruzioni essenziali per gli strumenti ma omette le linee guida di codifica di Claude Code, lo stile di risposta e il contesto del progetto. Per includere il system prompt completo di Claude Code, specifica systemPrompt: { preset: "claude_code" } in TypeScript o system_prompt={"type": "preset", "preset": "claude_code"} in Python.

Il system prompt di Claude Code include:

Istruzioni di utilizzo degli strumenti e strumenti disponibili
Linee guida di stile e formattazione del codice
Impostazioni di tono e verbosità della risposta
Istruzioni di sicurezza e protezione
Contesto sulla directory di lavoro corrente e sull'ambiente

Metodi di modifica

Metodo 1: File CLAUDE.md (istruzioni a livello di progetto)

I file CLAUDE.md forniscono contesto e istruzioni specifiche del progetto che vengono letti automaticamente da Agent SDK quando viene eseguito in una directory. Servono come "memoria" persistente per il tuo progetto.

Come CLAUDE.md funziona con l'SDK

Posizione e scoperta:

A livello di progetto: CLAUDE.md o .claude/CLAUDE.md nella tua directory di lavoro
A livello di utente: ~/.claude/CLAUDE.md per istruzioni globali su tutti i progetti

IMPORTANTE: L'SDK legge i file CLAUDE.md solo quando configuri esplicitamente settingSources (TypeScript) o setting_sources (Python):

Includi 'project' per caricare CLAUDE.md a livello di progetto
Includi 'user' per caricare CLAUDE.md a livello di utente (~/.claude/CLAUDE.md)

Il preset di system prompt claude_code NON carica automaticamente CLAUDE.md - devi anche specificare le fonti di impostazione.

Formato del contenuto: I file CLAUDE.md utilizzano markdown semplice e possono contenere:

Linee guida e standard di codifica
Contesto specifico del progetto
Comandi o flussi di lavoro comuni
Convenzioni API
Requisiti di test

Esempio CLAUDE.md

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

Utilizzo di CLAUDE.md con l'SDK

Quando utilizzare CLAUDE.md

Ideale per:

Contesto condiviso dal team - Linee guida che tutti dovrebbero seguire
Convenzioni di progetto - Standard di codifica, struttura dei file, pattern di denominazione
Comandi comuni - Comandi di build, test, deploy specifici del tuo progetto
Memoria a lungo termine - Contesto che dovrebbe persistere in tutte le sessioni
Istruzioni controllate da versione - Commit su git in modo che il team rimanga sincronizzato

Caratteristiche principali:

✅ Persistente in tutte le sessioni di un progetto
✅ Condiviso con il team tramite git
✅ Scoperta automatica (nessuna modifica del codice necessaria)
⚠️ Richiede il caricamento delle impostazioni tramite settingSources

Metodo 2: Stili di output (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.

Creazione di uno stile di output

Utilizzo degli stili di output

Una volta creati, attiva gli stili di output tramite:

CLI: /output-style [style-name]
Impostazioni: .claude/settings.local.json
Crea nuovo: /output-style:new [description]

Nota per gli utenti dell'SDK: Gli stili di output vengono caricati quando includi settingSources: ['user'] o settingSources: ['project'] (TypeScript) / setting_sources=["user"] o setting_sources=["project"] (Python) nelle tue opzioni.

Metodo 3: Utilizzo di `systemPrompt` con append

Puoi utilizzare il preset di Claude Code con una proprietà append per aggiungere le tue istruzioni personalizzate preservando tutte le funzionalità integrate.

Metodo 4: System prompt personalizzati

Puoi fornire una stringa personalizzata come systemPrompt per sostituire completamente il valore predefinito con le tue istruzioni.

Confronto di tutti e quattro gli approcci

Funzionalità	CLAUDE.md	Stili di output	`systemPrompt` con append	`systemPrompt` personalizzato
Persistenza	File per progetto	Salvati come file	Solo sessione	Solo sessione
Riutilizzabilità	Per progetto	Tra progetti	Duplicazione del codice	Duplicazione del codice
Gestione	Nel filesystem	CLI + file	Nel codice	Nel codice
Strumenti predefiniti	Preservati	Preservati	Preservati	Persi (a meno che non inclusi)

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 best practice

Quando utilizzare CLAUDE.md

Ideale per:

Standard di codifica e convenzioni specifiche del progetto
Documentazione della struttura e dell'architettura del progetto
Elenco di comandi comuni (build, test, deploy)
Contesto condiviso dal team che dovrebbe essere controllato da versione
Istruzioni che si applicano a tutto l'utilizzo dell'SDK in un progetto

Esempi:

"Tutti gli endpoint API dovrebbero utilizzare pattern async/await"
"Esegui npm run lint:fix prima di fare commit"
"Le migrazioni del database si trovano nella directory migrations/"

Importante: Per caricare i file CLAUDE.md, devi impostare esplicitamente settingSources: ['project'] (TypeScript) o setting_sources=["project"] (Python). Il preset di system prompt claude_code NON carica automaticamente CLAUDE.md senza questa impostazione.

Quando utilizzare gli stili di output

Ideale per:

Modifiche di comportamento persistenti tra sessioni
Configurazioni condivise dal team
Assistenti specializzati (revisore di codice, data scientist, DevOps)
Modifiche di prompt complesse che necessitano di versioning

Esempi:

Creazione di un assistente dedicato per l'ottimizzazione SQL
Creazione di un revisore di codice focalizzato sulla sicurezza
Sviluppo di un assistente didattico con una pedagogia specifica

Quando utilizzare `systemPrompt` con append

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

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

Puoi combinare questi metodi per massima flessibilità:

Esempio: Stile di output con aggiunte specifiche della sessione

Vedi anche

Output styles - Documentazione completa degli stili di output
Guida TypeScript SDK - Guida completa all'utilizzo dell'SDK
Guida alla configurazione - Opzioni di configurazione generali

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

// IMPORTANT: You must specify settingSources to load CLAUDE.md
// The claude_code preset alone does NOT load CLAUDE.md files
const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Use Claude Code's system prompt
    },
    settingSources: ["project"], // Required to load CLAUDE.md from project
  },
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

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

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // User-level: ~/.claude/output-styles
  // Project-level: .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");
}

// Example: Create a code review specialist
await createOutputStyle(
  "Code Reviewer",
  "Thorough code review assistant",
  `You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)`
);

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Always include detailed docstrings and type hints in Python code.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

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

// Assuming "Code Reviewer" output style is active (via /output-style)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `,
    },
  },
})) {
  messages.push(message);
}

Comprensione dei system prompt

Metodi di modifica

Metodo 1: File CLAUDE.md (istruzioni a livello di progetto)

Come CLAUDE.md funziona con l'SDK

Esempio CLAUDE.md

Utilizzo di CLAUDE.md con l'SDK

Quando utilizzare CLAUDE.md

Metodo 2: Stili di output (configurazioni persistenti)

Creazione di uno stile di output

Utilizzo degli stili di output

Metodo 3: Utilizzo di systemPrompt con append

Metodo 4: System prompt personalizzati

Confronto di tutti e quattro gli approcci

Casi d'uso e best practice

Quando utilizzare CLAUDE.md

Quando utilizzare gli stili di output

Quando utilizzare systemPrompt con append

Quando utilizzare systemPrompt personalizzato

Combinazione di approcci

Esempio: Stile di output con aggiunte specifiche della sessione

Vedi anche

Metodo 3: Utilizzo di `systemPrompt` con append

Quando utilizzare `systemPrompt` con append

Quando utilizzare `systemPrompt` personalizzato