Esempi e Ricette

Modifiche reali, dall'inizio alla fine. Ogni ricetta mostra i comandi che digiteresti e ciò che vedresti in risposta, così da poter confrontare la tua situazione con un modello e copiarlo. Questi esempi utilizzano i comandi core predefiniti (propose, explore, apply, update, sync, archive); dove l'insieme esteso di comandi risulta utile, viene specificato.

Un promemoria prima di iniziare: i comandi slash come /opsx:propose vanno inseriti nella chat del tuo assistente AI, mentre i comandi openspec vanno eseguiti nel terminale. Se non sei pratico, leggi prima Come Funzionano i Comandi. Nelle trascrizioni seguenti, You: (Tu:) e AI: indicano la chat, mentre le righe che iniziano con $ indicano il terminale.

Non sei ancora sicuro di cosa stai costruendo? La maggior parte di queste ricette è più efficace se inizi con /opsx:explore per rifletterci sopra prima di procedere. La Ricetta 3 lo mostra in azione e la guida Esplorare Prima espone il caso completo.

Ricetta 1: Una piccola funzionalità, il percorso veloce

Quando usarla: sai cosa vuoi e si tratta di un lavoro contenuto. Questa è la ricetta più comune.

L'intero processo richiede tre comandi: Propose, apply, archive.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Ora leggi il piano. Apri la proposta e la specifica delta. Questo è il momento per cui OpenSpec è stato creato: catturare un'assunzione errata quando è ancora lunga un paragrafo, non 400 righe di codice. Modifica direttamente qualsiasi artefatto se qualcosa non va, poi continua.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Ecco fatto. Il comportamento di disconnessione è ora parte delle tue specifiche e la modifica è archiviata con tutto il suo contesto.

Ricetta 2: Una correzione di bug

Quando usarla: qualcosa non funziona e vuoi che la correzione venga registrata come una modifica deliberata al comportamento, non come un commit misterioso.

Le correzioni di bug funzionano esattamente come le funzionalità. La differenza sta nel modo in cui formulai la proposta: descrivi il comportamento corretto, non solo "risolvi il bug".

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Poiché la correzione viene applicata a un requisito MODIFIED con uno scenario fresco, la persona successiva (o la prossima sessione AI) vedrà non solo che hai risolto il problema, ma anche cosa significa "corretto". Poi procedi con /opsx:apply e /opsx:archive come di consueto.

Suggerimento: per una correzione, un buon scenario è il test di regressione in forma testuale. "DATO un utente disconnesso, QUANDO invia credenziali valide, ALLORA atterra sulla dashboard e non viene reindirizzato nuovamente." Scrivi questo, e l'implementazione avrà un obiettivo chiaro.

Ricetta 3: Esplorare prima di impegnarsi

Quando usarla: hai un problema ma non ancora un piano. Non sei sicuro di cosa costruire o quale approccio sia corretto.

Inizia con /opsx:explore. È un partner di pensiero senza struttura e senza creazione di artefatti. Legge il tuo codebase e ti aiuta a decidere.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

L'esplorazione chiarisce il tuo pensiero prima di dedicare una modifica ad essa. Quando l'intuizione si cristallizza, proponi e l'AI porta avanti il contesto.

Ricetta 4: Gestire due modifiche contemporaneamente

Quando usarla: sei a metà di una funzionalità e una correzione urgente fa la coda.

Le modifiche sono cartelle indipendenti, quindi il lavoro parallelo non crea conflitti. Avvia la correzione, completala, poi torna alla funzionalità esattamente da dove avevi interrotto.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Indicare il nome della modifica in /opsx:apply add-dark-mode è il modo per indicare all'AI una modifica specifica quando ce ne sono più di una attiva. Poiché i tracciamenti dei compiti tengono traccia del completamento in tasks.md, l'AI sa esattamente dove ti eri fermato.

Quando diverse modifiche vengono completate insieme, l'esteso /opsx:bulk-archive le archivia insieme e risolve i conflitti delle specifiche controllando cosa è effettivamente implementato. Vedi Flussi di lavoro.

Ricetta 5: Un refactoring senza cambiamenti di comportamento

Quando usarla: stai riorganizzando il codice e il comportamento visibile esternamente dovrebbe rimanere identico.

Questo è il caso interessante, perché un puro refactoring non ha nulla da aggiungere alle tue specifiche. Il contratto del comportamento non cambia; cambia solo l'implementazione. Quindi il lavoro vive nel design e nei compiti, e il delta delle specifiche è vuoto o assente.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Dichiara il delta esplicitamente impostando skip_specs: true nel .openspec.yaml della modifica:

schema: spec-driven
skip_specs: true

Senza il marcatore, openspec validate rifiuta una modifica con zero delta (così una fase delle specifiche dimenticata viene comunque rilevata); con esso, la convalida passa e openspec status mostra la fase delle specifiche come esplicitamente saltata invece che in attesa. Se il refactoring dovesse cambiare il comportamento dopo tutto, rimuovi skip_specs dal .openspec.yaml e scrivi le specifiche delta: la convalida tratta il marcatore più i file delle specifiche come un conflitto, quindi il marcatore obsoleto non può persistere silenziosamente.

L'archiviazione di una modifica contrassegnata non richiede flag aggiuntivi (non ci sono delta da unire). Indipendentemente, il flag --skip-specs dice al comando del terminale di saltare esplicitamente il passaggio delle specifiche:

$ openspec archive refactor-payment-module --skip-specs

Lo stesso flag è utile per strumenti, CI e modifiche solo alla documentazione. Il principio: le specifiche descrivono il comportamento, quindi se il comportamento non è cambiato, nemmeno le specifiche dovrebbero esserlo. Vedi Concetti.

Ricetta 6: Controllo passo dopo passo (comandi estesi)

Quando usarla: una modifica complessa o rischiosa in cui desideri rivedere ogni artefatto prima di procedere.

Il core /opsx:propose redige tutto in una volta. Quando preferisci procedere un passo alla volta, attiva i comandi estesi:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Ora puoi creare lo scheletro e costruire incrementalmente:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Rivedi ogni artefatto man mano che viene creato, modifica liberamente e continua quando sei soddisfatto. Quando vuoi che il resto venga redatto in una sola volta, /opsx:ff avanza rapidamente attraverso gli artefatti di pianificazione rimanenti. Prima dell'archiviazione, /opsx:verify controlla che l'implementazione corrisponda effettivamente alle specifiche. Vedi Flussi di lavoro.

Ricetta 7: Imparare l'intero ciclo in prima persona

Quando usarla: hai installato OpenSpec e vuoi sentire il flusso di lavoro sul tuo codice effettivo, non su un esempio fittizio.

Attiva i comandi estesi (vedi Ricetta 6), poi:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard trova un miglioramento reale (piccolo), crea una modifica per esso, lo implementa e lo archivia, narrando ogni passaggio. Richiede da 15 a 30 minuti e ti lascia con una modifica reale che puoi mantenere o scartare. È il modo più delicato per imparare. Vedi Comandi.

Verifica del tuo lavoro dal terminale

In qualsiasi momento, dal tuo terminale, puoi ispezionare lo stato delle cose:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Questi sono strumenti di lettura e ispezione. La proposizione e la costruzione avvengono ancora tramite comandi slash nella chat. Dettagli completi nel riferimento CLI.

Dove andare oltre

• Explore First: il modo consigliato per iniziare quando si è incerti
• Workflows: i modelli sopra, con indicazioni decisionali su quando usare ciascuno
• Commands: ogni comando slash nel dettaglio
• Getting Started: la panoramica canonica della prima modifica
• Concepts: perché i pezzi si adattano insieme nel modo in cui fanno