Files

T

2026-10-26 00:25:18 +01:00

8.3 KiB

Raw Blame History

Scrivere la documentazione spec-driven — STS Lab Srl

Guida per creare la documentazione quando il progetto non ce l'ha, completarla quando è solo uno scheletro, o aggiungere una spec a un progetto che già la usa.

S = python ~/.claude/skills/sts-spec-driven/scripts/spec_index.py (da PowerShell: python $HOME\.claude\skills\sts-spec-driven\scripts\spec_index.py)

0. Scegliere il layout — lo decide l'utente

Chiedi sempre con AskUserQuestion, prima di creare file. Proponi come primo, con «(Consigliato)», il layout che si adatta al progetto:

Layout	Quando consigliarlo	Cosa crea
Strutturato	più moduli o servizi, integrazioni con altri sistemi, riscrittura di un sistema esistente, più persone al lavoro, committente esterno, requisiti contrattuali	`00-INDEX` + `01-product … 08-project`, 29 documenti, spec in `03-specs/SPEC-nnn-*.md`
Piatto	progetto piccolo o prototipo, un solo modulo, un solo sviluppatore, tempi brevi	8 documenti nella stessa cartella, una spec per modulo `<NOME>_MODULE.md`

Chiedi nella stessa domanda (o subito dopo) dove creare la cartella: default docs/ nella radice del repository (decisione D-003 dei modelli). Se esiste già una cartella con documenti sparsi, non sovrascriverla: proponi di crearci dentro lo scheletro e di spostare i contenuti esistenti nei documenti giusti.

1. Creare lo scheletro

S scaffold <repo>/docs --layout strutturato --progetto "Nome Progetto"
S scaffold <repo>/docs --layout piatto      --progetto "Nome Progetto"

Lo script non sovrascrive mai un file esistente (li elenca come «già esistenti»). I documenti nascono con segnaposto  che spiegano cosa scrivere, e con le decisioni iniziali già pronte: D-001 stack (Proposta), D-002 metodo spec-driven, D-003 documentazione nel repository.

2. Raccogliere le informazioni

2.1 Prima guarda, poi chiedi

Prima di fare domande leggi ciò che esiste: README, CLAUDE.md, manifest delle dipendenze (package.json, pyproject.toml, composer.json, …), docker-compose, cartelle di codice, documenti del committente forniti dall'utente. Non chiedere ciò che puoi ricavare.

2.2 Intervista — al massimo 4 domande per giro, solo ciò che manca

Tema	Domande
Problema	Chi usa il prodotto? Cosa fa oggi senza? Quanto costa il problema (tempo, errori)?
Perimetro	Cosa deve esserci nel primo rilascio? Cosa è esplicitamente fuori?
Vincoli	Stack imposto? Sistemi esistenti da integrare o da sostituire? Scadenze?
Utenti	Quali ruoli? Chi può fare cosa? Multi-azienda (tenant)?
Dati	Quali dati personali o sensibili? Per quanto si conservano?
Esercizio	Dove gira (cloud, on-premise, Kubernetes)? Quali ambienti?
Successo	Come si misura che il progetto ha funzionato?

Le risposte vanno nei documenti, non solo nella conversazione.

2.3 Progetto con codice ma senza documentazione

Ricostruisci dal codice, come è stato fatto in KadeonCad_v2:

ogni comportamento osservato diventa un REQ di tipo P (parità) con Origine file:funzione; il codice è la fonte di verità, non i commenti;
ogni difetto visto leggendo diventa un DIF-nn + un REQ di tipo C;
ogni scelta tecnica già fatta diventa una D-xxx Accettata con la data di oggi e «ricostruita dal codice» nel contesto;
le spec delle parti già scritte nascono comunque da approvare: l'utente conferma che il comportamento attuale è quello voluto.

3. Ordine di scrittura

Ogni step termina con un riepilogo all'utente e la sua conferma prima del successivo. A fine step aggiorna lo stato nella tabella degli step di 00-INDEX (⬜ → 🟡 → ✅).

Layout strutturato

Step	Documenti	Esce quando
0	`00-INDEX` (cos'è, obiettivi, struttura del repo), `D-001` stack, `PROJECT_MEMORY` §1	l'utente conferma obiettivi e stack
1	`VISION` → `GLOSSARY` → `PERSONAS_CASI_USO` → `REQUIREMENTS` → `ARCHITECTURE`, `C4_MODEL`, `DOMAIN_WORKFLOW`, `DATA_MODEL`, `SECURITY`	requisiti rivisti dall'utente
2	una `SPEC` per capability (`S new-spec`)	ogni REQ è coperto da almeno una spec
3	`openapi.yaml` + `API.md`, `DATABASE.md`, `SEED_BOOTSTRAP.md`	ogni rotta delle spec è nel contratto
4	`06-devops/*`	ambienti e pipeline descritti
5	`TEST_STRATEGY`, `ACCEPTANCE_CRITERIA`, `TRACEABILITY`, `ROADMAP`, `TODO`	`S check` senza ID orfani né requisiti scoperti

Per un progetto piccolo in layout strutturato gli step 4 e parte del 5 possono restare ⬜ con una riga «rimandato a …» nell'indice: meglio dichiarato vuoto che riempito di generico.

Layout piatto

PROJECT_MEMORY §1–2 e ARCHITECTURE.
DECISIONS (D-001 stack).
Primo documento di modulo: S new-spec <docs> --titolo "…" --prefisso X.
API.md, DATABASE.md per ciò che il modulo tocca.
TODO con la lettera del modulo e i suoi task.

4. Regole di qualità

Requisiti

Un comportamento per riga, osservabile e verificabile; «il sistema …».
Numeri espliciti al posto di aggettivi («entro 5 s», «≥ 200 pezzi», non «veloce», «grande»).
Niente soluzioni tecniche nel requisito (quelle vanno nella spec o in una D-xxx).
Ogni requisito ha Tipo (P/C/N) e Origine. Aree di 2–5 lettere maiuscole (AUT, ING, NFR).

Specifiche

Forma normativa: «il sistema rifiuta…», «non ricalcola…». I «non» in grassetto.
Algoritmi in pseudocodice; combinazioni di casi in tabella.
Contratto API con la tabella degli esiti e i codici HTTP; poi subito in openapi.yaml.
Criteri di accettazione binari, nella forma «Dato …, quando …, allora …»; ogni requisito coperto ha almeno un criterio; i casi limite (valore 199/200, assente, altro tenant) sono criteri a sé.
Task piccoli (indicativamente ≤ 1 giorno), con dipendenze; l'ultimo è sempre «Test di accettazione 1–n».
Numerazione: SPEC-nnn → task T-nnn0…T-nnn9, criteri con la lettera della spec (SPEC-001 → A, SPEC-002 → B, …). Usa S next-id per non sbagliare.
Documento di modulo (layout piatto): la sezione «Domande ancora aperte» deve essere vuota o «nessuna» prima dell'approvazione.

Decisioni

Alternative reali valutate, con il motivo dello scarto.
Conseguenze comprese quelle negative (costi, limiti accettati).

Sempre

Non inventare. Ciò che non sai resta DA COMPILARE o diventa una domanda all'utente; mai numeri, nomi di sistemi o vincoli plausibili ma non confermati.
Mai approvare da solo. Le spec nascono «da approvare»; diventano «Approvata» solo dopo un sì esplicito dell'utente (§5).
Italiano, frasi brevi, niente linguaggio promozionale. Gli stessi termini del GLOSSARY.
Nessun segreto nei documenti: solo il nome della variabile che lo contiene.

5. Approvare una spec (solo su richiesta dell'utente)

Riga di stato: Stato: **Approvata** · Versione 1.0 · AAAA-MM-GG.
00-INDEX §03: riga della spec con numero di criteri, blocco di task, stato ✅.
TODO: i task della spec nella fase giusta, stato ⬜.
TRACEABILITY: una riga per requisito coperto (REQ → SPEC §n → T → criteri → ⬜).
DEVELOPMENT_LOG: voce breve con cosa è stato deciso approvando.
S check <docs>.

Una spec approvata si modifica solo con una nuova D-xxx o con una revisione tracciata (versione 1.1, sezione §n.bis).

6. Aggiungere una spec a un progetto che già esiste

S next-id <docs> SPEC                       # numero libero
S new-spec <docs> --titolo "Portale cliente" # crea SPEC-nnn-portale-cliente.md, da approvare
S next-id <docs> REQ --area POR              # se servono requisiti nuovi
S next-id <docs> D                           # se la spec nasce da una decisione

Poi: requisiti nuovi in REQUIREMENTS (tipo N, origine D-xxx), riga nella mappa di 00-INDEX, riquadro «novità» in testa all'indice, e la procedura del §5 quando l'utente approva.

7. Verifica finale

S check <docs>

Prima di consegnare: nessun ID orfano, nessun requisito scoperto, nessun task delle spec assente dal TODO. I segnaposto «DA COMPILARE» rimasti devono corrispondere solo a parti dichiarate rimandate. Riporta all'utente l'esito del controllo, non solo «fatto».

_{STS Lab Srl · Spec-Driven Reader}

8.3 KiB Raw Blame History Unescape Escape