Il fixer di prompt che diagnostica prima di riscrivere

Incolla un prompt difettoso in quasi ogni "ottimizzatore di prompt" e ottieni sempre la stessa mossa: il tuo prompt entra in un template magico — framework 4-D! 27 pattern! — ed esce più lungo, ristrutturato da cima a fondo, senza traccia di quale cambiamento contasse o se svolge ancora lo stesso compito. Si legge meglio. Se funzioni meglio è una proprietà diversa, e lo strumento non lo verifica mai.

Gestiamo una directory che testa le skill di Claude sul campo, e volevamo l'opposto. Così abbiamo costruito prompt-discipline, che tratta un prompt come tratteresti un bug report: nomina il failure mode prima, applica la correzione più piccola che lo risolve, poi dice esattamente come fare l'A/B del cambiamento. È gratis e con licenza MIT: github.com/Skillproofdev/prompt-discipline.

Il vuoto: chi riscrive non diagnostica, chi diagnostica ha bisogno di infrastruttura

Prima di scrivere una regola abbiamo passato in rassegna 43 skill di prompt engineering nel nostro catalogo più gli strumenti standalone — il prompt improver della Console di Anthropic, PromptPerfect, DSPy, il prompt-optimizer di getsentry. Il campo si divide in due schieramenti che non si incontrano mai.

I riscrittori a template trasformano ogni input allo stesso modo. Non c'è nessun passo che chiede cosa c'è davvero di sbagliato qui — un prompt vago e un prompt contraddittorio ricevono lo stesso trattamento, e l'output è affidabilmente più lungo. Non è un uomo di paglia: il miglioramento della Console di Anthropic avvisa apertamente che le sue riscritture vengono più lunghe e più lente. Più lungo è il prodotto.

Le pipeline eval-first — DSPy, ottimizzatori guidati da trace — hanno l'epistemologia giusta. Misurano davvero. Ma richiedono infrastruttura: trace di produzione, un server MCP, un harness worktree, un dataset etichettato che devi assemblare prima. Non ci ricorri per correggere il prompt che stai editando adesso.

Nessuno mette in campo la cosa di mezzo: una skill senza dipendenze che fa diagnosi-prima → diff-minimo → piano di test A/B, senza trace e senza server da configurare. Quel vuoto è l'intera skill.

Nove regole, tre delle quali sono il punto

La skill è un insieme di regole rigide applicate in ordine (SKILL.md completo). Le parti familiari ci sono — il formato d'output come contratto positivo (una lista di chiavi con i tipi, non "rispondi in JSON"), esempi al posto di aggettivi, liste di divieti riscritte come istruzioni positive, ordine ruolo→dati→istruzioni→esempi→query. Le tre che la definiscono:

1. Diagnostica prima di toccare qualsiasi cosa. Classifica cosa c'è davvero di sbagliato — ambiguità, contesto mancante, nessun contratto d'output, istruzioni in conflitto, rischio di deriva di formato, over-prompting, o "non è un problema di prompting" — e cita lo span incriminato per ciascun finding. Nessuna diagnosi, nessuna riscrittura. "Questo prompt va bene" è un output valido e completo.
2. Diff minimo, un cambiamento per failure. Ogni modifica mappa esattamente un failure diagnosticato, mostrato come vecchio → nuovo con una motivazione di una riga. Le parti che funzionano restano testuali. Dove il miglioratore della Console imbottisce, questo di solito esce più corto — incantesimi morti ("sei il migliore al mondo…", "fai un respiro profondo", vecchi scaffold "think step by step") vengono tagliati.
3. Un piano di test, non una promessa. Ogni riscrittura arriva con 2–3 input di test concreti incluso un edge case, cosa significa "passare", e la procedura A/B: stessi input, stesso modello, 3–5 run ciascuno, confronta i tassi di successo. Se sono state accumulate più modifiche, nomina quale ripristinare per prima. Non promette mai "questo lo risolverà" — hai cambiato variabili, decide il test.

Il benchmark — e un avvertimento da leggere prima

Dieci prompt genuinamente difettosi, ciascuno abbinato a un task con una risposta verificabile meccanicamente: estrazione contro ground truth nota, formattazione che deve fare parsing (json.loads / csv.reader), classificazione contro esempi etichettati. Tre bracci per caso — il prompt originale, una riscrittura base (Claude semplice a cui viene detto "migliora questo prompt"), e una riscrittura con skill (stessa sessione con questo SKILL.md caricato). Tutte le riscritture poi girano come task sullo stesso modello.

Leggi questo prima della tabella: il run è n=1 per caso per braccio, non l'n=5 pre-registrato. La varianza di campionamento non è misurata. Qualsiasi divario su un singolo caso (0,1) è dentro il rumore di fondo. Tratta ogni numero qui come provvisorio in attesa di una replica n=5 — lo facciamo anche noi.

Braccio	Successo task	Conformità formato	Δ mediana lunghezza prompt
A — prompt originale	0,70 (7/10)	0,70 (7/10)	—
B — riscrittura base ("migliora questo prompt")	0,80 (8/10)	0,70 (7/10)	+99,5 parole
C — riscrittura con skill (questo SKILL.md)	0,90 (9/10)	0,80 (8/10)	+44,5 parole

Contro il test pre-registrato la skill passa: pareggia-o-batte la riscrittura base sul successo (0,90 ≥ 0,80) e sulla conformità (0,80 ≥ 0,70), supera la soglia di +15 pp rispetto all'originale (+20 pp), e lo fa aggiungendo meno della metà del rigonfiamento del prompt — mediana +44,5 parole contro le +99,5 della riscrittura base. Quest'ultimo numero è il risultato più robusto dell'intero run: C è più snello su tutti e dieci i casi, ed è l'unico braccio che va mai in negativo (caso-10, −10 parole, tagliando un accumulo di divieti da un prompt di sistema). Sia la riscrittura ingenua che quella disciplinata gonfiano i prompt concisi; quella ingenua ne raddoppia grosso modo il costo.

Dove è debole, e dove ha perso

I vantaggi su successo e conformità sono reali ma fragili, e non faremo finta del contrario.

Su 7 dei 10 casi, tutti e tre i bracci pareggiano. Il margine di successo poggia quasi interamente sul caso-06 (classificazione ticket), l'unico caso che la skill vince nettamente: C ha prodotto etichette corrette, parsabili elemento per elemento (15/15) mentre la riscrittura base ha ottenuto 13/15 in un formato che non parsava. Togli quel caso e il divario principale evapora quasi del tutto. È quello che sembra n=1 con molti pareggi — onesto, non compromettente, ma devi saperlo.

Il caso-09 è una sconfitta per la skill sul suo stesso terreno. Un prompt di correzione di tono con un pubblico mancante — esattamente la situazione per cui esiste la Regola 2 ("dichiara la tua assunzione quando l'intento è indecidibile"). La regola non è scattata. La riscrittura della skill ha perso il problema del pubblico mancante, e C ha fallito insieme ad A e B. Una skill che perde proprio nella cosa che è specificamente progettata per catturare è il tipo più utile di risultato negativo, quindi resta nella tabella.

La conformità del caso-02 è 0 su tutti e tre i bracci. Un prompt con istruzioni contraddittorie: ogni braccio ha risolto la contraddizione nel contenuto (ha ottenuto il numero giusto) ma nessuno ha forzato un singolo output, quindi tutti e tre hanno segnato 0 sul formato. Né il riscrittore disciplinato né quello ingenuo hanno pensato a imporre il contratto. Punto cieco condiviso, riportato non nascosto.

Testiamo le skill di altri per lavoro, e la nostra metodologia richiede di mettere le perdite accanto alle vittorie. Queste sono le perdite.

Installazione

git clone https://github.com/Skillproofdev/prompt-discipline ~/.claude/skills/prompt-discipline

Riavvia Claude Code. Si attiva su "migliora questo prompt", "perché il mio prompt fallisce", "ottimizza prompt", e quando stai scrivendo o rivedendo prompt di sistema e istruzioni per agenti — e rifiuta richieste di jailbreak/bypass di sicurezza e prompt di generazione immagini/video, che hanno una grammatica propria. Fa parte della nostra serie discipline: token-discipline taglia quanto costa una sessione, research-discipline taglia quanto la ricerca sbaglia, e questa taglia le riscritture di prompt fino al cambiamento che contava davvero.

FAQ

In cosa è diverso dal prompt improver della Console di Anthropic? Il miglioratore della Console è un riscrittore a template — ristruttura l'intero prompt e avvisa apertamente che il risultato viene più lungo e più lento. prompt-discipline diagnostica prima il failure specifico, cambia solo ciò che mappa a quel failure, e nel nostro benchmark ha aggiunto meno della metà della lunghezza pur uscendo di solito più corto. Obiettivo diverso: lo strumento della Console produce un prompt lucidato; questo produce il diff più piccolo difendibile più un modo per dimostrarlo.

Perché pubblicare un benchmark che ammettete essere n=1? Perché l'alternativa in questa nicchia è non pubblicare numeri, che è la norma contro cui reagiamo. n=1 con l'avvertimento dichiarato apertamente è più onesto di un'affermazione sicura senza alcuna misurazione dietro. Il risultato sulla lunghezza mediana è solido su tutti e dieci i casi; i vantaggi su successo e conformità sono provvisori ed etichettati come tali, in attesa di una replica n=5.

Riscrive sempre il mio prompt? No. Se il prompt va bene, la skill lo dice e si ferma — "questo prompt non ha bisogno di modifiche; ecco l'unico rischio da testare" è un output valido e completo. Rifiuta anche di imbottire una diagnosi solo per giustificare l'applicazione di un template, e rifiuta le richieste di jailbreak invece di "migliorarle".

Questo mi correggerà il prompt? Non lo promette, e non dovrebbe farlo nessuno strumento che non ha eseguito il tuo task. La skill cambia variabili e ti dà una procedura A/B concreta — stessi input, stesso modello, 3–5 run — così decide il test, non la sensazione di un prompt che sembra più pulito.