Quickstart

Il tuo primo cambiamento, dall'idea all'archiviazione, in un progetto nuovo o esistente.

Prima di iniziare, ti serve la CLI sulla tua macchina (Installazione) e OpenSpec inizializzato nel tuo progetto (Configura il tuo progetto).

Inizia da un progetto vuoto

Puoi iniziare senza aver scelto uno stack o un'architettura completa. Inizializza OpenSpec nella cartella del tuo progetto, poi chiedi al tuo agente di esplorare le opzioni insieme a te. Nella tua chat AI:

Aiutami a esplorare un task tracker da zero. Non ho scelto uno stack. Confronta le opzioni e aiutami a scegliere il primo comportamento da implementare.

Decidi di cosa ha bisogno il primo cambiamento e lascia aperte le scelte architetturali successive. Chiedi al tuo agente di proporre quel singolo cambiamento, poi segui i passaggi qui sotto. Puoi rivisitare l'architettura man mano che il progetto cresce.

Il ciclo in breve

Ogni cambiamento passa attraverso gli stessi cinque passaggi: rifletti sull'idea con il tuo agente, egli redige un piano, correggi il piano prima che esista codice, l'agente costruisce basandosi su di esso, e l'archiviazione aggiorna le tue specifiche con ciò che è stato rilasciato.

flowchart LR
    explore["1 · Esplora<br/>rifletti insieme"] --> propose["2 · Proponi<br/>l'agente redige il piano"]
    propose --> review["3 · Rivedi<br/>correggi il piano"]
    review --> apply["4 · Applica<br/>l'agente costruisce, attività per attività"]
    apply --> archive["5 · Archivia<br/>le specifiche assorbono il cambiamento"]
    archive -. "prossimo cambiamento" .-> explore

Ogni prompt qui sotto va inserito nella tua chat AI, lo stesso posto in cui chiedi il codice. Gli esempi usano un linguaggio semplice perché funzionino su tutti gli strumenti. Puoi anche invocare una skill direttamente; la sintassi varia a seconda dello strumento (strumenti supportati).

Passaggio 1: Esplora

Rifletti sull'idea con il tuo agente prima di chiedere un piano. Nella tua chat AI:

Aiutami a esplorare come dovrebbe funzionare il rate limiting in questa app.

Esplora è una modalità di riflessione. L'agente investiga il tuo codebase, pone le domande che contano, abbozza opzioni e mette alla prova le ipotesi. Non scrive mai codice. Non scrive altro a meno che tu non gli chieda di registrare ciò che hai deciso, o di dire sì quando te lo propone. Il risultato è un'idea più nitida.

Resta qui per tutto il tempo che il problema richiede. Quando la forma ti sembra giusta, passala oltre:

Proponi il cambiamento di cui abbiamo appena discusso.

Quella riga avvia la proposta per te, portando con sé tutto ciò che hai stabilito. Salta il primo prompt del passaggio 2.

Passaggio 2: Proponi

Proponi trasforma l'idea in un piano revisionabile. Arrivando da Esplora, è già in esecuzione. Partendo a freddo, quando il cambiamento è chiaro nella tua mente, chiedi direttamente. Nella tua chat AI:

Proponi un cambiamento per aggiungere il rate limiting.

L'agente chiede ciò di cui ha bisogno, poi scrive una cartella di cambiamento:

openspec/changes/add-rate-limiting/
├── proposal.md    perché e cosa cambia
├── specs/         cosa significa "fatto", come requisiti verificabili
├── design.md      decisioni tecniche (solo quando il cambiamento lo richiede)
└── tasks.md       la checklist di implementazione

Ancora nessun codice. Proponi si ferma al piano.

Passaggio 3: Rivedi e correggi il piano

Correggi il piano mentre sono ancora solo parole e non è stato costruito nulla. Leggi in quest'ordine:

• proposal.md: è questo il problema giusto, nella dimensione giusta?
• specs/: la lettura più importante. Accetteresti questi requisiti come completati?
• tasks.md: le attività coprono le specifiche, e nient'altro?

Per correggere qualcosa, puoi procedere in due modi:

• Modifica il file tu stesso. Gli artefatti sono markdown semplice, e i file sono il piano.
• Di all'agente cosa non va ("la specifica manca il caso non autenticato"). L'agente rivede gli artefatti.

Passaggio 4: Applica

Applica trasforma il piano in codice. Avvia una nuova sessione di chat, poiché l'implementazione funziona meglio in una finestra di contesto pulita. Nella tua chat AI:

Applica il cambiamento add-rate-limiting.

L'agente legge la cartella di cambiamento, poi lavora attraverso tasks.md, spuntando ogni attività man mano che la completa.

• Interrotto, o fuori contesto? Apri una nuova sessione e chiedi di applicare di nuovo. Riprende dalla prima attività non spuntata.
• Il piano si è rivelato sbagliato? Correggi gli artefatti (con entrambi i metodi del passaggio 3), poi continua ad applicare.
• Il progresso risiede nelle caselle di controllo di tasks.md. Non esiste stato nascosto.

Passaggio 5: Archivia

L'archiviazione fa due cose: aggiorna le tue specifiche principali con i requisiti del cambiamento, e sposta la cartella di cambiamento nella cartella di archivio (in /openspec/changes/archive/*).

Quando ogni casella in tasks.md è spuntata, nella tua chat AI:

Archivia il cambiamento add-rate-limiting.

Scorri cosa fa l'archiviazione:

## Il cambiamento completato
> L'implementazione è terminata. La specifica delta (ciò che questo cambiamento aggiunge) si trova ancora dentro la cartella di cambiamento; specs/ non sa ancora del rate limiting.
  openspec/
  ├── specs/                                   (nessuna specifica rate-limiting ancora)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         ogni casella spuntata
          └── specs/
              └── rate-limiting/
                  └── spec.md                  il delta: requisiti AGGIUNTI

## I requisiti arrivano in specs/
> Ogni requisito nel delta arriva nella specifica principale: quelli aggiunti si accodano, quelli modificati sostituiscono la loro vecchia versione. Una nuova capability ottiene un nuovo file di specifica.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          ottiene "Requisito: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  il delta, fonte della fusione

## La cartella si sposta in archive/
> L'intera cartella di cambiamento, delta incluso, si sposta nell'archivio con un prefisso di data. Nulla viene eliminato.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Le specifiche descrivono il sistema così come costruito
> changes/ è libera per il prossimo cambiamento. specs/ è la fonte di verità per ciò che il sistema fa; archive/ è la storia di come ci è arrivato.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          la specifica così come costruita
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git è una questione separata. Committa la cartella di cambiamento con il codice, e nient'altro nel tuo workflow cambia.

Mantieni o elimina i cambiamenti archiviati

openspec/changes/archive/ conserva la proposta, il design, le attività e il delta per ogni cambiamento completato. Nel flusso di archiviazione sopra, il delta ha già aggiornato openspec/specs/.

• Mantieni l'intera cartella di cambiamento quando vuoi un registro autonomo nel checkout corrente.
• Rimuovi la cartella specs/ di un cambiamento archiviato quando Git è la tua cronologia delle specifiche. Committa prima l'archivio, poi elimina openspec/changes/archive/<change>/specs/. La proposta, il design e le attività restano nel checkout. openspec validate --archived funziona ancora perché verifica il completamento delle attività, non i delta applicati.
• Rimuovi l'intera cartella di cambiamento solo quando non hai più bisogno della sua proposta, design o cronologia delle attività nel checkout. Le specifiche correnti non cambiano, ma openspec validate --archived e le ricerche nel checkout non includono più quel cambiamento.

WARNING

Mantieni il commit di archivio nella cronologia del tuo repository se vuoi che Git conservi i file eliminati. Unire insieme il commit di archivio e quello di pulizia rimuove quel snapshot intermedio.

OpenSpec non elimina automaticamente i cambiamenti archiviati né fornisce un'impostazione di conservazione.

Per approfondire

• Specifiche delta: come scrivere i cambiamenti di comportamento in una specifica delta.
• Profili: workflow opzionali oltre il set principale (verifica prima dell'archiviazione, pianificazione incrementale).

Guide avanzate

Non ancora scritte; guide che prevediamo di aggiungere:

• Prototipa prima: fai uno spike del codice prima di qualsiasi specifica, poi ricompili la proposta da ciò che il prototipo ti ha insegnato.
• Costruire iterativamente: una sequenza di piccoli cambiamenti invece di una grande proposta.
• Revisionare un cambiamento implementato: il piano deve muoversi di nuovo dopo l'applicazione, ma il cambiamento non è ancora stato unito o archiviato.