OpenSpec

Per Iniziare ​

Questa guida spiega come funziona OpenSpec dopo averlo installato e inizializzato. Per le istruzioni di installazione, consulta il README principale o la guida all'installazione. Nuovo all'intera documentazione? La home della documentazione mappa tutto.

Dove digito questi comandi? In due posti, e confonderli è l'errore più comune all'inizio.

  • I comandi openspec ... (come openspec init) si eseguono nel tuo terminale.
  • I comandi /opsx:... (come /opsx:propose) si eseguono nella chat del tuo assistente AI, la stessa casella in cui gli chiederesti di scrivere codice.

Non esiste una "modalità interattiva" separata da avviare. Devi solo digitare il comando slash nella chat e il tuo assistente gestirà il resto. Spiegazione completa: Come funzionano i comandi.

I Tuoi Primi Cinque Minuti ​

L'intero ciclo, con ogni passaggio etichettato in base a dove avviene:

text
TERMINALE  $ npm install -g @fission-ai/openspec@latest
TERMINALE  $ cd tuo-progetto && openspec init
CHAT AI      /opsx:explore                    (opzionale: pensaci prima)
CHAT AI      /opsx:propose add-dark-mode      (l'AI abbozza il piano; tu lo esamini)
CHAT AI      /opsx:apply                      (l'AI lo implementa)
CHAT AI      /opsx:archive                    (specifiche aggiornate, modifica archiviata)

Due passaggi da terminale per configurarlo, poi vivi nella chat. Il resto di questa guida spiega cosa fa ogni passaggio e cosa vedrai.

Non vuoi fare tu la parte del terminale? Incolla il prompt di configurazione nel tuo assistente e lui gestirà entrambe le righe, poi riporterà cosa ha creato.

Non sai ancora cosa costruire? Inizia con /opsx:explore. È un partner di riflessione senza rischi che legge il tuo codebase, valuta le opzioni e trasforma un'idea vaga in un piano concreto, tutto prima che esista qualsiasi artefatto o codice. Quando il quadro è chiaro, passa a /opsx:propose. Questa è l'abitudine migliore per lavorare con un'AI che altrimenti costruirà con sicurezza la cosa sbagliata. Consulta la guida Explore.

Come Funziona ​

OpenSpec ti aiuta a concordare con il tuo assistente AI di codifica cosa costruire prima che venga scritto qualsiasi codice.

Percorso rapido predefinito (profilo core):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (opzionale)

Inizia con /opsx:explore quando stai cercando di capire cosa fare, oppure salta direttamente a /opsx:propose quando lo sai già. Explore è nel profilo predefinito, quindi è sempre disponibile quando vuoi.

Percorso ampliato (selezione flusso di lavoro personalizzato):

text
/opsx:new ──► /opsx:ff o /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Il profilo globale predefinito è core, che include propose, explore, apply, update, sync e archive. Puoi abilitare i comandi del flusso di lavoro ampliato con openspec config profile e poi openspec update.

Cosa Crea OpenSpec ​

Dopo aver eseguito openspec init, il tuo progetto ha questa struttura:

openspec/
├── specs/              # Fonte di verità (comportamento del tuo sistema)
│   └── <dominio>/
│       └── spec.md
├── changes/            # Aggiornamenti proposti (una cartella per modifica)
│   └── <nome-modifica>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Specifiche delta (cosa sta cambiando)
│           └── <dominio>/
│               └── spec.md
└── config.yaml         # Configurazione del progetto (opzionale)

Due directory chiave:

  • specs/ - La fonte di verità. Queste specifiche descrivono come si comporta attualmente il tuo sistema. Organizzate per dominio (es., specs/auth/, specs/payments/).

  • changes/ - Modifiche proposte. Ogni modifica ha la propria cartella con tutti gli artefatti correlati. Quando una modifica è completa, le sue specifiche si uniscono alla directory principale specs/.

Comprendere gli Artefatti ​

Ogni cartella di modifica contiene artefatti che guidano il lavoro:

ArtefattoScopo
proposal.mdIl "perché" e il "cosa" - cattura intento, ambito e approccio
specs/Specifiche delta che mostrano requisiti AGGIUNTI/MODIFICATI/RIMOSSI
design.mdIl "come" - approccio tecnico e decisioni architetturali
tasks.mdChecklist di implementazione con caselle di spunta

Gli artefatti si costruiscono l'uno sull'altro:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            aggiorna mentre impari

Puoi sempre tornare indietro e perfezionare gli artefatti precedenti mentre impari durante l'implementazione.

Come Funzionano le Specifiche Delta ​

Le specifiche delta sono il concetto chiave in OpenSpec. Mostrano cosa sta cambiando rispetto alle tue specifiche attuali.

Il Formato ​

Le specifiche delta usano sezioni per indicare il tipo di modifica:

markdown
# Delta per Autenticazione

## Requisiti AGGIUNTI

### Requisito: Autenticazione a Due Fattori
Il sistema DEVE richiedere un secondo fattore durante il login.

#### Scenario: OTP obbligatorio
- DATO un utente con 2FA abilitato
- QUANDO l'utente invia credenziali valide
- ALLORA viene presentata una sfida OTP

## Requisiti MODIFICATI

### Requisito: Timeout della Sessione
Il sistema DOVRÀ far scadere le sessioni dopo 30 minuti di inattività.
(Precedentemente: 60 minuti)

#### Scenario: Timeout di inattività
- DATO una sessione autenticata
- QUANDO passano 30 minuti senza attività
- ALLORA la sessione viene invalidata

## Requisiti RIMOSSI

### Requisito: Ricordami
(Deprecato a favore del 2FA)

Cosa Succede in Archiviazione ​

Quando archivi una modifica:

  1. I requisiti AGGIUNTI vengono aggiunti alla specifica principale
  2. I requisiti MODIFICATI sostituiscono la versione esistente
  3. I requisiti RIMOSSI vengono eliminati dalla specifica principale

La cartella della modifica viene spostata in openspec/changes/archive/ per la cronologia di audit.

Esempio: La Tua Prima Modifica ​

Esaminiamo l'aggiunta della modalità scura a un'applicazione.

1. Inizia la Modifica (Predefinita) ​

text
Tu: /opsx:propose add-dark-mode

AI:  Creato openspec/changes/add-dark-mode/
     ✓ proposal.md — perché lo facciamo, cosa sta cambiando
     ✓ specs/       — requisiti e scenari
     ✓ design.md    — approccio tecnico
     ✓ tasks.md     — checklist di implementazione
     Pronto per l'implementazione!

Se hai abilitato il profilo del flusso di lavoro ampliato, puoi anche farlo in due passaggi: /opsx:new e poi /opsx:ff (o /opsx:continue incrementale).

2. Cosa Viene Creato ​

proposal.md - Cattura l'intento:

markdown
# Proposta: Aggiungi Modalità Scura

## Intento
Gli utenti hanno richiesto un'opzione di modalità scura per ridurre
l'affaticamento degli occhi durante l'uso notturno.

## Ambito
- Aggiungere l'interruttore del tema nelle impostazioni
- Supportare il rilevamento delle preferenze di sistema
- Persistere la preferenza in localStorage

## Approccio
Usare proprietà CSS personalizzate per il tema con un contesto React
per la gestione dello stato.

specs/ui/spec.md - Delta che mostra nuovi requisiti:

markdown
# Delta per UI

## Requisiti AGGIUNTI

### Requisito: Selezione del Tema
Il sistema DOVRÀ consentire agli utenti di scegliere tra temi chiari e scuri.

#### Scenario: Interruttore manuale
- DATO un utente su qualsiasi pagina
- QUANDO l'utente clicca l'interruttore del tema
- ALLORA il tema cambia immediatamente
- E la preferenza viene persistere tra le sessioni

#### Scenario: Preferenza di sistema
- DATO un utente senza preferenza salvata
- QUANDO l'applicazione viene caricata
- ALLORA viene usato lo schema di colori preferito del sistema

tasks.md - Checklist di implementazione:

markdown
# Attività

## 1. Infrastruttura del Tema
- [ ] 1.1 Creare ThemeContext con stato chiaro/scuro
- [ ] 1.2 Aggiungere proprietà CSS personalizzate per i colori
- [ ] 1.3 Implementare la persistenza in localStorage

## 2. Componenti UI
- [ ] 2.1 Creare il componente ThemeToggle
- [ ] 2.2 Aggiungere l'interruttore alla pagina delle impostazioni
- [ ] 2.3 Aggiornare Header per includere l'interruttore rapido

## 3. Stile
- [ ] 3.1 Definire la palette di colori del tema scuro
- [ ] 3.2 Aggiornare i componenti per usare le variabili CSS

3. Implementa ​

Tu: /opsx:apply

AI:  Lavorando sulle attività...
     ✓ 1.1 Creato ThemeContext con stato chiaro/scuro
     ✓ 1.2 Aggiunte proprietà CSS personalizzate a globals.css
     ✓ 1.3 Implementata la persistenza in localStorage
     ✓ 2.1 Creato il componente ThemeToggle
     ...
     Tutte le attività completate!

Durante l'implementazione, se scopri che il design deve essere aggiustato, aggiorna semplicemente l'artefatto e continua.

4. Archivia ​

Tu: /opsx:archive

AI:  Archiviando add-dark-mode...
     ✓ Unite le specifiche in openspec/specs/ui/spec.md
     ✓ Spostato in openspec/changes/archive/2025-01-24-add-dark-mode/
     Fatto! Pronto per la prossima funzionalità.

Le tue specifiche delta ora fanno parte delle specifiche principali, documentando come funziona il tuo sistema.

Verifica e Revisione ​

Usa la CLI per controllare le tue modifiche:

bash
# Elenca le modifiche attive
openspec list

# Visualizza i dettagli della modifica
openspec show add-dark-mode

# Valida la formattazione delle specifiche
openspec validate add-dark-mode

# Dashboard interattiva
openspec view

Passi Successivi ​