Output styles di Claude Code: cambiare il system prompt senza perdere il coding agent

🎨 Cos'è un output style e cosa non è

Un output style è un file markdown le cui istruzioni vengono aggiunte in coda al system prompt di Claude Code. Non è un messaggio utente, non è un file di contesto, non è un allegato: è la parte più alta della gerarchia, quella che definisce chi è l'assistente e come deve rispondere prima ancora che io scriva qualcosa.

La conseguenza pratica è che uno stile vale a ogni singolo turno, senza che io lo richiami. È lo strumento giusto quando la ripetizione riguarda la forma — «rispondi sempre con un diagramma», «tieniti sotto le cinque righe», «comportati da analista dati e non da sviluppatore» — e quello sbagliato quando riguarda i fatti del progetto, dove serve invece un CLAUDE.md.

Un limite che vale la pena sapere subito: lo stile si applica alla conversazione principale. Un subagent gira con un proprio system prompt e non lo eredita; fa eccezione il fork della conversazione corrente, che porta con sé l'intero system prompt del genitore.

🧭 I quattro stili integrati

Lo stile Default è il system prompt normale di Claude Code: conciso, tarato sul portare a casa un task di software engineering. Gli altri tre cambiano registro in modo netto.

Proactive spinge sull'autonomia: Claude esegue subito, fa assunzioni ragionevoli invece di fermarsi sulle decisioni di routine, preferisce agire al pianificare. Vale la pena notare che è una spinta più forte di quella della auto mode, ma non tocca i permessi: le richieste di conferma prima di eseguire uno strumento continuano ad arrivare.

Explanatory intercala blocchi «Insight» mentre lavora, spiegando le scelte implementative e i pattern del codebase. Learning va oltre e diventa collaborativo: oltre agli insight lascia dei marcatori TODO(human) nel codice, cioè pezzi piccoli e strategici che tocca a me implementare. È il più vicino a una sessione di pair programming vera, ed è quello che consiglio a chi teme di spegnere il cervello accettando patch a scatola chiusa.

⚙️ Come si cambia stile oggi: /config, non /output-style

Qui sta il primo scoglio, e non è un dettaglio da niente: quasi tutte le guide in circolazione dicono di lanciare /output-style nome-stile oppure /output-style:new. Quel comando è stato deprecato nella v2.1.73 e rimosso nella v2.1.91: se lo digito oggi non trovo nulla, e la conclusione sbagliata è che la funzionalità non esista più.

Il modo corretto è /config, voce Output style, che apre un menu con gli stili disponibili. La scelta finisce in .claude/settings.local.json, cioè a livello di progetto locale. In alternativa scrivo il campo outputStyle a mano nel file di impostazioni che preferisco, seguendo la normale precedenza delle settings.

La seconda cosa da ricordare è che lo stile fa parte del system prompt, che Claude Code legge una volta sola all'avvio della sessione. Un cambio non ha effetto sul turno corrente: serve un /clear o una sessione nuova. È il motivo numero uno per cui uno stile appena scritto «non funziona».

// .claude/settings.local.json
{
  "outputStyle": "Explanatory"
}

✍️ Scrivere uno stile su misura

Uno stile custom è un file markdown: frontmatter con i metadati, poi il testo che finisce nel system prompt. Il nome del file diventa il nome dello stile, a meno che non lo sovrascriva col campo name. I livelli sono tre: utente in ~/.claude/output-styles, progetto in .claude/output-styles e policy gestita nella directory delle managed settings.

I campi del frontmatter sono quattro: name e description (quest'ultima è ciò che leggo nel picker di /config), keep-coding-instructions di cui parlo tra poco, e force-for-plugin, riservato agli stili distribuiti dentro un plugin — quando è attivo lo stile si applica da solo appena il plugin è abilitato, scavalcando la scelta dell'utente.

Un dettaglio utile nei monorepo: gli stili di progetto si caricano da ogni cartella .claude/output-styles/ tra la directory di lavoro e la radice del repository, e a parità di nome vince quella più vicina alla directory in cui sto lavorando.

---
name: Diagrammi prima
description: Apre ogni spiegazione con un diagramma
keep-coding-instructions: true
---

Quando spieghi codice, architettura o flussi di dati, parti da un
diagramma Mermaid che mostra la struttura, poi spiega in prosa.

## Convenzioni sui diagrammi

Usa `flowchart TD` per il flusso di controllo e `sequenceDiagram`
per i percorsi di richiesta. Tieni i diagrammi sotto i 15 nodi.

⚠️ Il trabocchetto: keep-coding-instructions

Questo è l'errore che vedo fare più spesso, e nasce da un default poco intuitivo. Uno stile custom, per impostazione predefinita, lascia fuori le istruzioni di software engineering integrate di Claude Code: come circoscrivere una modifica, come scrivere i commenti, come verificare il lavoro. Non le affianca: le sostituisce con il mio testo.

Il risultato è un assistente che magicamente «si è dimenticato come si programma», e che regredisce su cose che prima faceva da solo. La causa è quasi sempre un campo mancante: keep-coding-instructions: true. Lo metto ogni volta che sto cambiando solo il modo di comunicare ma il lavoro resta scrivere codice.

Lo lascio fuori, invece, quando l'assistente non sta facendo software engineering per niente: uno stile da assistente alla scrittura, da analista dati, da revisore di documentazione. Lì le istruzioni di coding sono solo peso morto nel system prompt, e toglierle è esattamente il punto.

🧩 Quando uso uno stile e quando qualcos'altro

Claude Code ha quattro modi diversi di farsi personalizzare, e sceglierne uno per il lavoro dell'altro è la fonte principale di frustrazione. Li tengo separati così:

• Output style quando voglio un ruolo, un tono o un formato di risposta diverso a ogni turno: è l'unico che modifica il system prompt.
• CLAUDE.md quando Claude deve sapere le convenzioni e il contesto del mio progetto: arriva come messaggio dopo il system prompt, non lo riscrive.
• --append-system-prompt quando mi serve un'aggiunta una tantum per una singola invocazione, senza togliere niente a quello che c'è già.
• Skill quando ho un flusso di lavoro riutilizzabile, che si carica solo quando lo invoco o quando Claude lo ritiene rilevante — non a ogni messaggio.
• Subagent quando voglio un aiutante con system prompt, modello e strumenti suoi per un compito circoscritto.

✅ La checklist che seguo

Riassunto operativo, nell'ordine in cui mi salva tempo:

• Provo prima gli integrati: Explanatory e Learning coprono già gran parte dei casi «voglio capire cosa stai facendo».
• Scrivo lo stile custom in .claude/output-styles/ se serve al team, in ~/.claude/output-styles/ se è una preferenza mia.
• Metto keep-coding-instructions: true a meno che l'assistente non debba proprio smettere di fare lo sviluppatore.
• Attivo da /config, mai da /output-style: quel comando non esiste più dalla v2.1.91.
• Faccio /clear dopo ogni modifica allo stile, altrimenti sto guardando ancora il system prompt della sessione precedente.
• Tengo d'occhio i token: uno stile allunga il system prompt, e Explanatory e Learning producono per design risposte più lunghe del Default.