182 lines
8.3 KiB
Markdown
182 lines
8.3 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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 `<!-- DA COMPILARE: … -->` 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 <docs> --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 <lettera>1–<lettera>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 <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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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».
|
||
|
||
<sub>STS Lab Srl · Spec-Driven Reader</sub>
|