italiadatacenter/add-on/AgentPlatform/sts-spec-driven/references/layout.md

Layout della documentazione — STS Lab Srl

Due forme ricorrenti nei progetti STS Lab Srl. La skill deve funzionare con entrambe e con varianti intermedie. Per un progetto nuovo l'utente sceglie quale creare: i modelli sono in templates/strutturato/ e templates/piatto/ (vedi scrittura.md).

---

A. Layout strutturato (es. KadeonCad_v2/docs)

docs/
├── 00-INDEX.md            mappa, stato degli step, novità recenti in riquadri datati
├── 01-product/            COSA e PER CHI
│   ├── VISION.md            perché esiste, perimetro, non-obiettivi
│   ├── GLOSSARY.md          lessico condiviso (usare gli stessi termini nel codice)
│   ├── PERSONAS_CASI_USO.md attori e casi d'uso end-to-end
│   └── REQUIREMENTS.md      REQ-<AREA>-<nn> + DIF-<nn> (difetti noti)
├── 02-architecture/       COME È FATTO
│   ├── ARCHITECTURE.md · C4_MODEL.md · DOMAIN_WORKFLOW.md (macchina a stati, invarianti)
│   ├── DATA_MODEL.md (entità, relazioni, invarianti) · SECURITY.md · STORAGE.md
│   └── <componente>.md      (AI_GATEWAY, MESH_ENGINE, …)
├── 03-specs/              CONTRATTO PER L'IMPLEMENTAZIONE
│   └── SPEC-<nnn>-<slug>.md
├── 04-api/                CONTRATTO ESTERNO
│   ├── openapi.yaml         FONTE DI VERITÀ dell'API
│   └── API.md · WEBHOOKS.md · INTEGRATION_*.md
├── 05-data/               DATABASE.md (schema fisico) · MIGRATION_*.md · SEED_BOOTSTRAP.md
├── 06-devops/             INFRASTRUCTURE · KUBERNETES · CI_CD · ENVIRONMENTS · OBSERVABILITY · RUNBOOK · BACKUP_DR
├── 07-quality/            TEST_STRATEGY · ACCEPTANCE_CRITERIA · TRACEABILITY · liste di parità
└── 08-project/            DECISIONS · ROADMAP · TODO · CHANGELOG · DEVELOPMENT_LOG · PROJECT_MEMORY

Dove cercare cosa

Domanda	Documento
Cosa deve fare il prodotto?	01-product/REQUIREMENTS.md
Come deve farlo questa funzione?	03-specs/SPEC-xxx
Che forma ha la rotta?	04-api/openapi.yaml (poi API.md per le convenzioni)
Che colonne/vincoli ha la tabella?	05-data/DATABASE.md; entità logiche in 02-architecture/DATA_MODEL.md
Transizioni di stato ammesse?	02-architecture/DOMAIN_WORKFLOW.md
Perché è così?	08-project/DECISIONS.md (## D-xxx), poi DEVELOPMENT_LOG.md
È fatto? È verificato?	08-project/TODO.md, 07-quality/TRACEABILITY.md
Come si rilascia / variabili d'ambiente?	06-devops/ENVIRONMENTS.md, KUBERNETES.md

Legenda stati usata: ⬜ da scrivere/fare · 🟡 in corso/parziale · ✅ completo/verificato · 🔒 congelato (modifica solo con nuova D-xxx) · ⏸ sospeso.

---

B. Layout piatto (es. Kadeon/kadeon/src/docs)

docs/
├── PROJECT_MEMORY.md     «leggere sempre prima di scrivere codice»; sintesi architettura,
│                         decisioni, componenti già creati, sessioni
├── ARCHITECTURE.md · API.md · DATABASE.md · AI_GATEWAY.md · OUTPUT_SCHEMA.md
├── <MODULO>.md           proposta/specifica di un modulo (es. CAD_MODULE.md)
├── <area>/DESIGN.md      proposte con opzioni e «domande ancora aperte» (es. whatsapp/)
├── <area>/openapi.yaml   contratto del modulo
├── DECISIONS.md          D-xxx con Stato · Contesto · Opzioni · Scelta · Motivazione
├── TODO.md               T-<lettera><nn> raggruppati per tema, con Prio (P0–P3) e Stato
├── CHANGELOG.md · DEVELOPMENT_LOG.md

Differenze da tenere presenti:

• Non ci sono REQ-/SPEC-: il ruolo della spec lo svolge il documento di modulo o la sezione di PROJECT_MEMORY/ARCHITECTURE; il cancello §3 si applica a quello.
• Gli ID dei task hanno un prefisso tematico (T-S01 sicurezza, T-Q5, T-H01…).
• Stati in inglese: pending · in_progress · done · blocked; decisioni accepted · proposed · superseded.
• Un DESIGN.md con «Domande ancora aperte» non è approvato: chiarire con l'utente.
• PROJECT_MEMORY può essere lungo e datato: confronta la sua data con quelle di TODO e DECISIONS.

---

C. Formati degli ID

ID	Forma	Dove nasce	Note
Requisito	REQ-<AREA>-<nn> (AREA 2–5 lettere)	REQUIREMENTS	Tipo P/C/N; mai rinumerato
Difetto	DIF-<nn>	REQUIREMENTS (sezione difetti)	ogni DIF ha un REQ di tipo C e un test
Specifica	SPEC-<nnn>	file 03-specs/SPEC-nnn-slug.md	riga Stato: in testa
Task	T-<nnn> o T-<lettera><nn>, suffissi b, c	sezione Task della spec e TODO	barrato se chiuso senza lavoro
Decisione	D-<nnn>	DECISIONS	superata, mai cancellata
Criterio	lettera + numero (D1, P12, M18)	sezione Criteri della spec	⚠ D1 criterio ≠ D-001 decisione

_{STS Lab Srl · Spec-Driven Reader}