Modifica dei prompt di sistema

​

Comprendere i prompt di sistema

• 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 l’ambiente

​

Metodi di modifica

​

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

​

Come funziona CLAUDE.md con l’SDK

• Livello progetto: CLAUDE.md o .claude/CLAUDE.md nella tua directory di lavoro
• Livello utente: ~/.claude/CLAUDE.md per istruzioni globali in tutti i progetti

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

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

​

Esempio CLAUDE.md

# Linee Guida del Progetto

## Stile del Codice

- Usa la modalità strict di TypeScript
- Preferisci componenti funzionali in React
- Includi sempre commenti JSDoc per le API pubbliche

## Test

- Esegui `npm test` prima di fare commit
- Mantieni >80% di copertura del codice
- Usa jest per unit test, playwright per E2E

## Comandi

- Build: `npm run build`
- Server dev: `npm run dev`
- Controllo tipi: `npm run typecheck`

​

Utilizzare CLAUDE.md con l’SDK

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

// IMPORTANTE: Devi specificare settingSources per caricare CLAUDE.md
// Il preset claude_code da solo NON carica i file CLAUDE.md
const messages = [];

for await (const message of query({
  prompt: "Aggiungi un nuovo componente React per i profili utente",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Usa il prompt di sistema di Claude Code
    },
    settingSources: ["project"], // Richiesto per caricare CLAUDE.md dal progetto
  },
})) {
  messages.push(message);
}

// Ora Claude ha accesso alle tue linee guida del progetto da CLAUDE.md

​

Quando utilizzare CLAUDE.md

• Contesto condiviso dal team - Linee guida che tutti dovrebbero seguire
• Convenzioni del 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 sotto controllo versione - Commit su git così il team rimane sincronizzato

• ✅ Persistente in tutte le sessioni di un progetto
• ✅ Condiviso con il team tramite git
• ✅ Scoperta automatica (non sono necessarie modifiche al codice)
• ⚠️ Richiede il caricamento delle impostazioni tramite settingSources

​

Metodo 2: Stili di output (configurazioni persistenti)

​

Creare 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 di revisione del codice approfondita",
  `Sei un esperto revisore di codice.

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

​

Utilizzare gli stili di output

• CLI: /output-style [nome-stile]
• Impostazioni: .claude/settings.local.json
• Crea nuovo: /output-style:new [descrizione]

​

Metodo 3: Utilizzare systemPrompt con append

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 4: Prompt di sistema personalizzati

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

const customPrompt = `Sei uno specialista di codifica 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 quattro gli approcci

​

Casi d’uso e migliori pratiche

​

Quando utilizzare CLAUDE.md

• Standard e convenzioni di codifica specifici del progetto
• Documentazione della struttura e architettura del progetto
• Elenco di comandi comuni (build, test, deploy)
• Contesto condiviso dal team che dovrebbe essere sotto controllo versione
• Istruzioni che si applicano a tutto l’uso dell’SDK in un progetto

• “Tutti gli endpoint API dovrebbero utilizzare pattern async/await”
• “Esegui npm run lint:fix prima di fare commit”
• “Le migrazioni del database sono nella directory migrations/”

​

Quando utilizzare gli stili di output

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

• Creare un assistente dedicato all’ottimizzazione SQL
• Costruire un revisore di codice focalizzato sulla sicurezza
• Sviluppare un assistente didattico con pedagogia specifica

​

Quando utilizzare systemPrompt con append

• Aggiungere standard o preferenze di codifica specifici
• Personalizzare la formattazione dell’output
• Aggiungere conoscenza specifica del dominio
• Modificare la verbosità della risposta
• Migliorare il comportamento predefinito di Claude Code senza perdere le istruzioni degli strumenti

​

Quando utilizzare systemPrompt personalizzato

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

​

Combinare gli approcci

​

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

• Stili di output - Documentazione completa degli stili di output
• Guida TypeScript SDK - Guida completa all’uso dell’SDK
• Riferimento TypeScript SDK - Documentazione completa dell’API
• Guida alla configurazione - Opzioni di configurazione generali