Modello di PRD in Markdown per programmare con l’IA

Un documento dei requisiti di prodotto (PRD, product requirements document) è la prosa che enuncia il problema e l’ambito prima che il lavoro sia spezzato in attività. Una specifica di funzionalità è il file di SpecScore per una capacità del prodotto: che cosa fa, perché esiste e come si comporta. Markdown è il formato in testo semplice di quel file. Lo sviluppo guidato dalle specifiche (SDD, spec-driven development) è la pratica di scrivere la specifica prima del codice e di trattare la specifica come fonte di verità. In SpecScore, un requisito (REQ) è una regola con nome dentro una funzionalità. Un criterio di accettazione (AC, acceptance criterion) è una condizione astratta facoltativa che punta a una o più di quelle regole. Uno scenario è un esempio concreto, scritto come passi Given, When e Then. Un piano è il documento che spezza la funzionalità in attività. Un’attività è un’unità di lavoro che una persona o un agente può terminare. L’integrazione continua (CI, continuous integration) è un controllo automatico su ogni modifica proposta. Il controllo è un comando dell’interfaccia a riga di comando (CLI, command-line interface), specscore spec lint, della CLI in specscore/specscore-cli. Easy Approach to Requirements Syntax (EARS) è un modello di frase che un requisito può usare. Claude Code è l’agente di programmazione con IA per cui è scritto il plugin CLI Skills di questo sito. Questo modello di specifica di funzionalità è quel file di funzionalità, più il piano e l’attività che rimandano a esso.

Ultimo aggiornamento: 5 novembre 2026

Che cos’è questo modello di specifica di funzionalità

Un PRD è spesso un file di prosa che una persona legge. SpecScore tiene lo stesso incarico in file che un linter può controllare. La specifica di funzionalità chiama funzionalità l’unità atomica della specifica di prodotto: una directory sotto spec/features/ il cui README.md è l’unica fonte di verità di ciò che fa la funzionalità. La specifica di piano chiama piano il documento che scompone quella funzionalità in attività. Uno scenario, nella specifica di scenario, è un file concreto Given/When/Then nella directory _tests/ della funzionalità. La specifica dei criteri di accettazione tiene il criterio astratto: dice che cosa deve essere vero, e lo scenario dice come provarlo.

Il file checkout sotto è il modello compilato. Insieme all’indice delle funzionalità, a un README della specifica e a specscore.yaml, specscore spec lint lo ha accettato con 0 violazioni. Quel controllo è stato eseguito il 2 novembre 2026 con specscore 0.55.1 e con 0.39.1, il tag che dogfood.yml installa. La riga della barra degli strumenti Studio nel file di funzionalità è la riga che portano i README di funzionalità in specscore/specscore. La tabella delle sezioni obbligatorie nella specifica di funzionalità non la elenca.

Il README della funzionalità

La tabella delle sezioni obbligatorie nella specifica di funzionalità dice che ogni README di funzionalità ha un titolo # Feature: {Title}, una riga **Status:** subito dopo il titolo, un Summary, un Problem, una sezione Behavior, una sezione Acceptance Criteria, una sezione Open Questions e un piè di aderenza. Il valore di stato è uno tra Draft, In Review, Approved, Implementing, Stable, Amending, Rejected o Deprecated. Una sezione Contents è obbligatoria solo quando la funzionalità ha directory figlie. **Source Ideas:** è facoltativo. Il file controllato lo imposta su —.

Open Questions non si omette mai. Quando non ce n’è nessuna, la sezione dice None at this time. Anche Acceptance Criteria non si omette mai. Quando non sono definiti criteri, quella sezione dice Not defined yet. e Open Questions deve allora includere Acceptance criteria not yet defined for this feature. Il piè è l’ultima riga, e il suo URL è https://specscore.md/feature-specification.

La convenzione di frontmatter degli artefatti dice che ogni artefatto porta una chiave format: nel frontmatter YAML, e che un artefatto con stato porta anche status:, a specchio del token **Status:** nel corpo. La stessa funzionalità dice che le regole di lint che lo impongono escono dopo un periodo di grazia. Il file controllato include entrambe le chiavi. Questa pagina non afferma che il pin v0.39.1 rifiuti un file che le omette.

README di funzionalità che specscore spec lint ha accettato (2 novembre 2026)

---
format: https://specscore.md/feature-specification
status: Draft
---

# Feature: Checkout validation

> [SpecScore.**Studio**](https://specscore.studio): | [Explore](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=explore) | [Edit](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=edit) | [Ask question](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=ask) | [Request change](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=request-change) |

**Status:** Draft
**Source Ideas:** —

## Summary

The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address.

## Problem

A vague sentence such as "the form should handle bad input" does not say which event causes which response. Checkout needs those obligations written so a reviewer and a linter can point at them.

## Behavior

### Field validation

The checkout system checks the form when the shopper submits it.

#### REQ: show-field-error

When a shopper submits the checkout form with invalid data, the checkout system MUST show a validation error next to the invalid field.

#### REQ: reject-invalid-email

If the submitted email is not a valid address, then the checkout system MUST reject the form.

## Acceptance Criteria

### AC: invalid-submission

**Requirements:** checkout#req:show-field-error, checkout#req:reject-invalid-email

Submitting the checkout form with invalid data shows a validation error next to the invalid field, and an email that is not a valid address is rejected.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/feature-specification*

Indice delle funzionalità della stessa esecuzione di lint

---
format: https://specscore.md/features-index-specification
---

# Features

| Feature | Status | Description |
|---|---|---|
| [Checkout validation](checkout/README.md) | Draft | The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address. |

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/features-index-specification*

README della specifica della stessa esecuzione di lint

# Checkout specification

## Open Questions

None at this time.

specscore.yaml della stessa esecuzione di lint

# SpecScore Repo Config Schema: https://specscore.md/repo-config

project:
  title: Checkout sample
  host: github.com
  org: example
  repo: checkout

L’identificatore della funzionalità è il percorso della sua directory relativo a spec/features/. Il link dell’indice checkout/README.md significa che il file sta in spec/features/checkout/README.md, quindi l’id di funzionalità usato da requisiti e criteri è checkout. L’indice elenca ogni funzionalità di primo livello. Una directory figlia che non è elencata è una violazione di index-entries, che descrive fare il lint delle specifiche in CI. Il README della specifica in quell’albero ha una sezione, Open Questions, e dice None at this time. Il file di configurazione è ciò che la CLI cerca risalendo. Senza specscore.yaml il comando esce con 3 e nomina specscore init.

Identificatori REQ, criteri di accettazione e scenari

La specifica dei requisiti mette ogni regola sotto un titolo di argomento dentro ## Behavior. Il titolo è #### REQ: {slug}, con uno spazio dopo i due punti. Lo slug usa lettere minuscole, numeri e trattini. L’id canonico è {feature-path}#req:{slug}. Nel file checkout è checkout#req:show-field-error e checkout#req:reject-invalid-email. Un requisito enuncia un solo obbligo. La specifica dice che i requisiti SHOULD usare le parole chiave di RFC 2119: MUST, MUST NOT, SHOULD, SHOULD NOT e MAY. Un titolo REQ: non è valido fuori da ## Behavior. Una frase EARS può essere quella prosa. Il linter non valuta l’inglese. I modelli sono nella sintassi dei requisiti EARS.

Criterio di accettazione

La specifica dei criteri di accettazione dice che ogni criterio è un titolo ### AC: {slug} dentro ## Acceptance Criteria, poi una riga **Requirements:** che elenca valori {feature-id}#req:{slug}, poi un enunciato astratto di che cosa deve essere vero. I criteri sono facoltativi. La specifica dice di aggiungerne uno quando raggruppare due o più requisiti correlati aggiunge chiarezza. Il file checkout raggruppa entrambe le regole in checkout#ac:invalid-submission. L’enunciato non contiene Given, When o Then. Come scrivere criteri di accettazione è la guida di scrittura. La regola ac-heading-format (ac_heading.go al tag v0.55.1 della CLI) controlla che il titolo sia ### AC: <id> con un id in kebab-case. L’articolo sul lint registra che questa regola non richiede la riga **Requirements:** e non valuta le parole. La specifica dei criteri di accettazione richiede comunque quella riga.

Scenario

La specifica di scenario mette uno scenario in _tests/, che non è una sotto-funzionalità ed è escluso dall’indice delle funzionalità. Il file inizia con # Scenario: {Title}, una riga **Validates:** che punta a un requisito o a un criterio, e una sezione ## Steps le cui parole chiave sono in maiuscolo: GIVEN, WHEN, THEN e AND. Ogni directory _tests/ deve contenere un README con un indice degli scenari. Il campione sotto ha quella forma di file. Non faceva parte dell’esecuzione di lint del 2 novembre. specscore spec lint non controlla le parole chiave dei passi dello scenario. specscore rehearse esegue i file di scenario. Rehearse è quell’esecutore. Il workflow dogfood esegue il linter e non chiama rehearse.

Forma del file di scenario secondo la specifica di scenario

# Scenario: Reject an invalid email

**Validates:** [checkout#ac:invalid-email-rejected](../README.md#ac-invalid-email-rejected)

## Steps

GIVEN the shopper is on the checkout form
WHEN the shopper submits the email "not-an-email"
THEN the page shows "Enter a valid email address" beside the email field
AND the order is not placed

Leggi i tre strati in ordine. Il requisito dice la regola. Il criterio di accettazione dice che cosa deve essere vero per le regole che nomina. Lo scenario dà un flusso concreto. Un agente che vede solo la prosa del PRD deve inventare quella suddivisione. Il modello ce l’ha già.

Piani e attività

Un README di piano sta in spec/plans/{plan-slug}/README.md. La specifica di piano richiede il titolo # Plan: {Title} e i campi di intestazione Status, esattamente una riga di origine, Date, Owner e Supersedes. Un piano con origine in una funzionalità usa **Source Feature:** più lo slug della funzionalità, qui checkout. Le altre righe di origine ammesse sono **Source:** idea:{slug} e **Source:** none. Le sezioni obbligatorie sono Summary, Approach, Tasks e Open Questions. Dentro il piano, ogni attività è un titolo ### Task N: con una riga **Verifies:** della forma feature-slug#ac:ac-slug. La regola P-001 in plan_rules.go segnala un titolo di criterio di accettazione che nessuna attività copre e che non è elencato sotto ## Deferred AC Coverage. La regola P-002 segnala un valore **Verifies:** che non si risolve in uno di quei titoli. I piani con origine in un’idea e i piani con **Source:** none sono esenti da P-001.

Il piano sotto segue quella forma pubblicata per la funzionalità checkout, compreso il frontmatter format: e status:. Non era nell’esecuzione di lint del 2 novembre. Una funzionalità che un piano tocca deve includere una tabella ## Plans con le colonne Plan, Status, Author e Approved. Il file di funzionalità controllato non ha una sezione Plans, perché quell’albero non ha un piano.

La specifica di attività definisce anche un’attività come una propria directory e README.md sotto il piano. Il titolo è # Task: {Title}. I campi obbligatori sono **Status:**, **Depends on:** (il letterale none quando non c’è dipendenza) e **Model:** (small, medium, large o inherit). Una directory che contiene directory di attività figlie è un piano, non un’attività. Il file di attività sotto usa quei campi per la prima attività di checkout. Non era nell’esecuzione di lint del 2 novembre. L’URL del piè di un documento di attività è https://specscore.md/task-specification.

Forma di piano della specifica di piano, compilata per checkout

---
format: https://specscore.md/plan-specification
status: Draft
---

# Plan: Show checkout validation errors

**Status:** Draft
**Source Feature:** checkout
**Date:** 2026-11-05
**Owner:** @example
**Supersedes:** —

## Summary

This plan decomposes the checkout feature into the work that shows a field error and rejects an email that is not a valid address.

## Approach

Both tasks verify the same acceptance criterion, which bundles the two requirements. Nothing is deferred, so this plan has no Deferred AC Coverage section.

## Tasks

### Task 1: Show a validation error beside the invalid field

**Verifies:** checkout#ac:invalid-submission

When the shopper submits the checkout form with invalid data, show a validation error next to the invalid field.

### Task 2: Reject an email that is not a valid address

**Verifies:** checkout#ac:invalid-submission

If the submitted email is not a valid address, reject the form.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/plan-specification*

Forma del documento di attività secondo la specifica di attività

---
format: https://specscore.md/task-specification
status: queued
---

# Task: Show a validation error beside the invalid field

**Status:** queued
**Depends on:** none
**Model:** medium

## Acceptance Criteria

- Submitting the checkout form with invalid data shows a validation error next to the invalid field.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/task-specification*

Il file di funzionalità risponde a che cosa deve fare il modulo di checkout. Il piano risponde a come quel lavoro è suddiviso, e ogni attività in linea nomina il criterio che verifica. Il documento di attività è la foglia che una persona o un agente prende. Tieni stabile l’id del criterio. checkout#ac:invalid-submission è la stringa che usano la funzionalità e il piano.

Fare il lint del modello in CI

specscore spec lint valida l’albero della specifica rispetto a violazioni di convenzione strutturale. Un’esecuzione pulita stampa 0 violations found ed esce con 0. Un’esecuzione che trova violazioni stampa una riga per rilievo ed esce con 1. Quel codice di uscita fa fallire un job di CI. Gli argomenti non validi escono con 2. Uno specscore.yaml assente esce con 3. dogfood.yml installa la CLI con SPECSCORE_VERSION impostato su v0.39.1 e poi esegue specscore spec lint sulle pull request e sui push verso main. L’estratto del workflow, il rapporto di errore e il catalogo delle regole sono in fare il lint delle specifiche in CI.

La licenza del formato è CC BY 4.0 in specscore/specscore. La licenza della CLI è Apache-2.0 in specscore/specscore-cli.

Altri strumenti di sviluppo guidato dalle specifiche pubblicano controlli diversi. Le frasi sotto usano solo ciò che dicono le pagine di quei progetti. La rassegna degli strumenti registra le stesse pagine come lette il 30 ottobre 2026, tranne la home della documentazione di Spec Kit, che stampa il 28 settembre 2026.

OpenSpec documenta openspec validate nel suo riferimento di CLI. Quel comando controlla la struttura dei cambiamenti e delle specifiche di OpenSpec ed esce con un codice diverso da zero quando la validazione fallisce. Non controlla un titolo ### AC: di SpecScore né un indice SpecScore.

Il README di Task Master descrive la scomposizione di un PRD in attività con task-master parse-prd. Non descrive un linter per quel PRD. Un PRD può restare il testo che riscrivi nel file di funzionalità di questa pagina. specscore spec lint è ciò che poi controlla il file di funzionalità.

GitHub Spec Kit descrive un flusso di agente le cui fasi scrivono artefatti Markdown. Quella home della documentazione non descrive un comando che fa il lint di un README di funzionalità SpecScore in CI. Il confronto di quegli strumenti è la rassegna degli strumenti.

Un modello di specifica che Claude Code può leggere

I file sono Markdown, quindi un agente che può leggere un repository può leggere il modello. Claude Code è l’agente a cui punta la pagina CLI Skills. Quella pagina documenta ai-plugin-specscore, un plugin leggero di Claude Code che avvolge la CLI. Il repository del plugin è specscore/ai-plugin-specscore. La pagina dice che il plugin espone specscore spec lint, specscore feature, specscore task e specscore feature change-status come comandi del plugin. Le righe di installazione di quella pagina sono /plugin marketplace add specscore/ai-marketplace e /plugin install cli-skills@specscore.

La stessa pagina documenta specscore agent setup <agent-name> per claude, copilot, cursor, codex, antigravity.google, pi.dev oppure opencode, eseguito dentro un progetto gestito da SpecScore. SpecStudio Skills è il flusso guidato (/ideate, /specify, /plan, /implement) ed è anch’esso un plugin di Claude Code. Il modello di questa pagina è il file che quei comandi sottopongono a lint. Il plugin non sostituisce il README della funzionalità.

Domande frequenti

Che cos’è un modello di PRD in Markdown?

È un documento dei requisiti di prodotto scritto come file Markdown con una forma fissa. In SpecScore quella forma è un README di funzionalità: titolo, stato, riepilogo, problema, comportamento con regole #### REQ:, criteri di accettazione e domande aperte. Il file checkout di questa pagina è uno che specscore spec lint ha accettato.

Dove vanno gli identificatori REQ in un modello di specifica di funzionalità?

Sotto un titolo di argomento dentro ## Behavior, come #### REQ: {slug}. L’id è {feature-path}#req:{slug}. I criteri di accettazione elencano quegli id su **Requirements:**. Un’attività del piano elenca l’id del criterio su **Verifies:**.

Qual è la differenza tra un criterio di accettazione e uno scenario?

Un criterio di accettazione è una condizione astratta. Uno scenario è un flusso concreto Given/When/Then in _tests/. La specifica dei criteri di accettazione dice che il criterio non deve prescrivere i passi. Il file di scenario lo fa.

Il linter valuta la prosa del PRD?

No. specscore spec lint controlla la struttura: titoli, sezioni obbligatorie, righe dell’indice e riferimenti come P-001 e P-002. Non decide se il prodotto è una buona idea. Fare il lint delle specifiche in CI è il resoconto più lungo di quel comando.

Claude Code può usare questo modello di specifica?

Sì. Il modello è Markdown nel repository. Il plugin CLI Skills espone specscore spec lint e i comandi di funzionalità e di attività dentro Claude Code. specscore agent setup claude scrive un file di istruzioni per quell’agente. Il plugin non inventa un altro modello.

Un piano sostituisce la specifica di funzionalità?

No. Il README della funzionalità è la fonte dei requisiti e dei criteri di accettazione. Il piano scompone quella funzionalità in attività, e ogni attività rimanda con **Verifies:**. La specifica di piano e la specifica di attività sono i due documenti di quella suddivisione.

Fonti

La funzionalità checkout, l’indice delle funzionalità, il README della specifica e specscore.yaml sono stati accettati da specscore spec lint il 2 novembre 2026 con specscore 0.55.1 e con 0.39.1. I campioni di piano e di attività seguono le specifiche pubblicate e non facevano parte di quell’esecuzione. Le pagine dei concorrenti sono quelle collegate sotto; la rassegna degli strumenti le registra come lette il 30 ottobre 2026, tranne la home della documentazione di Spec Kit, che stampa il 28 settembre 2026.