Come creare un output style in Claude Code senza confonderlo con le istruzioni di progetto

Se in ogni sessione scrivi “rispondi in modo sintetico, apri con l'esito e separa prove e prossima azione”, stai ripetendo una regola di formato. Un output style può renderla persistente. Non è però il posto giusto per inserire architettura del repository, procedura di deploy o permessi.

La documentazione degli output style li definisce come configurazioni che cambiano ruolo, tono e formato predefinito delle risposte. Non aggiungono conoscenza. La parte delicata è capire che cosa mettere nello style e che cosa lasciare agli altri strati di Claude Code.

Metti ogni istruzione nel posto giusto

Usa questa matrice prima di creare un file.

La distinzione impedisce allo style di diventare un manuale universale. Più regole inserisci nel comportamento trasversale, più è facile che una richiesta semplice erediti vincoli che non le servono.

Uno style non sostituisce i permessi. “Sii prudente” non impedisce tecnicamente una scrittura. Accessi e approvazioni restano configurazioni separate.

Definisci un contratto osservabile dell'output

Evita formule come “professionale”, “chiaro” o “di alta qualità” se non le traduci in qualcosa che puoi rileggere.

Un contratto piccolo può dire:

• apri con l'esito in una frase;

• separa fatti, inferenze e decisioni;

• conserva per intero errori e avvisi di sicurezza;

• cita file o comandi quando sostengono una conclusione;

• termina con la prossima azione solo se ne esiste una.

Non chiedere sempre una tabella, tre sezioni e cinque bullet. Il formato deve servire il lavoro. Una risposta di una riga non migliora se la costringi dentro una struttura da report.

Scegli due o tre comportamenti che puoi verificare su output diversi. Lo style deve ridurre ripetizioni, non nascondere il giudizio dietro un template.

Decidi se mantenere le istruzioni di coding

Questo è il passaggio più importante. La documentazione ufficiale segnala che uno style custom non conserva per impostazione predefinita le istruzioni software di Claude Code. Se stai cambiando solo il modo in cui Claude comunica ma vuoi mantenere il comportamento da coding agent, imposta:

keep-coding-instructions: true

Se invece vuoi usare Claude Code come assistente di scrittura o analisi senza il comportamento software predefinito, puoi lasciare fuori il campo. La scelta deve essere intenzionale.

Non dedurre l'esito dal nome dello style. “Revisore tecnico” potrebbe richiedere ancora le istruzioni di coding; “Analista documentale” potrebbe non averne bisogno. Scrivi nello stesso brief dello style che cosa deve rimanere attivo.

Scrivi uno style minimo

Uno style custom è un file Markdown con frontmatter e istruzioni. Un esempio essenziale per un lavoro tecnico può essere:

---
name: Esito e prove
description: Apre con il risultato e separa evidenze e limiti
keep-coding-instructions: true
---

Apri con l'esito concreto.
Poi indica le evidenze che lo sostengono e i limiti ancora aperti.
Non abbreviare errori, avvisi di sicurezza o conferme per azioni distruttive.
Usa una struttura più lunga solo quando migliora la verifica.

Il file non contiene comandi del progetto, nomi di branch o regole di rilascio. Quelle informazioni cambiano con il repository e appartengono alle istruzioni di progetto o alla procedura competente.

Scegli lo scope più stretto

Claude Code supporta style a livello utente, progetto e policy gestita. Parti dallo scope più stretto che risolve il problema.

• Progetto: adatto quando un team vuole un formato condiviso in un repository.

• Utente: adatto a una preferenza personale valida in più progetti.

• Policy gestita: adatta a una scelta amministrata dall'organizzazione.

La documentazione indica anche che, quando esistono directory di style annidate con lo stesso nome, viene usata quella più vicina alla directory di lavoro. Per questo nome, percorso e owner devono essere espliciti. Due file chiamati allo stesso modo possono produrre una differenza che sembra casuale.

Attiva lo style tramite /config o la configurazione prevista dalla versione corrente. Dopo aver creato o modificato il file, verifica che la sessione lo abbia davvero caricato. La presenza sul disco non dimostra l'attivazione.

Provalo su tre casi diversi

Non testare lo style soltanto con il prompt per cui lo hai scritto. Usa tre casi:

1. Sintesi: chiedi lo stato di una modifica piccola. L'esito deve arrivare prima della cronaca.

2. Errore: fornisci un comando fallito. L'errore deve restare completo e distinguersi dall'interpretazione.

3. Modifica: chiedi un intervento circoscritto. Se hai mantenuto le istruzioni di coding, scope e verifica non devono scomparire.

Registra atteso e osservato in una tabella. Se lo style rende il caso semplice troppo verboso o abbrevia un avviso importante, correggi la regola specifica. Non compensare con un secondo style attivo nello stesso scope.

La prova può seguire la logica del controllo delle modifiche di un workflow AI: baseline, variazione, casi di prova e decisione di tenere o ripristinare.

Controlla ciò che lo style non deve cambiare

Uno style riuscito modifica la forma attesa, non l'autorità del task. Verifica che non abbia alterato:

• accesso a file, terminale o rete;

• regole di approvazione;

• fonti e convenzioni del repository;

• criteri di test;

• comportamento di agent con istruzioni proprie.

La documentazione ufficiale chiarisce che i subagent con un proprio system prompt non ereditano semplicemente lo style della conversazione principale. Se vuoi coerenza tra agenti, devi progettarla nei rispettivi contratti, non presumere che lo style si propaghi.

Uno style può anche aumentare i token di input o output in base alle istruzioni. Non dichiarare un risparmio prima di confrontare task equivalenti.

Versiona, distribuisci e torna indietro

Conserva il file come una configurazione piccola:

• owner;

• scopo;

• data di modifica;

• tre casi di prova;

• risultato atteso;

• versione precedente o istruzione per disattivarlo.

Se lo style è di progetto, trattalo come qualsiasi modifica condivisa: diff leggibile, review e prova. Se è personale, annota almeno perché esiste. Un nome come conciso.md non spiega quali informazioni non devono mai essere abbreviate.

Per un comportamento operativo ripetibile resta utile una SOP per un workflow AI. Lo style governa come arriva la risposta; la SOP governa che cosa deve succedere e come verificarlo.

Nel programma su Claude Cowork e Code puoi partire da una preferenza che ripeti ogni giorno, decidere se è davvero uno style e provarla senza mescolarla a contesto, procedure o permessi. Una configurazione piccola e collocata bene vale più di un file che tenta di governare tutto.