OpenSpec

Esplora prima ​

/opsx:explore è il tuo partner di pensiero. Utilizzalo ogni volta che hai un problema ma non ancora un piano. Indaga il tuo codebase, valuta le opzioni con te e chiarisce cosa vuoi realmente, tutto prima che venga creato un singolo artefatto o una riga di codice. Quando la situazione è chiara, passa la mano a /opsx:propose.

Se devi prendere un solo abitudine da questa documentazione, prendi questa: quando non sei sicuro, esplora prima di proporre.

Ecco perché è importante. Gli assistenti di codifica AI sono ansiosi di agire. Fai una richiesta vaga e costruiranno qualcosa con sicurezza, anche se forse non la cosa di cui avevi bisogno. L'esplorazione è la cura. È una conversazione senza rischi in cui tu e l'AI scoprite insieme la mossa giusta, così che quando proponi, stai proponendo la cosa giusta.

Quando esplorare ​

Esplorare è il primo passo giusto più spesso di quanto ci si aspetti. Usalo quando una di queste condizioni è vera:

  • Conosci il problema ma non la soluzione. ("Le pagine sembrano lente." "L'autenticazione è un disastro." "Continuiamo a ricevere ordini duplicati.")
  • Stai scegliendo tra approcci diversi e vuoi che i compromessi siano illustrati rispetto al tuo codice effettivo.
  • Sei nuovo nel codebase e devi capire come funziona qualcosa prima di modificarlo.
  • I requisiti sono vaghi e vuoi affinarli prima di impegnarti.
  • Sospetti che il lavoro sia più grande o più piccolo di quanto sembri e vuoi valutarne l'ambito onestamente.

Salta l'esplorazione solo quando sai già esattamente cosa vuoi e come farlo. In tal caso, vai direttamente a /opsx:propose.

Cosa fa (e cosa non fa) ​

Esplorare è una conversazione, non un generatore.

Fa:

  • Leggere e cercare nel tuo codebase per rispondere a domande reali.
  • Confrontare le opzioni e indicare i compromessi di ciascuna.
  • Disegnare diagrammi per rendere leggibile un design.
  • Aiutarti a restringere un'idea vaga in un ambito concreto e realizzabile.
  • Passare a /opsx:propose quando sei pronto.

Non fa:

  • Creare una cartella delle modifiche.
  • Scrivere alcun artefatto (nessuna proposta, specifiche, design o attività).
  • Scrivere o modificare codice.

Questo è il punto. Esplorare non ti costa nulla e non ti impegna a nulla. Puoi esplorare tre vicoli ciechi, imparare qualcosa da ciascuno, e solo allora proporre il percorso che ha resistito.

È già installato ​

Buone notizie: /opsx:explore è incluso nel profilo predefinito core, proprio accanto a propose, apply, update, sync e archive. Non devi abilitare nulla. Se OpenSpec è configurato nel tuo progetto, esplorare è pronto nella tua chat AI. (Come per tutti i comandi /opsx:*, lo digiti nella chat del tuo assistente, non nel terminale. Vedi Come funzionano i comandi.)

Un esempio completo ​

Guarda come una preoccupazione vaga diventa una modifica precisa e realizzabile.

text
Tu: /opsx:explore

AI:  Cosa vorresti esplorare?

Tu: A volte il nostro checkout crea ordini duplicati. Non so perché
     e non so come risolverlo in modo sicuro.

AI:  Lascia che approfondisca il percorso del checkout...
     [legge il servizio ordini, il gestore webhook di pagamento e la
      logica di invio del client]

     Ecco cosa ho trovato. Ci sono due modi in cui può verificarsi un duplicato:

     1. Il client può inviare due volte (doppio clic, retry su rete lenta).
        Nulla lo debitta.
     2. Il webhook di pagamento può attivarsi più di una volta, e il gestore
        crea un ordine ogni volta. Non c'è una chiave di idempotenza.

     La causa #2 è quella pericolosa: può addebitare ed evadere due volte.

     Tre modi per risolverlo, approssimativamente in ordine di robustezza:
     - Chiave di idempotenza sull'endpoint di creazione dell'ordine (gestisce entrambe le cause)
     - Deduplicazione sul webhook tramite payment-intent id (gestisce solo la #2)
     - Debounce lato client (gestisce solo la #1, maschera il bug reale)

     Dato che il tuo codice memorizza già il payment-intent id,
     l'approccio della chiave di idempotenza è una piccola modifica con il massimo rendimento.
     Vuoi che ne definisca l'ambito?

Tu: Sì, facciamo la chiave di idempotenza.

Tu: /opsx:propose add-order-idempotency-key

AI:  Creato openspec/changes/add-order-idempotency-key/, con una proposta
     e una specifica delta basate su quanto appena scoperto. Pronto per l'implementazione.

Nota cosa è successo. Il punto di partenza era "qualcosa non va e ho paura di toccarlo". Venti secondi di esplorazione hanno trasformato questo in una causa radice nominata, tre opzioni classificate, una raccomandazione legata al codice esistente e una modifica precisa. La proposta che segue è nitida perché il pensiero è avvenuto prima.

Passaggio a propose ​

Esplorare non archivia nulla in formato definitivo. Quando sei pronto, avvia semplicemente una modifica e l'AI trasferirà il contesto dalla tua conversazione agli artefatti.

text
explore  ──►  propose  ──►  apply  ──►  archive
 (pensiero)   (accordo)    (costruzione) (registrazione)

Puoi dirlo in linguaggio naturale ("trasformiamo questo in una modifica") o eseguire direttamente /opsx:propose <nome>. In entrambi i casi, l'esplorazione che hai appena fatto diventa la base della proposta, non una chat destinata alla cancellazione.

Se usi il set di comandi esteso, esplorare può passare la mano a /opsx:new invece, per la creazione di artefatti passo dopo passo. Vedi Flussi di lavoro.

Consigli per una buona esplorazione ​

  • Porta il problema, non la soluzione. "I login sembrano lenti" dà all'AI spazio per indagare. "Aggiungi una cache Redis" ti impegna preventivamente a una risposta che non hai ancora testato.
  • Chiedi esplicitamente i compromessi. "Quali sono gli svantaggi di ogni opzione?" ti offre un confronto più onesto.
  • Lascialo leggere prima. Le migliori esplorazioni iniziano con l'AI che guarda effettivamente il tuo codice, non indovinando. Indicagli l'area rilevante se aiuta.
  • È lecito ritirarsi. Se l'esplorazione rivela che l'idea non vale la pena, è una vittoria. Lo hai imparato a basso costo.
  • Esplora di nuovo durante la modifica. Bloccato durante /opsx:apply? Puoi tornare indietro ed esplorare un sotto-problema, poi riprendere.

I compromessi onesti ​

Cosa guadagni: esplorare cattura le svolte sbaglianti nel momento più economico possibile, prima che esista qualsiasi artefatto. È particolarmente potente in codice non familiare, dove la capacità dell'AI di leggere e riassumere il sistema ti risparmia un pomeriggio di scavi.

Cosa costa: un po' di pazienza. Esplorare è una conversazione, quindi è più lento che lanciare /opsx:propose e sperare bene. Per lavori che comprendi già pienamente, quel passaggio extra è puro overhead e dovresti saltarlo.

La regola pratica: più il compito è vago, più l'esplorazione ripaga. Più il compito è chiaro, più puoi saltare direttamente alla proposta.

Dove andare oltre ​