# 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 `_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 ```bash S scaffold /docs --layout strutturato --progetto "Nome Progetto" S scaffold /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 1. `PROJECT_MEMORY` §1–2 e `ARCHITECTURE`. 2. `DECISIONS` (`D-001` stack). 3. Primo documento di modulo: `S new-spec --titolo "…" --prefisso X`. 4. `API.md`, `DATABASE.md` per ciò che il modulo tocca. 5. `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) 1. Riga di stato: `Stato: **Approvata** · Versione 1.0 · AAAA-MM-GG`. 2. `00-INDEX` §03: riga della spec con numero di criteri, blocco di task, stato ✅. 3. `TODO`: i task della spec nella fase giusta, stato ⬜. 4. `TRACEABILITY`: una riga per requisito coperto (REQ → SPEC §n → T → criteri → ⬜). 5. `DEVELOPMENT_LOG`: voce breve con cosa è stato deciso approvando. 6. `S check `. 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 ```bash S next-id SPEC # numero libero S new-spec --titolo "Portale cliente" # crea SPEC-nnn-portale-cliente.md, da approvare S next-id REQ --area POR # se servono requisiti nuovi S next-id 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 ```bash S check ``` 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