# La gestione delle specifiche: conservare, versionare e revisionare le specifiche come codice

Canonical: https://specscore.md/it/articles/spec-management/

Ultimo aggiornamento: 9 novembre 2026

La gestione delle specifiche è il modo in cui un team conserva una specifica software, registra ogni modifica, revisiona quella modifica e tiene la specifica aggiornata. La gestione della specifica è lo stesso lavoro: una specifica è il documento che dice che cosa il software deve fare, e gestirla è il modo in cui il documento resta reperibile e affidabile. Gestire le specifiche come codice significa che quei documenti sono file nel sistema di controllo di versione, così una modifica a una specifica è un commit di cui un revisore può leggere il diff. Il versionamento delle specifiche è la storia di quei commit, insieme allo stato scritto su ogni documento. Tenere le specifiche sincronizzate con il codice significa che una modifica proposta che rompe la struttura della specifica non supera lo stesso controllo automatico a cui passa la modifica del codice. Lo [sviluppo guidato dalle specifiche](https://specscore.md/it/spec-driven-development/) (SDD, spec-driven development) è la pratica di scrivere la specifica prima del codice e di trattare la specifica come fonte di verità. L’[integrazione continua](https://specscore.md/it/validators/) (CI, continuous integration) è un controllo automatico su ogni modifica proposta. Un documento dei requisiti di prodotto (PRD, product requirements document) è la prosa che enuncia il problema e l’ambito; il [modello di PRD in Markdown](https://specscore.md/it/articles/feature-spec-template/) è un file di funzionalità SpecScore di quella forma. [Easy Approach to Requirements Syntax](https://specscore.md/it/articles/ears-requirements/) (EARS) è un modello di frase per un requisito. In [SpecScore](https://specscore.md/), un requisito (REQ) è una regola con nome dentro una funzionalità, e un [criterio di accettazione](https://specscore.md/it/articles/acceptance-criteria/) (AC, acceptance criterion) è una condizione astratta facoltativa che punta a una o più di quelle regole. Il controllo è un comando dell’[interfaccia a riga di comando](https://specscore.md/it/cli/) (CLI, command-line interface), `specscore spec lint`, documentato in [fare il lint delle specifiche in CI](https://specscore.md/it/articles/lint-specs-in-ci/). Il formato sta nel repository pubblico [specscore/specscore](https://github.com/specscore/specscore) ([CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)). La CLI sta in [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)).

## Dove è conservata la specifica

La gestione delle specifiche comincia da un posto in cui i file possono stare. In questo repository la specifica è Markdown sotto `spec/`. Il [README di spec](https://github.com/specscore/specscore/blob/main/spec/README.md) elenca le directory: features, plans, ideas, decisions e lessons. Una funzionalità è una directory con un `README.md`. La [specifica di funzionalità](https://specscore.md/feature-specification) è il contratto di quel file, e il [modello di PRD](https://specscore.md/it/articles/feature-spec-template/) è un esempio compilato che un linter ha accettato.

`specscore spec lint` non indovina quale albero leggere. [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) al tag v0.55.1, e la stessa funzione al [tag v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go), risale dalla directory di lavoro fino a trovare `specscore.yaml`. Il commento di quella funzione dice che il comando esige il file, restituisce il codice di uscita 3 quando manca, e ti dice di eseguire `specscore init`. Il [workflow dogfood](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) di questo repository installa la CLI v0.39.1 e poi esegue `specscore spec lint`, quindi il checkout che linta ha quel file di configurazione.

Un indice sta accanto ai file di funzionalità. La regola `feature-index-row-sync` è un errore nel catalogo di lint di [v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md) e di [v0.55.1](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md). La riga del catalogo dice che esige che ogni riga dell’indice delle funzionalità corrisponda al suo file di funzionalità. Quello è l’indice che resta allineato con il documento a cui punta. Non è un confronto tra il testo del requisito e un file sorgente.

## Versionamento delle specifiche

Il versionamento delle specifiche, per i file committati in git, è la storia dei commit di quei file. SpecScore non aggiunge un secondo numero di versione su una funzionalità. La revisione che un revisore guarda è il commit sul branch. La riga di stato sul documento dice dove quella funzionalità si trova nel suo ciclo di vita, e questo è un fatto diverso dall’hash git.

La [specifica di funzionalità nel repository](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) è essa stessa `**Status:** Stable`. Esige una riga `**Status:**` subito dopo il titolo, e il valore deve essere uno di `Draft`, `In Review`, `Approved`, `Implementing`, `Stable`, `Amending`, `Rejected` o `Deprecated`. La regola `status-mirror`, in entrambi i cataloghi citati sopra, esige che lo `status:` nel frontmatter di un artefatto che ha uno stato coincida con quella riga del corpo, e vieta `status:` su un tipo che non ha stato. Far coincidere le due copie non è la stessa cosa che rifiutare una parola fuori dagli otto valori. Nessuna delle due righe del catalogo descrive una regola che rifiuta uno stato di funzionalità fuori da quell’insieme, quindi questa pagina non ne afferma una.

I piani usano un altro insieme. La regola `P-006`, in entrambi i cataloghi, esige che lo `**Status:**` nel corpo di un piano in un solo file sia uno di `Draft`, `In Review`, `Approved`, `Executing`, `Blocked`, `Implemented`, `Failed`, `Rejected`, `Withdrawn`, `Superseded` o `Deprecated`. La regola `idea-status-values` rifiuta uno stato di idea fuori dall’insieme che quella regola permette. Il catalogo è la lista. Questa pagina non ripete le parole delle idee.

La [specifica di piano](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md) descrive anche una tabella facoltativa `## Snapshots` con le colonne Date, Git Hash, Action e Comment. Dice che ogni istantanea riferisce un hash di commit git dello stato del piano in quel momento. I due cataloghi di lint controllati per questa pagina non nominano una regola che risolve quell’hash, quindi questa pagina non afferma che il linter controlli che il commit esista. L’hash è un puntatore che una persona può seguire in git. La [specifica di piano](https://specscore.md/plan-specification) pubblicata è la pagina di formato di quel documento.

## Revisionare una specifica

La revisione di una specifica in Markdown è la pull request che la cambia. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) viene eseguito su `pull_request` e su un push verso `main`. Il job fa il checkout del repository, installa la CLI con `SPECSCORE_VERSION` impostata su `v0.39.1`, ed esegue `specscore spec lint` senza flag aggiuntivi. GitHub Actions fa fallire il passo quando quel processo esce con un codice diverso da zero. I permessi del workflow sono `contents: read`.

Lo stato di funzionalità `In Review` significa che la funzionalità è presentata per la revisione. Scrivere quella parola è una modifica del file Markdown. La pull request è dove una persona legge il diff. `status-mirror` controlla che il frontmatter e il corpo nominino lo stesso stato. Non registra che un revisore sia stato d’accordo con la prosa. La [pagina dei validatori](https://specscore.md/it/validators/) separa quel controllo strutturale da una lettura che una persona deve ancora fare. Il resoconto regola per regola di ciò che segnala `specscore spec lint` è in [fare il lint delle specifiche in CI](https://specscore.md/it/articles/lint-specs-in-ci/).

## Tenere le specifiche sincronizzate con il codice

Tenere le specifiche sincronizzate con il codice, su questo sito, significa che la specifica è nel repository con il progetto, e che la CI fa fallire la pull request quando l’albero della specifica viola il formato. Una pull request può cambiare un file di funzionalità e il codice nello stesso diff. La regola `feature-index-row-sync` tiene una riga dell’indice allineata con il file di funzionalità che nomina. Non legge un file sorgente per decidere se il codice implementa il requisito.

L’estratto sotto riporta i passi di installazione e di lint di [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml). Il file del workflow imposta anche i permessi, un gruppo di concorrenza e un commento sul perché il pin non è `latest`. Quelle righe sono omesse qui. I comandi sono quelli che quel file esegue.

### Passi di installazione e di lint da dogfood.yml

```yaml
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint
```

Il commento in quel file dice che un pin mobile `latest` cambia la barriera sotto il repository: una pull request e il branch main a cui punta possono vedere regole diverse. Il pin è `v0.39.1`. Il job non passa `--fix`. Un’esecuzione pulita e una che fallisce, inclusa la riga `file:line [severity] rule: message`, sono mostrate in [fare il lint delle specifiche in CI](https://specscore.md/it/articles/lint-specs-in-ci/).

Una frase della specifica che non descrive più il codice non è uno di quei rilievi. `specscore spec lint` valida la struttura: file e sezioni obbligatori, righe di indice, forma delle intestazioni, e i riferimenti che le regole nominano. Non valuta se l’implementazione corrisponde al requisito. Quel limite è il senso della [pagina dei validatori](https://specscore.md/it/validators/). Tenere vera la prosa resta una revisione del diff.

## Come altri strumenti di sviluppo guidato dalle specifiche controllano una specifica

I paragrafi sotto usano le pagine recuperate il 9 novembre 2026. Descrivono i controlli propri di quegli strumenti. Non dicono quanti prodotti esistono, e non classificano un mercato. La [rassegna degli strumenti](https://specscore.md/it/spec-driven-development/tools/) è il confronto più lungo.

Il [riferimento di SDD agentico di GitHub Spec Kit](https://github.github.io/spec-kit/reference/agentic-sdd.html) descrive `/speckit.analyze` come un controllo in sola lettura su `spec.md`, `plan.md` e `tasks.md`. Segnala conflitti, lacune e ambiguità, non modifica mai i file, e lo esegui nell’agente prima dell’implementazione. L’elenco dei comandi di quella stessa pagina non descrive un job di CI che esegue `specscore spec lint` contro un albero SpecScore.

[OpenSpec](https://github.com/Fission-AI/OpenSpec) conserva una modifica come una directory direttamente sotto `openspec/changes/`. [openspec validate](https://openspec.dev/docs/cli) controlla modifiche e specifiche in cerca di problemi di struttura. Il riferimento dice che il codice di uscita 0 significa che ogni elemento validato è passato, e che il codice 1 significa che un elemento è fallito, che la richiesta di report non è valida, che la configurazione non si può leggere, o che l’esecuzione è fallita. Quel controllo è la forma di OpenSpec, inclusi i suoi blocchi di requisito e di scenario, non un titolo `### AC:` di SpecScore. Su un altro comando, `openspec status`, lo stesso riferimento dice che un lotto che non riesce a caricare una modifica esce comunque con 1, «so CI doesn’t accept an incomplete report as successful.». Questa frase riguarda `openspec status`, non `openspec validate`.

## Domande frequenti

### Che cos’è la gestione delle specifiche?

La gestione delle specifiche è conservare una specifica software, registrare ogni modifica, revisionare quella modifica e tenere la specifica aggiornata. In SpecScore i file sono Markdown nel repository git, e `specscore spec lint` è il controllo strutturale che un job di CI può far fallire.

### Che cos’è la gestione della specifica?

La gestione della specifica è la stessa pratica. La specifica è il documento che dice che cosa il software deve fare. Gestirla significa che il documento ha un posto noto, una storia, una revisione, e un controllo che la sua struttura corrisponde ancora al formato.

### Come funziona gestire le specifiche come codice?

La specifica è un albero di file Markdown sotto `spec/`, più `specscore.yaml` alla radice del repository. Una modifica è un commit. Una pull request revisiona il diff. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) esegue `specscore spec lint` su quella pull request.

### Come funziona il versionamento delle specifiche?

La storia di git è la storia di versione dei file. Una funzionalità porta anche `**Status:**` con uno degli otto valori che la specifica di funzionalità esige. Un piano può registrare una riga `## Snapshots` il cui Git Hash è un commit dello stato del piano. I cataloghi del linter citati qui non descrivono una regola che risolve quell’hash.

### Come tengo le specifiche sincronizzate con il codice?

Metti la specifica nel repository e fai fallire la pull request quando `specscore spec lint` segnala una violazione strutturale, inclusa una riga di indice che non corrisponde al suo file di funzionalità. Il comando non decide se il codice implementa il requisito. Una frase che si è allontanata dal codice ha ancora bisogno che una persona legga il diff.

## Fonti

File della CLI e cataloghi di lint letti il 9 novembre 2026 ai tag v0.39.1 di specscore-cli (la versione che dogfood.yml installa) e v0.55.1. I requisiti di funzionalità e di piano sono i file collegati sotto in specscore/specscore. Le pagine dei concorrenti sono state recuperate lo stesso giorno.

- [specscore/specscore — spec/README.md](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — valori di stato della funzionalità](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — snapshot del piano](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — licenza CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — licenza Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — catalogo delle regole di lint](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — catalogo delle regole di lint](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [Che cosa valida SpecScore](https://specscore.md/it/validators/)
- [Fare il lint delle specifiche in CI con un linter di specifiche](https://specscore.md/it/articles/lint-specs-in-ci/)
- [Sintassi dei requisiti EARS spiegata, con esempi](https://specscore.md/it/articles/ears-requirements/)
- [Come scrivere criteri di accettazione che un agente IA possa verificare](https://specscore.md/it/articles/acceptance-criteria/)
- [Modello di PRD in Markdown per programmare con l’IA](https://specscore.md/it/articles/feature-spec-template/)
- [Specifica di funzionalità](https://specscore.md/feature-specification)
- [Specifica di piano](https://specscore.md/plan-specification)
- [GitHub Spec Kit — riferimento di SDD agentico (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [Riferimento della CLI OpenSpec — openspec validate e openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [Strumenti di sviluppo guidato dalle specifiche](https://specscore.md/it/spec-driven-development/tools/)

## Correlati

- [Fare il lint delle specifiche in CI con un linter di specifiche](https://specscore.md/it/articles/lint-specs-in-ci/)
- [Modello di PRD in Markdown per programmare con l’IA](https://specscore.md/it/articles/feature-spec-template/)
- [Come scrivere criteri di accettazione che un agente IA possa verificare](https://specscore.md/it/articles/acceptance-criteria/)
- [Sintassi dei requisiti EARS spiegata, con esempi](https://specscore.md/it/articles/ears-requirements/)
- [Sviluppo guidato dalle specifiche](https://specscore.md/it/spec-driven-development/)
- [Strumenti di sviluppo guidato dalle specifiche](https://specscore.md/it/spec-driven-development/tools/)
- [Specifica di funzionalità](https://specscore.md/feature-specification)
- [Specifica di piano](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/it/cli/)
- [Che cosa valida SpecScore](https://specscore.md/it/validators/)
