# Ogni ambiguità nella tua specifica è un token che il tuo agente brucia.

Canonical: https://specscore.md/it/

SpecScore è un formato di file aperto e verificabile con un linter per le specifiche, scritto in Markdown e YAML (YAML Ain't Markup Language) — come JSON (JavaScript Object Notation) per i dati — con un'interfaccia a riga di comando (CLI) che i tuoi agenti invocano per interrogarle e modificarle, come `jq` per JSON.

Ultimo aggiornamento: 30 ottobre 2026

Poi una domanda di chiarimento a metà sviluppo. Poi una correzione dopo il rilascio. Poi il contesto che continui a rispiegare.

 Open source su GitHub Skill IA per il tuo agente Installa la CLI

## Un formato per le specifiche che già scrivi.

**SpecScore è un formato Markdown + YAML** per feature, requisiti e criteri di accettazione. Definisce una struttura che il tuo team e i tuoi agenti IA capiscono entrambi — ed è semplicemente composto da file nel tuo repository.

Un progetto SpecScore è formato da tre tipi di artefatti lungo un ciclo di vita: un'**Idea** cattura una direzione abbozzata; una specifica di **Feature** congela il comportamento concordato; un **Plan** scompone la feature in task ordinati, ciascuno dei quali cita i criteri di accettazione che soddisfa.

**Perché è importante per il tuo agente.** Poiché la struttura è leggibile dalla macchina, gli agenti IA possono interrogare la specifica tramite la CLI invece di leggere ogni singolo file. Chiedi *«su cosa dovrei lavorare adesso?»* e la CLI restituisce le Feature aperte e le domande irrisolte. La stessa forma che il tuo team revisiona; molto meno contesto che l'agente deve caricare.

 Feature → Requirements → Acceptance Criteria → Scenarios. idea → feature → plan ESEMPIO ideas/apply-discount.md

```
# Idea: Discount codes at checkout **Status:** approved **Promotes To:** features/checkout/apply-discount.md **Author:** cart-team ## Why Checkout drop-off is high at the payment step; users leave to search for coupons and never return. Let them paste codes directly in the cart before starting checkout. ## Success Criteria - Users enter promo codes without leaving the cart - Invalid codes fail fast with actionable copy - Stacking rules are clear (only one code per order) ## Outstanding Questions - What happens if a cart's subtotal drops below the code's minimum spend after applying? - Do we support percentage and flat discounts in v1?
```

 ESEMPIO features/checkout/apply-discount.md

```
--- title: Apply Discount Code at Checkout status: approved created: 2026-04-12 promoted_from: ideas/apply-discount.md --- # Context Shoppers with a valid coupon code want to apply it before payment so they can see the reduced total. # Requirements ## R1 — Code validation Accept coupon codes up to 16 alphanumeric characters. - AC-1: Given a valid code, when applied, then subtotal decreases by the code's value. - AC-2: Given an expired code, when applied, then show error "This code has expired". - AC-3: Given an empty input, the apply button remains disabled. ## R2 — Single-use enforcement Enforce one promo code per cart. Applying a second code replaces the first after confirmation. - AC-1: Given a cart with an active code, when a second code is applied, then prompt to replace. # Outstanding Questions None at this time.
```

 ESEMPIO plans/apply-discount/README.md

```
# Plan: Apply Discount **Status:** approved **Features:** - [apply-discount](../../features/apply-discount.md) **Author:** cart-team **Effort:** M **Impact:** high ## Context The apply-discount Feature is Approved. This plan breaks it into ordered tasks; each task cites the acceptance criteria it satisfies. ## Tasks ### T1 — Accept a `code` field on the cart Cites: R1.AC-1, R1.AC-2, R1.AC-3 ### T2 — Validate code time-window Cites: R2.AC-1, R2.AC-2 ### T3 — Apply percentage to subtotal, round down Cites: R3.AC-1, R3.AC-2 ### T4 — Higher-of tiebreak vs site-wide promo Cites: R3.AC-3 ### T5 — Confirmation toast on apply / replace Cites: R1.AC-2
```

## Le specifiche sono gerarchiche. Anche il tuo albero delle specifiche lo è.

Una lista piatta con cinquanta Feature diventa un disastro. SpecScore mantiene l'albero navigabile: i genitori governano l'ambito, i figli governano il dettaglio, e la struttura delle directory rispecchia la forma del prodotto su cui il tuo team già ragiona.

**Le domande aperte risalgono l'albero.** Le domande irrisolte a qualsiasi livello di profondità emergono nell'indice di ogni genitore. Vedi cosa blocca un rilascio dalla cima dell'albero, senza dover scavare per trovarlo.

La maggior parte degli strumenti per specifiche presuppone che un elenco piatto funzioni. Funziona — finché non funziona più. SpecScore è progettato per il momento in cui «dove vive questa Feature?» inizia a contare.

[Guardalo dal vivo in specscore-cli →](https://specscore.studio/app/github.com/specscore/specscore-cli/spec/features/cli?op=explore)

 DA specscore-cli/spec/features/cli/

```
spec/features/cli/ ├── agent/ │ └── setup/ ├── feature/ │ ├── change-status/ │ ├── deps/ │ ├── info/ │ ├── list/ │ ├── new/ │ ├── refs/ │ └── tree/ ├── idea/ │ ├── change-status/ │ ├── new/ │ └── relocate/ ├── spec/ │ └── lint/ │ ├── issue-rules/ ← sotto-sotto-Feature │ └── plan-rules/ ├── task/ │ ├── info/ │ ├── list/ │ └── new/ └── … altre 10 Feature di livello superiore
```

## Cosa si rompe quando non c'è.

- ### 🌀 Le specifiche si disallineano. La specifica nel documento, la discussione su Slack e il codice nella PR divergono silenziosamente per settimane. Nessuno sa quale versione della conversazione sia quella canonica. La soluzione Un'unica specifica canonica, nel repository, versionata insieme al codice. `specscore lint` viene eseguito in CI a ogni push; la cronologia Git è la traccia di audit. La specifica, la discussione e la PR non possono divergere in silenzio — condividono lo stesso file sotto revisione.
- ### 🌫️ I criteri di accettazione restano vaghi. *"Gestisce gli errori con eleganza"* doveva significare*"mostra un toast e fai il rollback."* O era*"registra nei log e riprova?"* L'agente deve tirare a indovinare. La soluzione Il linter individua i criteri ambigui prima ancora che venga scritta una riga di codice. Il verbo fallisce il lint perché privo di oggetto o condizione concreta. Correggere l'avviso ti costringe a specificare cosa significa davvero *"gestisce"*.
- ### 🤖 Gli agenti rilasciano la cosa sbagliata. Le persone deducono, chiedono, chiariscono. Gli agenti IA no — implementano il pattern più comune presente nei loro dati di addestramento. Il codice supera la revisione perché fa**qualcosa** di sensato. Solo che non è ciò che intendevi. La soluzione Input strutturato. Gli agenti IA analizzano gli ID di REQ, gli ID di AC e gli scenari`GIVEN / WHEN / THEN`in modo deterministico — non c'è nulla da dedurre. Ogni task del Plan deve citare gli ID degli AC che soddisfa, in modo che ciò che viene costruito sia sempre verificabile rispetto a quanto specificato.
- ### 🔁 Paghi due volte per una specifica ambigua. L'agente costruisce qualcosa a partire da un brief ambiguo, vedi che è sbagliato e glielo richiedi — in quattro modi diversi. Ogni funzione abbozzata e ogni tentativo vengono fatturati in token. Più la specifica è vaga, più round servono per azzeccarla. La soluzione Esegui il lint della specifica prima che l'agente entri in azione.`specscore lint` rifiuta fin dall'inizio i verbi vaghi e i criteri di accettazione mancanti, così l'agente implementa un brief concreto una volta sola anziché procedere a tentativi. L'esecuzione più economica è quella che non devi ripetere.
- ### 💸 Gli agenti pagano per rileggere le tue specifiche. Un agente IA che risponde a *"cosa dipende da questa feature?"* legge l'intero README della feature. Poi ogni indice genitore. Poi le feature correlate — per ogni chiarimento a metà sviluppo. Migliaia di token solo per orientarsi prima di scrivere codice. La soluzione Interrogazioni tramite CLI. `specscore feature deps` restituisce solo il grafico delle dipendenze; `specscore feature info` restituisce solo l'interfaccia. L'agente carica solo le righe necessarie per rispondere alla domanda, anziché inglobare interi file di testo nel proprio contesto.
- ### 🔗 Il codice dimentica la sua specifica. Sei mesi dopo, qualcuno refattorizza la funzione di sconto e si chiede perché esista quel branch a tre condizioni. Nessun commento la collega alla specifica; il ticket originale è perso in uno strumento di tracciamento chiuso. La soluzione Annotazioni nel codice sorgente. Commenti come`// specscore: features/checkout/apply-discount/R1.AC-2`rendono il collegamento leggibile dalla macchina e resistente a ogni refactoring.`specscore code deps` risponde a*"quale specifica implementa questo file?"* in una sola chiamata; il linter segnala i riferimenti che puntano a specifiche cancellate.
- ### 🏷️ I cambi di stato non si sincronizzano. Sposti una feature da *Draft* ad *Approved*nel suo README, ma il features-index genitore la elenca ancora come Draft. Tre settimane dopo, un agente che legge l'indice pensa che sia ancora provvisoria. Lo stato vive in due posti e sono in disaccordo. La soluzione `specscore feature change-status` riscrive il campo Status della feature e risincronizza la riga del features-index in un unico passaggio atomico — se il lint fallisce, la modifica viene annullata. Lo stato esiste in un unico punto canonico; l'indice è una vista generata di quello stato.
- ### 📋 Le specifiche dimenticano ciò che non sanno. Una specifica sembra definitiva — finché non ti ricordi che la domanda *"e come gestiamo i fusi orari?"* è andata persa in un thread di Slack due mesi fa e non è mai finita nel documento. Ora sei in fase di implementazione e nessuno sa quale fosse la risposta. La soluzione Ogni feature di SpecScore ha una sezione obbligatoria**Outstanding Questions**. Il linter rifiuta le feature che la omettono — lasciarla vuota va bene (`"None at this time."`), ma ometterla no. Le domande irrisolte sono visibili nel documento, interrogabili da CLI e impossibili da dimenticare.

## Il modo più semplice per iniziare: SpecStudio Skills per agenti IA.

[SpecStudio Skills](https://github.com/specscore/specstudio-skills)è un plugin per Claude Code che trasforma il ciclo di vita di SpecScore in quattro comandi slash. Lo installi una volta, poi li esegui in ordine — dall'idea grezza al piano eseguibile.

```
> /plugin marketplace add specscore/ai-marketplace > /plugin install specstudio@specscore
```

 Claude Code completamento automatico

```
> /specstudio: /specstudio:ideate Perfeziona un'idea grezza in una SpecScore Idea /specstudio:specify Trasforma un'Idea approvata in una specifica di Feature /specstudio:plan Scomponi una Feature in un Plan di task /specstudio:implement Esegui il prossimo task in un Plan
```

 /ideate → /specify → /plan → /implement Claude Code /ideate

```
> /ideate Pensiamo a come dovrebbe apparire la schermata del carrello per il checkout.
```

 Claude Code /specify

```
> /specify Definiamo spec/ideas/checkout-basket.md
```

 Claude Code /plan

```
> /plan Implementa spec/features/checkout/basket/README.md
```

 Claude Code /implement

```
> /implement Esegui spec/plans/checkout-basket/README.md
```

Gratuito per qualsiasi uso, anche commerciale. Il codice sorgente del plugin è su[specscore/specstudio-skills](https://github.com/specscore/specstudio-skills) — licenza MIT.

## Verifica la tua specifica in due passaggi.

Un linter deterministico e veloce, poi una revisione IA più approfondita — eseguiti sulla specifica che hai appena visto. Due passaggi, due tipi di certezza.

### Esegui il linter.

 deterministico

```
$ specscore spec lint features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds features/apply-discount/refunds:0 [error] readme-exists: README.md not found 3 violations found (3 errors) # exit code 1
```

Stesso risultato a ogni esecuzione. Gratuito, veloce, viene eseguito a ogni commit.

### Revisiona e valuta con l'IA.

 non deterministico

```
> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
```

Legge per comprenderne il significato, come un revisore umano.

## Ecco cosa non rileverà.

Un linter che dichiara di rilevare tutto sta mentendo. SpecScore è un sistema a livelli — un linter deterministico, un revisore IA e il tuo giudizio — e ogni livello ha un limite reale. Li abbiamo messi tutti per iscritto: cosa individua il linter, cosa individua l'IA e cosa dipende ancora da te perché nessuno strumento può farlo per ora.

[Cosa il linter non rileverà →](/it/validators/#limits)

## Cosa c'è nella scatola.

### Il formato

Markdown + YAML. Funziona in qualsiasi editor di testo. Nessun nuovo strumento richiesto per iniziare a scrivere.

### Il linter

CLI in Go. Valida struttura, riferimenti e completezza. Restituisce un codice di uscita diverso da zero in caso di errore — funziona nel tuo terminale e nella tua CI.

## Usa gli strumenti che preferisci.

SpecScore è semplicemente un insieme di file nel tuo repository. Nessun SaaS a cui iscriversi. Nessun orchestratore richiesto. Usalo con Linear, Jira, GitHub Projects, semplice Markdown in una cartella o senza alcuno strumento di project management. Al formato e al linter non importa dove si trovino i tuoi ticket.

## Come si confronta SpecScore.

Lo sviluppo guidato dalle specifiche è un settore affollato. Ecco come si posiziona SpecScore rispetto alle alternative — in tutta onestà.

 Plain Markdown L'approccio predefinito. SpecScore è l'evoluzione del tuo Markdown. OpenSpec Un buon punto di partenza. SpecScore offre i guardrail. Spec Kit Spec Kit è il flusso di lavoro. SpecScore è l'artefatto. Datarim Datarim esegue la pipeline. SpecScore è ciò che lascia traccia. CodeSpeak CodeSpeak punta su un compilatore. SpecScore punta su un formato. Kiro Kiro scrive la spec nel suo IDE. SpecScore è il formato che la CI può sottoporre a lint. Tessl Tessl sostiene la spec come fonte. SpecScore fa il lint della spec accanto al codice. BMAD Method BMAD esegue il ciclo agile. SpecScore è l’artefatto che una pull request può controllare. Task Master AI Task Master divide un PRD in task. SpecScore è la spec che quei task possono citare.

[Vedi il confronto completo →](/it/vs/)

## Preferisci la CLI?

Non usi agenti IA o hai bisogno di validare le specifiche nella tua pipeline di CI? C'è una CLI per questo. Si installa in 60 secondi — nessun account, nessuna telemetria, funziona con qualsiasi cartella di specifiche Markdown.

 Linux / macOS Windows

```
$ curl -fsSL https://specscore.md/install/get-cli | sh
```

```
> irm https://specscore.md/install/get-cli.ps1 | iex
```

Esegui il lint della specifica di esempio inclusa con il binario:

```
$ specscore lint examples/checkout/apply-discount.md
```

Guarda l'output:

```
examples/checkout/apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
```

Leggi la [documentazione completa](/docs/) · [Contribuisci su GitHub](https://github.com/specscore/specscore)

## Costruito su SpecScore.

- ### DataTug Esplora schemi di database, crea ed esegui query e comprendi i risultati con DataTug. SpecScore guida i suoi requisiti e criteri di accettazione. [datatug.app →](https://datatug.app)[Gli strumenti alla base →](https://datatug.app/en/under-the-hood/tools-we-built/)
- ### MeaningGraph Registro aperto di modelli di dati e definizioni semantiche, mantenute nei propri repository Git e collegate a modelli e codice. [meaninggraph.io →](https://meaninggraph.io/)[Esplora il registro →](https://meaninggraph.io/registry/)
- ### Codegrapher Motore a grafo di codice per un'esplorazione rapida del codice e collegamento bidirezionale spec↔codice. [codegrapher.dev →](https://codegrapher.dev/)
- ### DALgo Livello di accesso ai dati in Go specificato con SpecScore. [dal-go.github.io →](https://dal-go.github.io/)
- ### inGitDB Database versionato basato su Git specificato con SpecScore. [ingitdb.com →](https://ingitdb.com/)
- ### Rehearse Livello di evidenza di accettazione — esegue realmente i criteri di accettazione di una specifica, con controlli riutilizzabili e senza codice collante. [rehearse.ink →](https://rehearse.ink)
- ### SpecScore Studio Interfaccia web per visualizzare e modificare le specifiche SpecScore. [specscore.studio →](https://specscore.studio)

## Hai domande?

Ecco le domande che ci vengono poste più spesso. Ciascuna rimanda alla risposta completa sulla [pagina delle FAQ](/it/faq/).

 Come si differenzia SpecScore da spec-kit?

spec-kit è una metodologia; SpecScore è un formato di archiviazione per le specifiche che scrivi, più una CLI. Si integrano a vicenda — un'estensione per spec-kit che scrive in formato SpecScore è già in lavorazione.

 Risposta completa → In cosa si differenziano le SpecStudio Skills da Superpowers e agent-skills?

Simili nello spirito — tutte e tre guidano gli agenti IA attraverso ideate → specify → plan → implement. SpecStudio Skills scrive gli artefatti nel formato SpecScore e usa la CLI `specscore` per interrogazioni e cambi di stato; gli altri leggono e modificano i file direttamente. Scegli SpecStudio quando il consumo di token fa la differenza.

 Risposta completa → Perché una CLI — non posso semplicemente installare le skill?

Le skill non possono, in modo affidabile, garantire l'integrità referenziale, restituire query filtrate senza leggere ogni singolo file, né aggiornare il campo di stato appropriato al momento giusto. La CLI compie ciascuna di queste operazioni in una sola chiamata. Le skill leggerebbero ogni file per fare la stessa cosa.

 Risposta completa → Perché "SpecScore" — cosa misura?

Due significati, entrambi voluti. Partitura — uno spartito strutturato di requisiti. E un voto di qualità letterale — il linter della CLI è il punteggio deterministico, e la skill`/score` è la valutazione A–F espressa dall'IA sulla maturità dell'artefatto.

 Risposta completa → Dove sono i dati sul risparmio di token?

Un confronto analitico affiancato e misurato è in preparazione prima del post su Habr. Strutturalmente: la CLI restituisce un piccolo elenco strutturato; un agente tradizionale senza CLI legge invece decine di documenti.

 Risposta completa → Con quale licenza è distribuito SpecScore?

La specifica e la documentazione nel repository pubblico [specscore/specscore](https://github.com/specscore/specscore) sono [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE). L'interfaccia a riga di comando (CLI) di riferimento in [specscore/specscore-cli](https://github.com/specscore/specscore-cli) è [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE).

 Risposta completa → SpecScore richiede un strumento di IA specifico?

No. Le specifiche sono file di testo nel repository. La CLI è un binario locale. Le AI Skills di questo sito avvolgono quella CLI per gli agenti che possono eseguire skill. Il formato non richiede un fornitore.

 Risposta completa → Che cos'è lo sviluppo guidato dalle specifiche (SDD)?

Lo sviluppo guidato dalle specifiche (SDD) significa scrivere una specifica verificabile — requisiti e criteri di accettazione — prima del codice, e poi controllare il risultato rispetto a quella specifica. SpecScore è un formato di file per quelle specifiche.

 Risposta completa →

## Definisci il successo. Poi fagli spazio.

SpecScore definisce quando il progetto è finito. Un impegno settimanale ti aiuta a scegliere il passo successivo. Collega i due con una breve verifica dei risultati.

 Scegli il prossimo risultato da completare → Scopri CommittedMe (in inglese) →