Concetti
Questa guida spiega le idee fondamentali alla base di OpenSpec e come si integrano tra loro. Per l'uso pratico, vedi Per Iniziare e Flussi di Lavoro.
Filosofia
OpenSpec è costruito attorno a quattro principi:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldPerché Questi Principi Contano
Fluido, non rigido. I sistemi di specifiche tradizionali ti bloccano in fasi: prima pianifichi, poi implementi, poi hai finito. OpenSpec è più flessibile — puoi creare artefatti in qualsiasi ordine abbia senso per il tuo lavoro.
Iterativo, non a cascata. I requisiti cambiano. La comprensione si approfondisce. Quello che sembrava un buon approccio all'inizio potrebbe non reggere dopo aver visto il codebase. OpenSpec abbraccia questa realtà.
Semplice, non complesso. Alcuni framework di specifiche richiedono configurazioni estese, formati rigidi o processi pesanti. OpenSpec non ti ostacola. Inizializza in pochi secondi, inizia a lavorare immediatamente, personalizza solo se necessario.
Brownfield-first. La maggior parte del lavoro software non consiste nello sviluppo da zero — ma nella modifica di sistemi esistenti. L'approccio basato su delta di OpenSpec rende facile specificare cambiamenti al comportamento esistente, non solo descrivere nuovi sistemi.
La visione d'insieme
OpenSpec organizza il lavoro in due aree principali:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘I Specs sono la source of truth (fonte di verità) — descrivono come il sistema si comporta attualmente.
I Changes sono modifiche proposte — risiedono in cartelle separate fino a quando non si è pronti a unirli (merge).
Questa separazione è fondamentale. È possibile lavorare su più cambiamenti in parallelo senza conflitti. È possibile revisionare un cambiamento prima che influisca sugli spec principali. E quando si archivia un cambiamento, i suoi delta si fondono pulitamente nella fonte di verità.
Specs
Gli spec descrivono il comportamento del sistema utilizzando requisiti e scenari strutturati.
Struttura
openspec/specs/
├── auth/
│ └── spec.md # Comportamento di autenticazione
├── payments/
│ └── spec.md # Elaborazione dei pagamenti
├── notifications/
│ └── spec.md # Sistema di notifiche
└── ui/
└── spec.md # Comportamento UI e temiOrganizzare gli spec per dominio — raggruppamenti logici che hanno senso per il proprio sistema. Pattern comuni:
- Per area di funzionalità:
auth/,payments/,search/ - Per componente:
api/,frontend/,workers/ - Per contesto delimitato:
ordering/,fulfillment/,inventory/
Formato Spec
Uno spec contiene requisiti, e ogni requisito ha scenari:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateElementi chiave:
| Elemento | Scopo |
|---|---|
## Purpose | Descrizione ad alto livello del dominio di questo spec |
### Requirement: | Un comportamento specifico che il sistema deve avere |
#### Scenario: | Un esempio concreto del requisito in azione |
| SHALL/MUST/SHOULD | Parole chiave RFC 2119 che indicano la forza del requisito |
Perché strutturare gli spec in questo modo
I requisiti sono il "cosa" — dichiarano cosa il sistema dovrebbe fare senza specificare l'implementazione.
Gli scenari sono il "quando" — forniscono esempi concreti che possono essere verificati. Buoni scenari:
- Sono testabili (si potrebbe scrivere un test automatizzato per essi)
- Coprono sia il percorso felice (happy path) che i casi limite (edge cases)
- Utilizzano il formato strutturato Given/When/Then o simile
Le parole chiave RFC 2119 (SHALL, MUST, SHOULD, MAY) comunicano l'intento:
- MUST/SHALL — requisito assoluto
- SHOULD — raccomandato, ma esistono eccezioni
- MAY — opzionale
Cosa è uno Spec (e cosa non è)
Uno spec è un contratto di comportamento, non un piano di implementazione.
Contenuti buoni per uno spec:
- Comportamento osservabile su cui utenti o sistemi downstream fanno affidamento
- Input, output e condizioni di errore
- Vincoli esterni (sicurezza, privacy, affidabilità, compatibilità)
- Scenari che possono essere testati o esplicitamente validati
Evitare negli spec:
- Nomi di classi/funzioni interni
- Scelte di librerie o framework
- Dettagli di implementazione passo-passo
- Piani di esecuzione dettagliati (questi appartengono a
design.mdotasks.md)
Test rapido:
- Se l'implementazione può cambiare senza modificare il comportamento visibile esternamente, probabilmente non appartiene allo spec.
Mantenere la leggerezza: Rigore progressivo
OpenSpec mira a evitare la burocrazia. Utilizzare il livello più leggero che renda comunque verificabile il cambiamento.
Spec Lite (predefinito):
- Requisiti brevi incentrati sul comportamento
- Ambito e non-obiettivi chiari
- Alcuni controlli di accettazione concreti
Spec completo (per rischi più elevati):
- Cambiamenti tra team o tra repository
- Modifiche API/contratto, migrazioni, preoccupazioni di sicurezza/privacy
- Cambiamenti in cui l'ambiguità potrebbe causare costosi lavori di rifacimento
La maggior parte dei cambiamenti dovrebbe rimanere in modalità Lite.
Collaborazione Uomo + Agente
In molti team, gli esseri umani esplorano e gli agenti redigono gli artefatti. Il ciclo previsto è:
- L'umano fornisce intento, contesto e vincoli.
- L'agente converte ciò in requisiti e scenari incentrati sul comportamento.
- L'agente mantiene i dettagli di implementazione in
design.mdetasks.md, non inspec.md. - La convalida conferma struttura e chiarezza prima dell'implementazione.
Questo mantiene gli spec leggibili per gli esseri umani e coerenti per gli agenti.
Changes
Un cambiamento è una modifica proposta al proprio sistema, impacchettata come una cartella con tutto il necessario per comprenderlo e implementarlo.
Struttura del Change
openspec/changes/add-dark-mode/
├── proposal.md # Why and what
├── design.md # How (technical approach)
├── tasks.md # Implementation checklist
├── .openspec.yaml # Change metadata (optional): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # What's changing in ui/spec.mdOgni cambiamento è autocontenuto. Contiene:
- Artefatti — documenti che catturano intento, design e attività
- Delta specs — specifiche per ciò che viene aggiunto, modificato o rimosso
- Metadata — configurazione opzionale per questo specifico cambiamento
Perché i Changes sono Cartelle
Impacchettare un cambiamento come una cartella offre diversi vantaggi:
Tutto insieme. Proposta, design, attività e spec vivono in un unico posto. Non c'è bisogno di cercare attraverso diverse posizioni.
Lavoro parallelo. Più cambiamenti possono esistere simultaneamente senza conflitti. Lavorare su
add-dark-modementrefix-auth-bugè anche in corso.Cronologia pulita. Quando archiviati, i cambiamenti si spostano in
changes/archive/preservando il loro contesto completo. Si può guardare indietro e capire non solo cosa è cambiato, ma perché.Facile da revisionare. Una cartella di cambiamento è facile da revisionare — aprirla, leggere la proposta, controllare il design, vedere i delta degli spec.
Artefatti
Gli artefatti sono i documenti all'interno di un cambiamento che guidano il lavoro.
Il Flusso degli Artefatti
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeGli artefatti si costruiscono l'uno sull'altro. Ogni artefatto fornisce contesto per il successivo.
Tipi di Artefatti
Proposta (proposal.md)
La proposta cattura intent, scope e approccio a livello alto.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Quando aggiornare la proposta:
- Modifiche allo scope (restringendo o ampliando)
- L'intent si chiarisce (migliore comprensione del problema)
- L'approccio cambia fondamentalmente
Specs (delta specs in specs/)
I delta specs descrivono cosa sta cambiando rispetto agli spec attuali. Vedere Delta Specs di seguito.
Design (design.md)
Il design cattura l'approccio tecnico e le decisioni architetturali.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Quando aggiornare il design:
- L'implementazione rivela che l'approccio non funzionerà
- Scoperta di una soluzione migliore
- Dipendenze o vincoli cambiano
Tasks (tasks.md)
Le attività sono la lista di controllo per l'implementazione — passi concreti con caselle di controllo.
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibilityBuone pratiche per le attività:
- Raggruppare attività correlate sotto intestazioni
- Utilizzare numerazione gerarchica (1.1, 1.2, ecc.)
- Mantenere le attività abbastanza piccole da completare in una sessione
- Spuntare le attività man mano che vengono completate
Delta Specs
I delta specs sono il concetto chiave che rende OpenSpec efficace per lo sviluppo brownfield. Descrivono cosa sta cambiando invece di ripetere l'intero spec.
Il Formato
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Sezioni Delta
| Sezione | Significato | Cosa succede all'Archiviazione |
|---|---|---|
## ADDED Requirements | Nuovo comportamento | Aggiunto allo spec principale |
## MODIFIED Requirements | Comportamento modificato | Sostituisce il requisito esistente |
## REMOVED Requirements | Comportamento deprecato | Eliminato dallo spec principale; rimuovendo l'ultimo requisito, la capacità viene ritirata ed eliminato il suo file spec, quando il cambiamento dichiara retire_capabilities: true |
## Purpose | A cosa serve una nuova capacità | Inizia il Purpose dello spec principale che viene creato; ignorato quando lo spec esiste già |
Perché Delta invece di Spec Completi
Chiarezza. Un delta mostra esattamente cosa sta cambiando. Leggendo uno spec completo, si dovrebbe confrontarlo mentalmente con la versione attuale.
Evitare conflitti. Due cambiamenti possono toccare lo stesso file spec senza conflitti, purché modifichino requisiti diversi.
Efficienza della revisione. I revisori vedono il cambiamento, non il contesto invariato. Concentrarsi su ciò che conta.
Adattamento Brownfield. La maggior parte del lavoro modifica comportamenti esistenti. I delta rendono le modifiche di prima classe, non un pensiero secondario.
Schemi
Gli schemi definiscono i tipi di artefatti e le loro dipendenze per un workflow.
Come funzionano gli schemi
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Nessuna dipendenza, può essere creato per primo
- id: specs
generates: specs/**/*.md
requires: [proposal] # Richiede la proposta prima della creazione
- id: design
generates: design.md
requires: [proposal] # Può essere creato in parallelo con le specifiche
- id: tasks
generates: tasks.md
requires: [specs, design] # Richiede sia le specifiche sia il designGli artefatti formano un grafo di dipendenze:
proposal
(nodo radice)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(richiede: (richiede:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(richiede:
specs, design)Le dipendenze sono abilitatori, non gate. Indicano cosa è possibile creare, non cosa devi creare per primo. Puoi saltare il design se non ti serve. Puoi creare le specifiche prima o dopo il design — entrambi dipendono solo dalla proposta.
Schemi integrati
spec-driven (predefinito)
Il workflow standard per lo sviluppo basato su specifiche:
proposal → specs → design → tasks → implementIdeale per: la maggior parte dei lavori su funzionalità in cui si desidera concordare le specifiche prima dell'implementazione.
Schemi personalizzati
Crea schemi personalizzati per il workflow del tuo team:
# Crea da zero
openspec schema init research-first
# Oppure fork di uno esistente
openspec schema fork spec-driven research-firstEsempio di schema personalizzato:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Fai prima la ricerca
- id: proposal
generates: proposal.md
requires: [research] # Proposta informata dalla ricerca
- id: tasks
generates: tasks.md
requires: [proposal] # Salta specifiche/design, vai direttamente ai taskConsulta Personalizzazione per tutti i dettagli sulla creazione e l'uso di schemi personalizzati.
Archiviazione
L'archiviazione completa un cambiamento fondendo le sue specifiche delta nelle specifiche principali e preservando il cambiamento per la storia.
Cosa succede quando archivi
Prima dell'archiviazione:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Dopo l'archiviazione:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Ora include i requisiti 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preservato per la storia
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdIl processo di archiviazione
Fusione dei delta. Ogni sezione di specifica delta (ADDED/MODIFIED/REMOVED) viene applicata alla corrispondente specifica principale.
Spostamento nell'archivio. La cartella del cambiamento viene spostata in
changes/archive/con un prefisso di data per l'ordinamento cronologico.Preservazione del contesto. Tutti gli artefatti restano intatti nell'archivio. Puoi sempre consultare il passato per capire perché un cambiamento è stato fatto.
Perché l'archiviazione è importante
Stato pulito. I cambiamenti attivi (changes/) mostrano solo il lavoro in corso. Il lavoro completato viene spostato da parte.
Traccia di audit. L'archivio preserva il contesto completo di ogni cambiamento — non solo cosa è cambiato, ma la proposta che spiega il perché, il design che spiega il come, e i task che mostrano il lavoro svolto.
Evoluzione delle specifiche. Le specifiche crescono organicamente man mano che i cambiamenti vengono archiviati. Ogni archiviazione fonde i suoi delta, costruendo nel tempo una specifica completa.
Come si integrano tutte le parti
┌──────────────────────────────────────────────────────────────────────────────┐
│ FLUSSO OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. INIZIA │ /opsx:propose (core) o /opsx:new (espanso) │
│ │ CAMBIAMENTO│ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREA │ /opsx:ff o /opsx:continue (workflow espanso) │
│ │ ARTEFATTI │ Crea proposta → specifiche → design → task │
│ │ │ (in base alle dipendenze dello schema) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENTA │ /opsx:apply │
│ │ TASK │ Lavora sui task, spuntandoli │
│ │ │◄──── Aggiorna gli artefatti man mano che impari │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFICA │ /opsx:verify (opzionale) │
│ │ LAVORO │ Controlla che l'implementazione corrisponda alle specifiche│
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVIA │────►│ Le specifiche delta si fondono nelle specifiche principali│
│ │ CAMBIAMENTO│ │ La cartella del cambiamento si sposta in archive/│ │
│ └────────────────┘ │ Le specifiche sono ora la fonte di verità aggiornata│
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Il ciclo virtuoso:
- Le specifiche descrivono il comportamento attuale
- I cambiamenti propongono modifiche (come delta)
- L'implementazione rende i cambiamenti reali
- L'archiviazione fonde i delta nelle specifiche
- Le specifiche ora descrivono il nuovo comportamento
- Il cambiamento successivo si basa sulle specifiche aggiornate
Glossario
| Termine | Definizione |
|---|---|
| Artefatto | Un documento all'interno di un cambiamento (proposta, design, task o specifiche delta) |
| Archiviazione | Il processo di completamento di un cambiamento e fusione dei suoi delta nelle specifiche principali |
| Cambiamento | Una modifica proposta al sistema, impacchettata come cartella con artefatti |
| Specifica delta | Una specifica che descrive modifiche (ADDED/MODIFIED/REMOVED) rispetto alle specifiche attuali |
| Dominio | Un raggruppamento logico per le specifiche (es. auth/, payments/) |
| Requisito | Un comportamento specifico che il sistema deve avere |
| Scenario | Un esempio concreto di un requisito, tipicamente in formato Given/When/Then |
| Schema | Una definizione dei tipi d'artefatto e delle loro dipendenze |
| Specifica | Una specifica che descrive il comportamento del sistema, contenente requisiti e scenari |
| Fonte di verità | La directory openspec/specs/, contenente il comportamento concordato attuale |
Prossimi passi
- Primi passi - Passi pratici iniziali
- Workflow - Pattern comuni e quando usarli
- Comandi - Riferimento completo dei comandi
- Personalizzazione - Crea schemi personalizzati e configura il tuo progetto