OpenSpec

Glossario ​

Tutti i termini di OpenSpec in un unico posto, definiti in linguaggio semplice. Leggilo una volta e il resto della documentazione si leggerà più velocemente.

I termini sono raggruppati per argomento e poi ordinati in ordine alfabetico all'interno di ogni gruppo.

I sostantivi fondamentali ​

Spec. Un documento che descrive il comportamento di una parte del sistema. Le spec si trovano in openspec/specs/, sono organizzate per dominio e sono composte da requisiti e scenari. La spec è l'answer concordata alla domanda "cosa fa questo software?" Vedi Concepts.

Source of truth. L'intera directory openspec/specs/. Contiene l'attuale comportamento concordato del sistema. I change propongono modifiche ad essa; l'archiviazione le applica.

Change. Un'unità di lavoro, impacchettata come cartella sotto openspec/changes/<name>/. Un change contiene tutto ciò che riguarda quella lavorazione: la sua proposta, il design, i task e le modifiche alle spec che introduce. Un change, una funzionalità o una correzione.

Artifact. Un documento all'interno di un change. Gli artifact standard sono la proposta, le delta spec, il design e i task. Vengono creati in ordine di dipendenza e si alimentano a vicenda.

Delta spec. Una spec all'interno di un change che descrive solo ciò che sta cambiando, utilizzando le sezioni ADDED, MODIFIED e REMOVED, anziché riformulare l'intera spec. Questo è ciò che permette a OpenSpec di modificare sistemi esistenti in modo pulito. Vedi Concepts.

Domain. Un raggruppamento logico per le spec, come auth/, payments/ o ui/. Scegli domini che corrispondano al modo in cui pensi al tuo sistema.

All'interno di una spec ​

Requirement. Un singolo comportamento che il sistema deve avere, generalmente scritto con una parola chiave RFC 2119: "Il sistema SHALL scadere le sessioni dopo 30 minuti." I requisiti specificano il cosa, non l'how.

Scenario. Un esempio concreto e testabile di un requisito in azione, tipicamente in forma Given/When/Then. Gli scenari rendono un requisito verificabile: da uno scenario puoi scrivere un test automatizzato.

RFC 2119 keywords. Le parole MUST, SHALL, SHOULD e MAY, che hanno un significato standardizzato riguardo alla rigidità di un requisito. MUST e SHALL sono assolute. SHOULD è raccomandato con possibilità d'eccezioni. MAY è opzionale. Il nome deriva dal documento di standardizzazione di internet che le ha definite.

Gli artifact ​

Proposal (proposal.md). Il perché e il cosa di un change: la sua intenzione, l'ambito e l'approccio di alto livello. Il primo artifact che crei.

Design (design.md). Il come: approccio tecnico, decisioni architetturali e i file che prevedi di modificare. Facoltativo per i change semplici.

Tasks (tasks.md). L'elenco di controllo per l'implementazione, con caselle di spunta. l'IA lo percorre durante /opsx:apply e spunta gli elementi man mano che avanza.

Il ciclo di vita ​

Archive. L'atto di completare un change. Le sue delta spec vengono unite alle spec principali e la cartella del change viene spostata in openspec/changes/archive/YYYY-MM-DD-<name>/. Dopo l'archiviazione, le tue spec descrivono la nuova realtà. Vedi Concepts.

Sync. Unire le delta spec di un change alle spec principali senza archiviare il change. Di solito automatico (l'archiviazione lo propone), ma disponibile separatamente come /opsx:sync per i change di lunga durata. Vedi Commands.

Workflow e comandi ​

OPSX. Il workflow standard attuale di OpenSpec, costruito attorno ad azioni fluide anziché a fasi rigide. I suoi slash command iniziano tutti con /opsx:. Vedi OPSX Workflow.

Slash command. Un comando che digiti nella chat del tuo assistente IA, come /opsx:propose. Gli slash command guidano l'workflow. Non sono comandi di terminale. Vedi How Commands Work.

Explore (/opsx:explore). Il comando da partner di riflessione. Legge il tuo codebase, confronta le opzioni e chiarisce un'idea vaga in un piano concreto, senza creare artifact né scrivere codice. Il punto di partenza consigliato quando hai un problema ma non ancora un piano. Vedi Explore First.

CLI. Il programma openspec che esegui nel terminale. Configura i progetti, elenca e valida i change, apre la dashboard e archivia. La metà terminale di OpenSpec. Vedi CLI.

Skill. Una cartella di istruzioni (.../skills/openspec-*/SKILL.md) che l'assistente IA rileva automaticamente e segue. Le skill sono lo standard cross-tool emergente per fornire il workflow di OpenSpec al tuo assistente.

Command file. Un file di slash command per tool (.../commands/opsx-*). Il meccanismo di distribuzione più vecchio, ancora supportato insieme alle skill. Raramente li tocchi direttamente.

Profile. L'insieme di slash command installati nel tuo progetto. Core (il predefinito) comprende propose, explore, apply, update, sync, archive. L'insieme espanso aggiunge new, continue, ff, verify, bulk-archive, onboard. Modificalo con openspec config profile.

Delivery. Se OpenSpec installa skill, command file o entrambi per i tuoi tool. Configurato globalmente e applicato con openspec update.

Personalizzazione ​

Schema. La definizione di quali artifact ha un workflow e come dipendono l'uno dall'altro. Il predefinito integrato è spec-driven (proposal → specs → design → tasks). Puoi forkarlo o scrivere il tuo. Vedi Customization.

Template. Un file Markdown all'interno di uno schema che modella ciò che l'IA genera per un dato artifact. Modificare un template cambia immediatamente l'output dell'IA, senza necessità di rebuild.

Project config (openspec/config.yaml). Impostazioni per progetto: lo schema predefinito, il context: iniettato in ogni richiesta di pianificazione e le rules: per artifact. Il modo più semplice per insegnare a OpenSpec il tuo stack e le tue convenzioni. Vedi Customization.

Context injection. Inserire il contesto del progetto nel campo context: di config.yaml affinché venga aggiunto automaticamente a ogni artifact generato dall'IA. Più affidabile che sperare che l'IA legga un file separato.

Dependency graph. Il grafo orientato formato dalle relazioni requires: degli artifact. È un DAG (grafo aciclico orientato: le frecce puntano solo in avanti, mai in un ciclo) e OpenSpec lo usa per sapere cosa puoi creare successivamente.

Enablers, not gates. Il principio secondo cui le dipendenze degli artifact mostrano cosa diventa possibile successivamente, non cosa è richiesto successivamente. Puoi rivedere e modificare qualsiasi artifact in qualsiasi momento. Vedi Core Concepts at a Glance.

Coordinazione tra repository (beta) ​

Questi termini si applicano solo se la tua pianificazione copre più di un repository. Sono in beta. La maggior parte degli utenti può ignorarli. Vedi la Stores User Guide.

Store. Un repository autonomo il cui unico scopo è la pianificazione. Ha la stessa struttura openspec/ che già conosci (spec e change) più un piccolo file d'identità. Lo registri una volta sulla tua macchina, per nome, e poi qualsiasi comando OpenSpec può operare in esso da qualsiasi posizione.

Reference. Una dichiarazione, nell'openspec/config.yaml di un repository di codice, di uno store su cui quel repository si basa. I reference sono solo di lettura: il repository mantiene la propria root e openspec instructions ottiene un indice delle spec dello store referenziato, ciascuna con l'esatto comando per recuperarla.

Working context. Ciò che openspec context assembla per l'repository corrente: la sua root OpenSpec più ogni store che referenzia, ciascuno con il metodo per recuperarlo. La risposta alla domanda "con cosa sto lavorando?"

Workset. Un insieme personale e locale alla macchina di cartelle che apri insieme (uno store accanto ai repository di codice su cui lavori). Creato esplicitamente con openspec workset create; nulla di quei percorsi locali viene commitato nel repository di pianificazione condiviso.

Vedi anche ​