OpenSpec

Glossário ​

Todos os termos do OpenSpec em um só lugar, definidos de forma clara. Leia rapidamente uma vez e o restante da documentação será compreendida mais rápido.

Os termos estão agrupados por tópico e, dentro de cada grupo, ordenados alfabeticamente.

Os substantivos fundamentais ​

Spec. Um documento que descreve como parte do seu sistema se comporta. Os specs ficam em openspec/specs/, são organizados por domínio e são compostos por requisitos e cenários. O spec é a resposta acordada para "o que este software faz?". Veja Concepts.

Fonte da verdade. O diretório openspec/specs/ como um todo. Ele contém o comportamento atual e acordado do seu sistema. As alterações propõem edições nele; o arquivamento as aplica.

Change. Uma unidade de trabalho, empacotada como uma pasta sob openspec/changes/<name>/. Um change contém tudo sobre esse trabalho: sua proposta, design, tarefas e as edições de spec que ele introduz. Um change, um recurso ou correção.

Artifact. Um documento dentro de um change. Os artifacts padrão são a proposta, os delta specs, o design e as tarefas. Eles são criados em ordem de dependência e alimentam uns aos outros.

Delta spec. Um spec dentro de um change que descreve apenas o que está mudando, usando seções ADDED, MODIFIED e REMOVED, em vez de redeclarar todo o spec. É isso que permite ao OpenSpec editar sistemas existentes de forma limpa. Veja Concepts.

Domain. Um agrupamento lógico para specs, como auth/, payments/ ou ui/. Você escolhe domínios que correspondam à maneira como você pensa sobre o seu sistema.

Dentro de um spec ​

Requirement. Um único comportamento que o sistema deve ter, geralmente escrito com uma palavra-chave RFC 2119: "O sistema SHALL expirar sessões após 30 minutos." Os requirements declaram o o quê, não o como.

Scenario. Um exemplo concreto e testável de um requirement em ação, tipicamente na forma Dado/Quando/Então (Given/When/Then). Os scenarios tornam um requirement verificável: você poderia escrever um teste automatizado a partir dele.

RFC 2119 keywords. As palavras MUST, SHALL, SHOULD e MAY, que carregam significado padronizado sobre quão rigoroso é um requirement. MUST e SHALL são absolutos. SHOULD é recomendado, com espaço para exceções. MAY é opcional. O nome vem do documento de padrões da internet que os definiu.

Os artifacts ​

Proposal (proposal.md). O porquê e o quê de um change: sua intenção, escopo e abordagem de alto nível. O primeiro artifact que você cria.

Design (design.md). O como: abordagem técnica, decisões de arquitetura e os arquivos que você espera modificar. Opcional para changes simples.

Tasks (tasks.md). A lista de verificação de implementação, com caixas de seleção. A IA trabalha através dela durante /opsx:apply e marca os itens conforme avança.

O ciclo de vida ​

Archive. O ato de finalizar um change. Seus delta specs são mesclados nos specs principais, e a pasta do change é movida para openspec/changes/archive/YYYY-MM-DD-<name>/. Após o arquivamento, seus specs descrevem a nova realidade. Veja Concepts.

Sync. Mesclar os delta specs de um change nos specs principais sem arquivar o change. Geralmente automático (o arquivamento oferece fazer isso), mas disponível isoladamente como /opsx:sync para changes de longa duração. Veja Commands.

Fluxo de trabalho e comandos ​

OPSX. O fluxo de trabalho padrão atual do OpenSpec, construído em torno de ações fluidas em vez de fases rígidas. Seus slash commands começam todos com /opsx:. Veja OPSX Workflow.

Slash command. Um comando que você digita no chat do seu assistente de IA, como /opsx:propose. Os slash commands dirigem o fluxo de trabalho. Eles não são comandos de terminal. Veja How Commands Work.

Explore (/opsx:explore). O comando de parceiro de pensamento. Ele lê sua base de código, compara opções e esclarece uma ideia vaga em um plano concreto, sem criar artifacts nem escrever código. O ponto de partida recomendado sempre que você tem um problema, mas ainda não um plano. Veja Explore First.

CLI. O programa openspec que você executa no seu terminal. Ele configura projetos, lista e valida changes, abre o dashboard e archiva. A metade do terminal do OpenSpec. Veja CLI.

Skill. Uma pasta de instruções (.../skills/openspec-*/SKILL.md) que seu assistente de IA detecta automaticamente e segue. Skills são o padrão emergente entre ferramentas para entregar o fluxo de trabalho do OpenSpec ao seu assistente.

Command file. Um arquivo de slash command por ferramenta (.../commands/opsx-*). O mecanismo de entrega mais antigo, ainda suportado junto com as skills. Raramente você toca nesses diretamente.

Profile. O conjunto de slash commands instalados no seu projeto. Core (o padrão) é propose, explore, apply, update, sync, archive. O conjunto expanded adiciona new, continue, ff, verify, bulk-archive, onboard. Altere-o com openspec config profile.

Delivery. Se o OpenSpec instala skills, command files ou ambos para suas ferramentas. Configurado globalmente e aplicado com openspec update.

Personalização ​

Schema. A definição dos quais artifacts um workflow possui e como eles dependem uns dos outros. O padrão integrado é spec-driven (proposal → specs → design → tasks). Você pode bifurcá-lo ou escrever o seu próprio. Veja Customization.

Template. Um arquivo Markdown dentro de um schema que molda o que a IA gera para um determinado artifact. Editar um template altera imediatamente a saída da IA, sem necessidade de reconstrução.

Project config (openspec/config.yaml). Configurações por projeto: o schema padrão, o context: injetado em cada solicitação de planejamento e as rules: por artifact. A maneira mais fácil de ensinar o OpenSpec sobre sua stack e convenções. Veja Customization.

Context injection. Colocar o contexto do projeto no campo context: do config.yaml para que seja adicionado automaticamente a cada artifact gerado pela IA. Mais confiável do que esperar que a IA leia um arquivo separado.

Dependency graph. O grafo direcionado formado pelas relações requires: dos artifacts. É um DAG (grafo acíclico direcionado: as setas apontam apenas para frente, nunca em loop), e o OpenSpec usa isso para saber o que você pode criar a seguir.

Enablers, not gates. O princípio de que as dependências dos artifacts mostram o que se torna possível a seguir, não o que é obrigatório a seguir. Você pode revisar e editar qualquer artifact a qualquer momento. Veja Core Concepts at a Glance.

Coordenação entre repositórios (beta) ​

Estes termos aplicam-se apenas se o seu planejamento abranger mais de um repositório. Eles estão em beta. A maioria dos usuários pode ignorá-los. Veja o Stores User Guide.

Store. Um repositório independente cuja única função é o planejamento. Ele tem a mesma estrutura openspec/ que você já conhece (specs e changes) mais um pequeno arquivo de identidade. Você o registra em sua máquina uma vez, por nome, e então qualquer comando do OpenSpec pode trabalhar nele de qualquer lugar.

Reference. Uma declaração, no openspec/config.yaml de um repositório de código, de um store que esse repositório utiliza. As references são somente leitura: o repositório mantém sua própria raiz, e openspec instructions ganha um índice dos specs do store referenciado, cada um com o comando exato para buscá-lo.

Working context. O que openspec context monta para o repositório atual: sua raiz do OpenSpec mais todos os stores que ele referencia, cada um com a forma de buscá-lo. A resposta para "com o que estou trabalhando?".

Workset. Um conjunto pessoal e local à máquina de pastas que você abre juntas (um store junto com os repositórios de código com os quais você trabalha). Criado explicitamente com openspec workset create; nada sobre esses caminhos locais é commitado para o repositório de planejamento compartilhado.

Veja também ​