Il formato
Markdown + YAML. Funziona in qualsiasi editor di testo. Nessun nuovo strumento richiesto per iniziare a scrivere.
Ogni ambiguità nella tua specifica
è un token che il tuo agente brucia.
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.
Poi una domanda di chiarimento a metà sviluppo. Poi una correzione dopo il rilascio. Poi il contesto che continui a rispiegare.
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.
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.
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 superioreCosa 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 lintviene 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é faqualcosa 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 / THENin 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 lintrifiuta 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 depsrestituisce solo il grafico delle dipendenze;specscore feature inforestituisce 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-2rendono il collegamento leggibile dalla macchina e resistente a ogni refactoring.specscore code depsrisponde 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 Approvednel 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-statusriscrive 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 obbligatoriaOutstanding 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è 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 Codecompletamento 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
Gratuito per qualsiasi uso, anche commerciale. Il codice sorgente del plugin è suspecscore/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.
Cosa c'è nella scatola.
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 MarkdownL'approccio predefinito. SpecScore è l'evoluzione del tuo Markdown.OpenSpecUn buon punto di partenza. SpecScore offre i guardrail.Spec KitSpec Kit è il flusso di lavoro. SpecScore è l'artefatto.DatarimDatarim esegue la pipeline. SpecScore è ciò che lascia traccia.CodeSpeakCodeSpeak punta su un compilatore. SpecScore punta su un formato.KiroKiro scrive la spec nel suo IDE. SpecScore è il formato che la CI può sottoporre a lint.TesslTessl sostiene la spec come fonte. SpecScore fa il lint della spec accanto al codice.BMAD MethodBMAD esegue il ciclo agile. SpecScore è l’artefatto che una pull request può controllare.Task Master AITask Master divide un PRD in task. SpecScore è la spec che quei task possono citare.
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.
$ curl -fsSL https://specscore.md/install/get-cli | sh> irm https://specscore.md/install/get-cli.ps1 | iexEsegui il lint della specifica di esempio inclusa con il binario:
$ specscore lint examples/checkout/apply-discount.mdGuarda 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 1Costruito 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 Gli strumenti alla baseMeaningGraph
Registro aperto di modelli di dati e definizioni semantiche, mantenute nei propri repository Git e collegate a modelli e codice.
meaninggraph.io Esplora il registroCodegrapher
Motore a grafo di codice per un'esplorazione rapida del codice e collegamento bidirezionale spec↔codice.
codegrapher.devDALgo
Livello di accesso ai dati in Go specificato con SpecScore.
dal-go.github.ioinGitDB
Database versionato basato su Git specificato con SpecScore.
ingitdb.comRehearse
Livello di evidenza di accettazione — esegue realmente i criteri di accettazione di una specifica, con controlli riutilizzabili e senza codice collante.
rehearse.inkSpecScore Studio
Interfaccia web per visualizzare e modificare le specifiche SpecScore.
specscore.studio
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.