249 lines
14 KiB
Markdown
249 lines
14 KiB
Markdown
---
|
||
name: sts-spec-driven
|
||
description: "STS Lab Srl — Spec-Driven Reader. Legge e SCRIVE la documentazione spec-driven di un progetto (cartella docs/ con PROJECT_MEMORY, REQUIREMENTS REQ-*, specifiche SPEC-*, task T-*, decisioni D-*, difetti DIF-*, TRACEABILITY, TODO, DECISIONS, CHANGELOG, DEVELOPMENT_LOG). Lettura: trasforma la documentazione in un brief di implementazione prima del codice e chiude il ciclo dopo. Scrittura: se il progetto non ha documentazione la crea da zero facendo scegliere fra layout strutturato (00-INDEX + 01-product…08-project) e piatto, con modelli, intervista e controllo di coerenza; aggiunge nuove spec, requisiti e decisioni a una documentazione esistente. Usala all'inizio di ogni sessione di sviluppo, quando l'utente cita un ID (REQ-, SPEC-, T-, D-, DIF-), chiede di implementare una spec o un task, chiede «leggi la documentazione», «da dove riprendo», «che stato ha il progetto», «crea la documentazione», «imposta lo spec driven», «scrivi la spec di …», «nuovo progetto», o quando si inizia a sviluppare in un progetto senza docs/."
|
||
---
|
||
|
||
# Spec-Driven Reader — STS Lab Srl
|
||
|
||
> **STS Lab Srl** · Skill proprietaria per lo sviluppo software guidato da specifiche.
|
||
> © 2026 STS Lab Srl — tutti i diritti riservati.
|
||
|
||
Nei progetti STS Lab la documentazione **precede** il codice e ne è il contratto:
|
||
|
||
```
|
||
REQ-xxx cosa deve fare il prodotto (REQUIREMENTS)
|
||
▼
|
||
SPEC-xxx come lo fa: API, dati, regole, (03-specs/ o documenti di modulo)
|
||
│ errori, criteri di accettazione
|
||
▼
|
||
T-xxx unità di lavoro implementabile (TODO)
|
||
▼
|
||
codice + test
|
||
▼
|
||
TRACEABILITY chiude il cerchio: ogni REQ ha spec, task e test che passano
|
||
```
|
||
|
||
Ogni scelta strutturale è una decisione numerata `D-xxx`; ogni difetto noto è un `DIF-xx`.
|
||
Questa skill serve a **scrivere** quella catena quando manca, a **leggerla bene** prima di
|
||
toccare il codice, e a **richiuderla** dopo.
|
||
|
||
### Quale modalità
|
||
|
||
| Situazione | Modalità | Dove |
|
||
|---|---|---|
|
||
| Il progetto **non ha** documentazione spec-driven (o l'utente chiede di crearla) | **Scrittura** | §A qui sotto + [references/scrittura.md](references/scrittura.md) |
|
||
| C'è solo lo scheletro, con molti `DA COMPILARE` | **Scrittura** (completamento) | idem, dallo step in corso |
|
||
| Serve una spec, un requisito o una decisione **nuovi** | **Scrittura** (aggiunta) | [references/scrittura.md](references/scrittura.md) §6 |
|
||
| La documentazione c'è e si deve sviluppare | **Lettura** | §1–§8 |
|
||
|
||
---
|
||
|
||
## 0. Strumento: `scripts/spec_index.py`
|
||
|
||
Libreria standard Python 3.8+. Usalo **prima** di aprire i file grandi: DECISIONS e
|
||
DEVELOPMENT_LOG possono superare le 3–6 000 righe e non vanno mai letti interi.
|
||
|
||
```bash
|
||
S=~/.claude/skills/sts-spec-driven/scripts/spec_index.py
|
||
# lettura (non scrive nulla)
|
||
python $S overview <docs> # layout, documenti chiave, stato delle spec, segnaposto
|
||
python $S context <docs> SPEC-004 # definizione + ID collegati + TODO + TRACEABILITY
|
||
python $S find <docs> D-014 # dove è definito e chi lo cita
|
||
python $S check <docs> # coerenza: orfani, requisiti scoperti, derive di stato
|
||
python $S next-id <docs> SPEC|D|DIF|T|REQ [--area AUT] [--spec SPEC-004] [--prefisso W]
|
||
# scrittura (non sovrascrive mai un file esistente)
|
||
python $S scaffold <docs> --layout strutturato|piatto --progetto "Nome"
|
||
python $S new-spec <docs> --titolo "Titolo" [--prefisso W (solo layout piatto)]
|
||
```
|
||
|
||
Su Windows da PowerShell il `~` non viene espanso: usa `$HOME\.claude\skills\sts-spec-driven\scripts\spec_index.py`
|
||
(oppure lancialo dal tool Bash, dove `~` funziona).
|
||
|
||
- Per una SPEC, `context` stampa l'indice delle sezioni con i numeri di riga: leggi poi solo
|
||
le sezioni che servono con `Read offset/limit`.
|
||
- `check` esce con codice 1 se trova problemi; riporta all'utente cosa ha trovato.
|
||
|
||
Se Python non c'è, ripiega su `Grep` con il pattern
|
||
`REQ-[A-Z]+-\d+|SPEC-\d{3}|T-[A-Z]{0,2}\d+|D-\d{3}|DIF-\d+` e copia a mano i modelli da
|
||
`templates/`.
|
||
|
||
---
|
||
|
||
## A. Scrittura — creare la documentazione
|
||
|
||
Procedura completa in [references/scrittura.md](references/scrittura.md). In sintesi:
|
||
|
||
1. **Verifica** che non esista già (§1). Se esiste solo in parte, non ricrearla: completala.
|
||
2. **Fai scegliere il layout all'utente** con `AskUserQuestion`, mettendo per primo con
|
||
«(Consigliato)» quello adatto — *Strutturato* per progetti con più moduli, integrazioni,
|
||
riscritture, committente esterno; *Piatto* per progetti piccoli, prototipi, un solo modulo.
|
||
Chiedi anche dove crearla (default `docs/` alla radice del repository).
|
||
3. **Crea lo scheletro** con `scaffold`. I modelli stanno in `templates/strutturato/`,
|
||
`templates/piatto/`, `templates/spec.md`, `templates/modulo.md`.
|
||
4. **Raccogli le informazioni**: prima leggi README, manifest, codice; poi intervista l'utente
|
||
(al massimo 4 domande per giro, solo ciò che manca). Se c'è codice senza documenti,
|
||
ricostruisci i requisiti dal codice come tipo **P** con *Origine* `file:funzione`.
|
||
5. **Scrivi nell'ordine degli step** (visione → requisiti → architettura → spec → contratto e
|
||
dati → devops → qualità e backlog), con un riepilogo e la conferma dell'utente a fine step.
|
||
6. **Nuove spec** con `new-spec`: numerazione, blocco di task e lettera dei criteri sono
|
||
automatici. Nascono sempre «da approvare».
|
||
7. **Chiudi** con `check` e riporta l'esito.
|
||
|
||
Regole che non si derogano:
|
||
|
||
- **Non inventare**: ciò che non è noto resta `DA COMPILARE` o diventa una domanda.
|
||
- **Mai approvare da solo**: una spec diventa *Approvata* solo dopo un sì esplicito
|
||
dell'utente (procedura in scrittura.md §5).
|
||
- **Mai sovrascrivere** documenti esistenti; i contenuti sparsi si spostano nei documenti
|
||
giusti, con l'accordo dell'utente.
|
||
|
||
---
|
||
|
||
## 1. Trovare la documentazione
|
||
|
||
Cerca nell'ordine: `docs/`, `src/docs/`, `*/src/docs/`, `documentation/`. Una cartella è
|
||
spec-driven se contiene almeno `PROJECT_MEMORY.md` o `00-INDEX.md` più uno fra `DECISIONS.md`,
|
||
`TODO.md`, `REQUIREMENTS.md`. Leggi anche `CLAUDE.md`/`README.md` alla radice del repository:
|
||
possono indicare la cartella o regole locali.
|
||
|
||
**Se non la trovi**, non scrivere codice: di' all'utente che il progetto non ha documentazione
|
||
spec-driven e proponi di crearla (§A). Se l'utente preferisce procedere senza, rispetta la
|
||
scelta e annotala nella risposta.
|
||
|
||
Due layout ricorrenti (dettagli in [references/layout.md](references/layout.md)):
|
||
|
||
| Layout | Riconoscimento | Esempio |
|
||
|---|---|---|
|
||
| **Strutturato** | cartelle `01-product/ … 08-project/`, `00-INDEX.md`, `03-specs/SPEC-xxx-*.md` | `KadeonCad_v2/docs` |
|
||
| **Piatto** | tutti i `.md` in una cartella, specifiche come documenti di modulo (`CAD_MODULE.md`, `whatsapp/DESIGN.md`) | `Kadeon/kadeon/src/docs` |
|
||
|
||
---
|
||
|
||
## 2. Lettura di inizio sessione (sempre, prima del codice)
|
||
|
||
1. **`overview`** con lo script.
|
||
2. **`PROJECT_MEMORY.md`** — per intero. Contiene ciò che non è deducibile dal codice e che, se
|
||
dimenticato, fa ripetere errori: vincoli non negoziabili, azioni pendenti di sicurezza, «le
|
||
cose da non dimenticare mai». Tienile presenti per tutta la sessione.
|
||
3. **`00-INDEX.md`** (layout strutturato) — tabella degli step, stato dell'implementazione e i
|
||
riquadri `> **Titolo (data):**` in testa: sono le novità più recenti, in ordine inverso.
|
||
4. **Indice di `DECISIONS.md`** — solo la tabella iniziale; le singole decisioni si leggono
|
||
quando servono.
|
||
5. **`TODO.md`** — sezione «fuori sequenza / prima di tutto» e la fase corrente.
|
||
|
||
Non leggere CHANGELOG, DEVELOPMENT_LOG, openapi.yaml per intero: si interrogano per ID o data.
|
||
|
||
---
|
||
|
||
## 3. Prima di implementare: il cancello
|
||
|
||
Rispondi a queste domande **prima** di scrivere una riga. Se una risposta è «no», fermati e
|
||
dillo all'utente.
|
||
|
||
| # | Domanda | Dove si verifica | Se «no» |
|
||
|:-:|---|---|---|
|
||
| 1 | Il lavoro richiesto corrisponde a un `T-xxx`? | TODO, sezione *Task* della spec | Proponi il task e la spec di appartenenza |
|
||
| 2 | Il task appartiene a una `SPEC-xxx` in stato **Approvata**? | riga `Stato:` della spec, 00-INDEX | Non implementare: segnala lo stato (*da approvare*, 🟡) e chiedi |
|
||
| 3 | Le dipendenze del task (colonna *Dipende da*) sono ✅? | TODO, tabella task della spec | Segnala l'ordine corretto |
|
||
| 4 | Nessuna decisione `D-xxx` **accettata** lo vieta o lo vincola diversamente? | DECISIONS (per ID), PROJECT_MEMORY | Cita la decisione; una deviazione richiede una nuova `D-xxx` |
|
||
| 5 | Se tocca un requisito di **parità** (tipo `P`) cambia il comportamento? | REQUIREMENTS, colonna *Tipo* | È una decisione di prodotto: serve una `D-xxx` |
|
||
| 6 | Contratto API e schema dati sono già scritti? | `openapi.yaml` / API.md, DATABASE.md | Si scrive prima il contratto (contract-first) |
|
||
|
||
Eccezione legittima: richiesta esplicita dell'utente di procedere comunque. In quel caso
|
||
procedi, ma registra la deviazione (vedi §6) — è ciò che i progetti chiamano «inversione»
|
||
e che va lasciata scritta.
|
||
|
||
---
|
||
|
||
## 4. Leggere una spec
|
||
|
||
Struttura tipica di una `SPEC-xxx` (le sezioni possono variare):
|
||
|
||
1. Intestazione: `Stato`, versione, data, **requisiti coperti**, decisione di riferimento.
|
||
2. Contesto e obiettivo — il *perché*; spesso contiene un dato misurato che giustifica la scelta.
|
||
3. «Cosa cambia rispetto a ciò che è già scritto» — elenco dei punti fermi che la spec modifica.
|
||
4. Regole / algoritmo in **forma normativa**: le parole in grassetto e i «**non**» sono vincoli.
|
||
5. Contratto API: rotta, ingresso, uscita, **tabella degli esiti con codici HTTP**.
|
||
6. Errori.
|
||
7. **Criteri di accettazione** (`D1…D12`, `P1…P24`, …): ognuno diventa almeno un test.
|
||
8. **Task** con dipendenze.
|
||
|
||
Regole di lettura:
|
||
|
||
- Leggi la spec **intera** quando la implementi; usa l'indice di `context` per le altre.
|
||
- I paragrafi «è una decisione, non una dimenticanza» descrivono comportamenti voluti che
|
||
sembrano bug: non «correggerli».
|
||
- Sezioni con suffisso `bis`/`ter` (es. §5.3bis) sono aggiunte successive: leggile, spesso
|
||
modificano la regola base.
|
||
- Per ogni `REQ-` citato leggi la riga in REQUIREMENTS: colonna **Tipo** (P parità / C
|
||
correzione / N nuovo) e **Origine** (per i `P` la fonte di verità è il codice della versione
|
||
precedente indicato lì).
|
||
- Per ogni `D-` citata leggi **solo** la sezione `## D-xxx` (Contesto → Decisione →
|
||
Alternative → Conseguenze). Una decisione *Superata da D-yyy* non vale più: segui D-yyy.
|
||
- Il glossario (`GLOSSARY.md`) fissa i termini: usa gli stessi nomi nel codice e nei messaggi.
|
||
|
||
---
|
||
|
||
## 5. Il brief di implementazione
|
||
|
||
Prima di scrivere codice, presenta all'utente un brief compatto con il modello in
|
||
[references/brief-template.md](references/brief-template.md): obiettivo, stato della spec,
|
||
requisiti, regole normative, contratto, criteri di accettazione → test, task e dipendenze,
|
||
decisioni vincolanti, file di codice probabilmente toccati, **incoerenze trovate**.
|
||
|
||
Per un task piccolo il brief può stare in poche righe; non saltare mai le sezioni *criteri* e
|
||
*incoerenze*.
|
||
|
||
---
|
||
|
||
## 6. Dopo l'implementazione: chiudere il ciclo
|
||
|
||
Aggiorna la documentazione **nella stessa modifica del codice**, seguendo
|
||
[references/chiusura-ciclo.md](references/chiusura-ciclo.md). In sintesi:
|
||
|
||
| Documento | Cosa scrivere | Quando |
|
||
|---|---|---|
|
||
| TODO | stato del task (⬜ → 🟡 → ✅) | ✅ solo con test passanti |
|
||
| TRACEABILITY | stato della riga REQ, criteri coperti | **quando il test passa, non quando il codice è scritto** |
|
||
| spec | nuove sezioni `bis`, criteri e task aggiunti | se la regola cambia o si estende |
|
||
| DECISIONS | nuova `D-xxx` (mai modificarne una vecchia: la si *supera*) | ogni scelta strutturale o deviazione |
|
||
| CHANGELOG | cosa cambia **per chi usa il prodotto** | ogni modifica visibile |
|
||
| DEVELOPMENT_LOG | cosa si è scoperto e **perché** si è deciso così | scoperte, tentativi respinti, misure |
|
||
| PROJECT_MEMORY | solo ciò che, dimenticato, fa ripetere un errore | raramente |
|
||
| 00-INDEX | riquadro `> **Titolo (data):**` in testa + date «Ultimo aggiornamento» | ogni consegna rilevante |
|
||
|
||
Riporta sempre il numero di test eseguiti e il loro esito reale (es. «backend 614 (+3)»).
|
||
Non dichiarare ✅ ciò che non è stato verificato: scrivi 🟡 e cosa manca.
|
||
|
||
---
|
||
|
||
## 7. Incoerenze e fonti di verità
|
||
|
||
La documentazione viva va in deriva: indici non aggiornati, totali vecchi, spec marcata «da
|
||
approvare» ma task già ✅, ID citati e mai definiti (l'`overview` li elenca). Quando le trovi:
|
||
|
||
1. **Non correggere in silenzio e non sceglierne una a caso.** Elencale nel brief.
|
||
2. Applica la gerarchia delle fonti di verità dichiarata dal progetto. Default:
|
||
- contratto API → `openapi.yaml` (non API.md, non il codice);
|
||
- requisiti di parità → codice della versione precedente citato in *Origine*;
|
||
- stato «verificato» → test **eseguiti** (non la TRACEABILITY);
|
||
- decisioni → l'ultima `D-xxx` accettata che non è superata;
|
||
- stato di una spec → la sua riga `Stato:`; in assenza, l'indice.
|
||
3. Se l'incoerenza blocca il lavoro, chiedi all'utente; altrimenti prosegui e proponi la
|
||
correzione documentale insieme alla consegna.
|
||
|
||
---
|
||
|
||
## 8. Cose da non fare
|
||
|
||
- Implementare da una spec *da approvare* o da un'idea non scritta, senza dirlo.
|
||
- «Modernizzare» ciò che un requisito di parità o una decisione congela.
|
||
- Rinumerare o riusare un ID: gli ID sono **immutabili**; quelli eliminati si barrano (`~~T-005~~`).
|
||
- Cancellare una decisione o una voce di diario: si superano o si annotano.
|
||
- Leggere per intero file da migliaia di righe quando basta una sezione.
|
||
- Copiare segreti trovati nella documentazione in risposte, log o commit.
|
||
|
||
---
|
||
|
||
<sub>**STS Lab Srl** · Spec-Driven Reader v1.1 (lettura + scrittura) · 2026-10-16 · uso interno e per i clienti STS Lab Srl</sub>
|