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.

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

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

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

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)`
);

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.

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);
  }
}

Metodo 4: System prompt personalizzati

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

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);
  }
}

Confronto di tutti e quattro gli approcci

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

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);
}

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