3 novembre 2026Aggiornato il Fathy Shalaby17 min di lettura
Template di PRD per agenti di coding AI (Claude Code, Cursor, Copilot)
Un template di PRD da copiare e incollare per agenti di coding AI, dove si colloca accanto a CLAUDE.md, AGENTS.md e alle regole di Cursor, e come scrivere controlli di accettazione che un agente possa eseguire.
Un template di PRD per agenti di coding AI è un brief breve e specifico per un compito che dice a Claude Code, Cursor o GitHub Copilot chi ha il problema, che cosa deve cambiare, che cosa è fuori ambito e quali controlli dimostrano che il lavoro è finito. Tieni le regole stabili del progetto in CLAUDE.md, AGENTS.md o nelle regole di Cursor. Tieni la decisione sulla funzionalità nel PRD. Il template qui sotto sta in una o due pagine.
Punti chiave
Gli agenti sono veloci e spesso sbagliano di poco. Nel sondaggio di Stack Overflow del 2025, il 66% degli sviluppatori ha indicato le soluzioni AI «quasi giuste, ma non del tutto» tra le principali frustrazioni, e l'86,9% era preoccupato per l'accuratezza degli agenti AI (Stack Overflow, 2025).
I fornitori concordano che i file di istruzioni di progetto devono essere brevi e generali: Anthropic punta a meno di 200 righe per CLAUDE.md, Cursor dice di tenere le regole sotto le 500 righe, e il prompt di onboarding di GitHub limita le istruzioni di Copilot a 2 pagine ed esclude i contenuti specifici di un compito.
Quindi la decisione sulla funzionalità ha bisogno di una casa propria: un PRD per compito, collegato dall'issue o dalla pull request.
La sezione che cambia di più il risultato dell'agente sono i controlli di accettazione. Un agente con un controllo pass/fail può testare e correggere il proprio lavoro; un agente senza si ferma quando il lavoro sembra soltanto finito.
I requisiti vaghi erano costosi già prima dell'AI. Il PMI ha trovato una cattiva gestione dei requisiti dietro il 47% dei progetti che non hanno raggiunto gli obiettivi (PMI, 2014).
Che cos'è un template di PRD per agenti di coding AI?
Un product requirements document (PRD) per un agente di coding risponde alle stesse domande di qualsiasi PRD: di chi è il problema, che cosa deve cambiare e come sapremo che ha funzionato? La differenza è il lettore. Un ingegnere umano chiede su Slack quando qualcosa è ambiguo. Un agente di solito sceglie un'interpretazione e va avanti.
La guida a Claude Code di Anthropic lo dice senza giri di parole: Claude tende a prendere una richiesta nel suo senso più stretto e a costruire il minimo che la soddisfa, perché non può capire quanto ambiziosa fosse l'intenzione (Anthropic, Claude Code best practices). La soluzione non è un prompt più lungo. È un brief che dice ciò che un collega umano avrebbe colto nella stanza.
Un agente di coding più la persona che ne rivede il lavoro
Ambito
Spesso un'intera release
Un compito o una fetta verticale
Lunghezza
Spesso diverse pagine
Una o due pagine; link per i dettagli
Ambiguità
Risolta a voce
Elencata come domande aperte e regole di stop
Non-obiettivi
Utili
Obbligatori, perché l'agente lasci stare il codice adiacente
Criteri di accettazione
Letti dal QA
Scritti come controlli che l'agente può eseguire e su cui può riferire
Dove vive
Wiki o strumento di documenti
Repo o issue, collegato dalla pull request
Perché gli agenti di coding AI hanno bisogno di un PRD?
Perché il codice non dice a un agente quale problema del cliente conta, quale compromesso il team ha accettato o che cosa è volutamente fuori ambito. Questi fatti vivono in interviste, ticket e riunioni. Se nessuno li scrive, l'agente riempie il vuoto con un'ipotesi plausibile.
L'uso degli agenti è ormai abbastanza diffuso da far contare la cosa. Nel sondaggio di Stack Overflow del 2025, l'84% degli intervistati usava o pianificava di usare strumenti AI, il 14,1% usava agenti AI al lavoro ogni giorno e un altro 9% ogni settimana. La fiducia resta indietro rispetto all'uso: il 46% non si fidava dell'accuratezza dell'output AI, contro il 33% che si fidava (Stack Overflow, 2025).
L'intento vago era costoso molto prima degli agenti. La ricerca del PMI del 2014 ha rilevato che la cattiva gestione dei requisiti ha fatto mancare gli obiettivi al 47% dei progetti falliti e ha sprecato il 5,1% di ogni dollaro speso nei progetti (PMI, 2014). Con un agente, la stessa vaghezza si presenta come una pull request sicura di sé in pochi minuti invece che come una sorpresa alla sprint review.
La sicurezza è l'altro motivo per essere espliciti. Veracode ha testato più di 100 large language model e ha trovato che il 45% degli esempi di codice generato introduceva una vulnerabilità della OWASP Top 10; per gli esempi in Java il tasso di fallimento era del 72% (Veracode, 2025). Un PRD da solo non risolve il problema, ma un elenco di «non deve» e un controllo di sicurezza con un nome dicono all'agente e al revisore dove guardare.
Che cosa va in CLAUDE.md o AGENTS.md e che cosa va nel PRD?
Dividi il contesto in base a quanto a lungo resta vero. I file di istruzioni del repository contengono regole che valgono per ogni compito. Il PRD contiene la decisione per questo compito. Mescolarli peggiora entrambi: il file di istruzioni si gonfia e la decisione sulla funzionalità ci si perde dentro.
Ogni strumento documenta i propri file di istruzioni e le proprie indicazioni di dimensione:
Strumento
File di istruzioni del progetto
Indicazione di dimensione del fornitore
Opzione a livello di compito
Claude Code
CLAUDE.md (ambiti managed, user, project e local), .claude/rules/ con filtri di percorso; legge AGENTS.md quando manca CLAUDE.md
Puntare a meno di 200 righe per file
Fare riferimento a un file di spec con @path; chiedere a Claude di intervistarti e scrivere SPEC.md
Cursor
.cursor/rules/*.mdc (sempre, intelligenti, per file o manuali); AGENTS.md, anche annidati
Tenere le regole sotto le 500 righe
Menzionare il file del PRD con @ nella chat
GitHub Copilot
.github/copilot-instructions.md, .github/instructions/*.instructions.md con applyTo; AGENTS.md, CLAUDE.md o GEMINI.md
Prompt di onboarding: non oltre 2 pagine, non specifico per un compito
File di prompt, scelti chat per chat
Qualsiasi agente AGENTS.md
AGENTS.md; vince il file più vicino al codice modificato
Nessun campo obbligatorio; usato da oltre 60k progetti open source
Due dettagli della documentazione dei fornitori guidano la divisione. Anthropic dice che Claude tratta CLAUDE.md come contesto e non come configurazione imposta, e che file più lunghi riducono l'aderenza. La documentazione di Copilot di GitHub descrive i file di prompt come qualcosa che scegli chat per chat, a differenza delle istruzioni che si applicano automaticamente (GitHub Docs). Entrambi vanno nella stessa direzione: le regole durature vanno nel file sempre caricato, le decisioni una tantum in un file che passi per quel compito.
Metti nelle istruzioni del repository:
Comandi di build, test, typecheck e lint, incluso come eseguire un singolo file di test
I punti in cui il codice è fuorviante, come un pattern legacy che il nuovo codice non deve copiare
Decisioni non visibili nel codice: l'helper per gli errori, il processo di deploy, che cosa richiede una revisione della migrazione
Regole di sicurezza, privacy e accessibilità che valgono ovunque
Dove vivono le decisioni di prodotto, come link
Metti nel PRD:
L'utente, il problema e le evidenze che lo sostengono
Il risultato, la sua baseline e i guardrail
Dentro l'ambito, fuori ambito e «non deve»
Il comportamento richiesto, inclusi gli stati vuoto, di caricamento e di errore
I controlli di accettazione e i comandi che li verificano
Le domande aperte e chi le decide
La documentazione di Cursor aggiunge una regola utile per entrambi: fai riferimento ai file invece di copiarne il contenuto, perché le copie diventano obsolete. Linka la ricerca; non incollarla.
Il template di PRD da copiare per agenti di coding AI
Copialo in docs/specs/<feature>.md o nel corpo dell'issue. Tieni brevi le risposte e linka ricerche, design o note tecniche per i dettagli.
# PRD: [titolo di lavoro]
Responsabile: [nome] | Stato: bozza / approvato | Data: [AAAA-MM-GG]
Issue / PR: [link]
## 1. Problema
- Utente principale:
- Situazione e problema (una frase):
- Evidenze: [link]. Segna ogni elemento come osservato / dedotto / ipotizzato.
- Perché adesso:
- Che cosa ancora non sappiamo:
## 2. Risultato
- Risultato per l'utente: che cosa diventa più facile, più veloce o più sicuro?
- Segnale di prodotto: il comportamento che mostrerebbe che ha aiutato
- Baseline: [numero + fonte] oppure "sconosciuta: prima strumentare"
- Guardrail: che cosa non deve peggiorare (errori, privacy, latenza, controllo dell'utente)
## 3. Ambito
- Dentro l'ambito:
- Fuori ambito (non-obiettivi):
- Non deve: [azioni o effetti collaterali vietati]
- Dipendenze:
## 4. Comportamento richiesto
R1. Punto di ingresso e percorso principale, in linguaggio semplice:
R2. Stati vuoto, di caricamento e di errore:
R3. Permessi e gestione dei dati:
R4. Casi limite che cambiano la decisione:
## 5. Contesto
- Comportamento attuale: [route, schermata o file]
- Decisioni rilevanti: [link al decision record]
- Vincoli noti: [piattaforma, compatibilità, latenza, policy]
- Regole del repository: vedi CLAUDE.md / AGENTS.md
- Se due fonti sono in conflitto: fermati e chiedi a [responsabile]
## 6. Comportamento dell'AI (solo se la funzionalità usa un modello)
- Input che il modello può usare:
- Output mostrato o salvato:
- Grounding: quale fonte sostiene ogni affermazione
- Incertezza: quando dire "evidenze insufficienti" o chiedere
- Controllo umano: quali azioni richiedono una revisione
- Gestione dei fallimenti: timeout, output malformato, evidenze mancanti
- Casi di valutazione: [link, inclusi esempi difficili e negativi]
## 7. Controlli di accettazione
AC1. Dato [stato], quando [azione], allora [risultato osservabile].
AC2. Se [condizione indesiderata], allora il sistema deve [fallback sicuro].
AC3. Dato [utente senza permessi], quando [lo apre], allora non compaiono dati riservati.
AC4. Regressione: [comando di test esistente] continua a passare.
Verifica con: [comandi di test, typecheck, lint ed end-to-end]
## 8. Accordo di esecuzione per l'agente
1. Leggi questo PRD e le istruzioni del repository prima di modificare qualsiasi cosa.
2. Riformula il requisito ed elenca le domande aperte. Aspetta le risposte su tutto ciò che è segnato come "decisione".
3. Proponi un piano: file da modificare, test da aggiungere. Aspetta l'approvazione.
4. Costruisci la fetta più piccola che supera i controlli di accettazione.
5. Fermati e chiedi prima di cambiare un'API pubblica, toccare auth, billing o migrazioni, aggiungere una dipendenza o risolvere da solo una domanda aperta.
6. Esegui i comandi di verifica e incolla i comandi e il loro output.
7. Riassumi il comportamento modificato, le ipotesi e i rischi residui.
Quali sezioni contano di più?
Non-obiettivi e «non deve». Un non-obiettivo di una riga («nessun nuovo costruttore di dashboard», «non cambiare le definizioni dei report») impedisce a un agente ragionevole di trasformare una piccola richiesta in un redesign. Alcuni strumenti bloccano già le azioni più rischiose. La modalità automatica di Claude Code, per esempio, blocca per impostazione predefinita i deploy in produzione e le migrazioni, i force push e il merge di una pull request che nessun umano ha approvato (Anthropic, permission modes). Il tuo elenco aggiunge i divieti specifici del prodotto che nessuno strumento può conoscere: la logica dei prezzi, il testo del consenso, un'email rivolta ai clienti.
Stato delle evidenze. Segnare ogni riga di evidenza come osservata, dedotta o ipotizzata evita che un'ipotesi sembri un fatto una volta finita in un documento ordinato. Il claim trace di 15 minuti per spec scritte dall'AI mostra come verificarlo prima della consegna.
Un limite: tutto ciò che è scritto in un PRD o in CLAUDE.md è un'indicazione che l'agente può decidere non si applichi. Il consiglio di Anthropic è che una regola che non ammette eccezioni appartiene a un hook, a una regola di divieto o a un'impostazione gestita, non alla prosa (Anthropic, Claude Code best practices).
Come si scrivono criteri di accettazione che un agente di coding AI possa verificare?
Scrivi ogni controllo in modo che restituisca pass o fail, e indica il comando o l'osservazione che lo decide. La guida di Anthropic elenca i tipi di controlli che Claude può leggere: un file di test, il codice di uscita di una build, un linter, uno script che confronta l'output con una fixture, o uno screenshot del browser accanto al mockup.
Due sintassi mantengono i criteri di accettazione testabili:
Given / When / Then (dato / quando / allora), dal behavior-driven development: «Data una vista salvata, quando l'utente la elimina, allora scompare dalla barra laterale e l'API dell'elenco non la restituisce più.»
EARS (Easy Approach to Requirements Syntax), creata da Alistair Mavin e colleghi in Rolls-Royce e pubblicata per la prima volta nel 2009 (Mavin, EARS). Usa cinque pattern:
Pattern EARS
Template
Esempio di prodotto
Ubiquitous
Il sistema deve …
L'esportazione deve includere una riga di intestazione.
Event-driven
Quando [trigger], il sistema deve …
Quando un upload supera i 10 MB, il sistema deve mostrare il limite di dimensione.
State-driven
Finché [stato], il sistema deve …
Finché è in corso una sincronizzazione, il sistema deve disattivare il pulsante Salva.
Unwanted behaviour
Se [condizione], allora il sistema deve …
Se il modello non restituisce alcuna fonte, allora il sistema deve segnare il tema come «non supportato».
Optional feature
Dove [funzionalità], il sistema deve …
Dove è attivo il SSO, il sistema deve nascondere il campo password.
Gli esempi sono illustrativi. Il pattern «Se … allora» è il più utile per gli agenti, perché il comportamento indesiderato è dove tirano a indovinare.
Poi chiedi evidenze, non un verdetto. Anthropic consiglia di chiedere a Claude il comando eseguito e il suo output, perché la semplice affermazione che i test passano è una prova debole. Come seconda linea di difesa, fai rivedere il diff rispetto al PRD a una sessione nuova o a un subagent che non ha scritto il codice.
Esempio compilato: riassunti dei temi per trascrizioni di interviste
Questo esempio è illustrativo, non è una ricerca su un cliente reale.
Problema. Un team di prodotto di cinque persone ha 12 trascrizioni di interviste sparse in più documenti. Prima di una riunione di pianificazione vuole vedere i problemi ricorrenti senza perdere le evidenze dei partecipanti dietro ciascuno.
Comportamento desiderato. Un membro del team seleziona le trascrizioni e chiede una bozza di riassunto dei temi. Ogni tema rimanda ai passaggi che lo sostengono. Il membro modifica il riassunto prima di condividerlo.
Dentro l'ambito. Temi in bozza, link alle fonti, un passaggio di revisione modificabile.
Fuori ambito. Pubblicare automaticamente i temi, cambiare la roadmap, o presentare un conteggio di temi da 12 interviste come stima valida per tutto il mercato.
Non deve. Inventare una citazione, attribuire un'affermazione al partecipante sbagliato, o dichiarare una frequenza che le trascrizioni non supportano.
Controlli di accettazione.
Data una trascrizione con un passaggio su un problema di configurazione, quando il riassunto include quel tema, allora il lettore può aprire l'esatto passaggio che lo sostiene.
Se un tema non ha alcun passaggio a supporto, allora il sistema deve segnarlo come «incerto» invece di colmare il vuoto.
Dato un riassunto generato, quando il membro del team lo apre, allora può modificarlo prima che venga condiviso.
Data una trascrizione con informazioni personali, quando la funzionalità la elabora, allora si applicano le regole di dati e accesso già esistenti del workspace.
Baseline. Sconosciuta. Prima di fissare un obiettivo, il team cronometra quanto tempo serve per trovare a mano le evidenze di tre temi e conta le correzioni dei revisori. L'esempio non presuppone alcun miglioramento particolare.
Come passi il PRD a Claude Code, Cursor o Copilot?
Scrivi il PRD. Scrivilo tu, parti dal generatore di PRD gratuito o usa i prompt di come scrivere un PRD con l'AI. In Claude Code puoi chiedergli di intervistarti finché non è in grado di scrivere la spec, poi salvarla come SPEC.md.
Mettilo dove l'agente può leggerlo. Salvalo nel repo o nell'issue e fai riferimento al percorso (@docs/specs/saved-views.md in Claude Code o Cursor).
Chiedi prima una riformulazione e un piano. La modalità piano di Claude Code lascia che l'agente legga ed esplori, ma blocca le modifiche finché non approvi il piano. Correggi i malintesi qui, dove non costano nulla.
Costruisci in una sessione nuova. Anthropic suggerisce di avviare la costruzione in una nuova sessione una volta che la spec esiste, così si parte senza le chiacchiere di pianificazione e con la spec come definizione di completato.
Riporta le nuove decisioni nel registro. Se il lavoro ha fatto emergere una decisione, aggiorna il PRD o il decision log, non solo la chat.
Prima di lasciare un agente in esecuzione senza supervisione, Anthropic suggerisce cinque domande: sa che aspetto ha «finito», può controllare il proprio lavoro, che cosa può toccare, che cosa lo ferma e chi approva il risultato? Le sezioni 3, 7 e 8 del template rispondono a quattro di queste.
Quando usare invece Spec Kit o Kiro?
Usa un workflow di spec strutturato quando vuoi l'intera pipeline, non solo un passaggio di consegne migliore. Spec Kit di GitHub, con circa 150k stelle, separa la spec («che cosa costruire e perché») dal piano tecnico, poi genera task e implementazione (GitHub, Spec Kit). Kiro divide ogni spec in requirements.md, design.md e tasks.md (Kiro docs). Il template qui sopra corrisponde al passaggio dei requisiti: le sezioni da 1 a 4 e la 7. Se il tuo team usa già uno di questi strumenti, incolla le sezioni di prodotto nel suo passaggio di spec invece di mantenere due documenti.
Quanto deve essere lungo un PRD per un agente di coding AI?
Proporzionale al rischio della modifica. Questi intervalli sono una regola pratica, non un benchmark:
Modifica
Che cosa includere
Lunghezza indicativa
Correzione di testo o piccolo ritocco reversibile della UI
Problema, ambito, 1-2 controlli
5-15 righe
Fetta di funzionalità standard
Sezioni 1-5, 7 e 8
Circa una pagina
Permessi, billing, dati personali o affermazioni generate dall'AI
Template completo con la sezione 6, un controllo di sicurezza e un revisore con nome
Fino a due pagine, più link
Il limite superiore segue la stessa logica che i fornitori applicano ai file di istruzioni. Ogni riga compete per l'attenzione del modello, quindi un PRD di cinque pagine nasconde l'unico vincolo che contava. Se una sezione supera mezza pagina, probabilmente contiene più decisioni; dividila o linka. Per un PRD di una release intera scritto per le persone, vedi come scrivere un PRD.
Errori comuni nei PRD per agenti di coding AI
Incollare l'intera wiki di prodotto. Più contesto non è contesto migliore. Linka le due o tre fonti che cambiano la decisione.
Mettere i dettagli della funzionalità in CLAUDE.md o AGENTS.md. Questi file vengono caricati a ogni compito. Il prompt di onboarding di GitHub esclude esplicitamente i contenuti specifici di un compito dal file di istruzioni di Copilot.
Requisiti come «rendi accurata l'AI». Indica che cosa l'utente può ispezionare e che cosa fa il sistema quando non riesce a soddisfare il requisito.
Inventare un obiettivo. Se non c'è una baseline, scrivi «sconosciuta» e prima strumenta.
Accettare «fatto» senza output. Chiedi i comandi e i loro risultati.
Lasciare che l'agente scriva e approvi il proprio PRD. Un agente può abbozzarne uno, ma una persona deve confermare problema, evidenze e ambito.
Scrivere le regole rigide come prosa. «Non toccare mai le migrazioni» appartiene anche a una regola di divieto o a un hook, oltre che al PRD.
Dove si inserisce Specky
Specky redige i PRD nel suo editor di PRD con citazioni inline alle chiamate con i clienti, ai ticket e ai feedback nel tuo Product Graph, così la sezione Evidenze rimanda a fonti reali. Il suo server MCP permette a Claude Code, Cursor e ad altri client MCP di caricare direttamente quel brief: get_coding_brief restituisce i PRD, le decisioni e le evidenze rilevanti per un ticket, e tutto ciò che un agente scrive di ritorno arriva come bozza per la revisione umana. La configurazione è nella pagina di setup MCP per agenti AI.
Domande frequenti
Un PRD per un agente di coding AI è diverso da un PRD normale?
Le domande sono le stesse: chi ha il problema, che cosa deve cambiare e come saprai che ha funzionato. La versione per agenti è più corta, limitata a un compito e più esplicita su non-obiettivi, regole di stop e controlli che l'agente può eseguire, perché un agente agisce sull'ambiguità invece di chiedere. Mantieni il brief proporzionato alla dimensione e al rischio della modifica.
Quanto deve essere lungo un PRD per Claude Code o Cursor?
Circa una pagina per una fetta di funzionalità standard, e fino a due pagine per modifiche che toccano permessi, billing, dati personali o affermazioni generate dall'AI. Linka per i dettagli. I fornitori danno limiti simili per i file di istruzioni: meno di 200 righe per CLAUDE.md, meno di 500 righe per regola di Cursor e non più di 2 pagine nel prompt di onboarding di GitHub.
Il PRD va in CLAUDE.md o AGENTS.md?
No. CLAUDE.md e AGENTS.md vengono caricati in ogni sessione, quindi devono contenere le regole durature del progetto come comandi, convenzioni e vincoli di sicurezza. Metti il PRD della funzionalità in un file a parte o nell'issue e fai riferimento ad esso per quel compito. Un link a dove vivono le decisioni di prodotto è la giusta quantità di contesto di prodotto per il file di istruzioni.
L'agente di coding può scrivere il PRD da solo?
Può abbozzarne uno, organizzare i tuoi appunti e suggerire casi limite. Claude Code può persino intervistarti e scrivere un file di spec. Una persona deve comunque confermare il problema dell'utente, le evidenze, l'ambito e il segnale di successo, perché il testo generato non è la prova che il team abbia preso quelle decisioni. Tratta un PRD abbozzato da un agente come una bozza.
Che cos'è lo spec-driven development?
Lo spec-driven development significa scrivere una specifica di che cosa costruire e perché prima che un agente AI pianifichi e implementi. Spec Kit di GitHub e Kiro lo formalizzano entrambi in fasi: requisiti o spec, poi piano tecnico o design, poi task, poi codice. Il template di PRD di questo articolo copre la fase dei requisiti.
Come scrivo criteri di accettazione per un agente di coding AI?
Scrivi ciascuno come un'affermazione pass/fail legata a qualcosa che l'agente può eseguire o osservare: un test, una build, un linter, un diff di fixture o uno screenshot. Usa la sintassi Given/When/Then o EARS, includi almeno un caso «se qualcosa va storto, allora» e chiedi all'agente di incollare comandi e output.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing