Generazione dei test e standard

Se chiede a Claude Code di "scrivere i test per questo modulo" senza fornire indicazioni, otterrà test che vengono eseguiti ma non rispettano lo stile del team: helper del framework sbagliati, fixture inventate, asserzioni che rispecchiano l'implementazione invece del contratto.

La soluzione non è un prompt occasionale migliore. Sono standard persistenti e condivisi che il modello legge a ogni esecuzione. Questa lezione mostra come documentare fixture e convenzioni, affinché i test generati risultino idiomatici, deterministici e facili da revisionare, sia nelle sessioni interattive sia in CI.

Le convenzioni per i test devono appartenere alla configurazione a livello di progetto, così ogni collaboratore e ogni runner CI può vederle. Le inserisca in ./CLAUDE.md o .claude/CLAUDE.md, condivisi tramite VCS.

NON faccia affidamento su ~/.claude/CLAUDE.md a livello utente: è personale e NON viene condiviso tramite il controllo di versione, quindi i nuovi membri del team e la pipeline semplicemente non lo avranno. Tutto ciò da cui dipende la generazione dei test deve risiedere nell'ambito del progetto.

Un CLAUDE.md monolitico diventa difficile da leggere e consuma contesto. Sposti il playbook dettagliato dei test in un file dedicato e lo importi usando la sintassi @path. In questo modo il file principale rimane snello, pur caricando lo standard.

Il file importato è semplice markdown, sottoposto al controllo di versione come tutto il resto; lo standard è quindi riutilizzabile e facile da revisionare separatamente.

Ancora meglio degli import sempre attivi: inserisca le convenzioni dei test in un file di .claude/rules/ con frontmatter YAML paths. La regola viene caricata solo quando si modificano file corrispondenti, consentendo di risparmiare contesto e token rispetto a un CLAUDE.md monolitico che invia tutto a ogni turno.

Limiti una regola alla directory dei test: si attiverà esattamente quando Claude genera o modifica test e resterà inattiva in tutti gli altri casi.

La causa principale dei test generati in modo errato sono le fixture inventate: il modello fabbrica un oggetto utente o uno stub del database invece di usare quelli esistenti. Documenti le fixture reali, così Claude potrà riutilizzarle.

Specifichi cosa fornisce ogni fixture, la sua struttura e quando utilizzarla. La tratti come la descrizione di uno strumento: scopo, valore restituito, formato dell'input e limiti di applicabilità sono gli elementi che guidano una selezione corretta.

La sola prosa lascia spazio all'ambiguità. Aggiunga da 2 a 4 esempi mirati di un test canonico: il modello generalizza lo schema, non si limita a copiarlo. Gli esempi few-shot sono il mezzo più efficace per garantire coerenza, gestire i casi limite e definire il formato dell'output.

Mostri un test completo e idiomatico che utilizzi le fixture reali. I nuovi test ne rispecchieranno la struttura, i nomi e lo stile delle asserzioni.

"Scrivere buoni test" è un desiderio vago. I criteri espliciti producono un output affidabile. Confronti "essere esaustivi" con "coprire il percorso principale, un valore di confine e un percorso di errore; non testare mai direttamente i metodi privati."

Regole concrete e verificabili eliminano le supposizioni che rendono incoerenti i test generati tra file e collaboratori diversi.

Renda il flusso di lavoro ripetibile con una skill in .claude/skills/ (l'ambito del progetto è condiviso tramite VCS, quello dell'utente è personale). La skill raggruppa il Suo standard e può limitare gli strumenti e isolare l'output.

Utilizzi context: fork per isolare l'output dettagliato della generazione, allowed-tools per limitare ciò che può modificare e argument-hint per guidare il chiamante. Ora "generare test secondo lo standard" è un comando riutilizzabile, invece di un paragrafo da riscrivere.

Non generi nel vuoto. Chieda a Claude di seguire prima lo schema di indagine incrementale: usi Glob per individuare i file di test esistenti, Read per leggerne alcuni, Grep per verificare come viene utilizzata una fixture, quindi scriva un nuovo test coerente con quelli già presenti.

Basare la generazione sul codebase reale è meglio che recitare una guida di stile, perché il modello copia convenzioni vive e funzionanti invece di procedere per supposizioni.

In una pipeline, generi i test senza interfaccia con -p (obbligatorio: non è presente alcun essere umano) e --output-format json, così un passaggio successivo può analizzare il risultato. Poi revisioni i test generati in una sessione separata e isolata.

La revisione da un'istanza nuova è migliore dell'autovalutazione nella stessa sessione: l'autore conserva il proprio ragionamento e non metterà in discussione i propri test. Un revisore indipendente individua asserzioni tautologiche e casi di errore mancanti che il generatore ha trascurato.

Quando richiede test come output strutturato (tool_use + JSON Schema), convalidi il risultato. Se è malformato, utilizzi retry-with-feedback: invii nuovamente la richiesta originale, l'output errato e l'errore di convalida esatto. Questo risolve in modo affidabile gli errori di formato e struttura.

Due avvertenze dalla scheda informativa: retry NON è utile quando l'informazione necessaria è semplicemente assente dalla fonte; inoltre, contrassegni un campo dello schema come required solo se è sempre presente, altrimenti il modello lo inventerà.

Punti chiave:

• Inserisca gli standard di test nell'ambito del progetto (./CLAUDE.md, .claude/rules/ con paths), condiviso tramite VCS; non faccia mai affidamento sul file personale ~/.claude/CLAUDE.md in CI.
• Modularizzi con import @path; le regole con frontmatter paths vengono caricate solo quando si modificano file corrispondenti, risparmiando contesto.
• Documenti le fixture come fonte autorevole (scopo, struttura, momento di utilizzo), così il modello le riutilizza invece di inventare stub.
• Il few-shot (2-4 esempi canonici) insieme a criteri espliciti è migliore delle istruzioni vaghe; il modello generalizza lo schema.
• Racchiuda tutto in una skill in .claude/skills/; faccia indagare a Claude i test esistenti (Glob/Read/Grep) prima di scrivere.
• In CI, generi senza interfaccia con -p --output-format json, poi esegua la revisione in una sessione nuova e isolata.
• Convalidi l'output strutturato; retry-with-feedback corregge gli errori di formato ma non le informazioni mancanti, e renda obbligatorio un campo dello schema solo se è sempre presente.