Exemplos e Receitas

Mudanças reais, do início ao fim. Cada receita mostra os comandos que você digitaria e o que veria em resposta, para que você possa comparar sua situação com um padrão e copiá-lo. Estas usam os comandos padrão core (propose, explore, apply, update, sync, archive); onde o conjunto expandido ajuda, isso é anotado.

Um lembrete antes de começar: comandos com barra como /opsx:propose vão no chat do seu assistente de IA, e os comandos openspec vão no seu terminal. Se isso é novo, leia primeiro Como os Comandos Funcionam. Nos transcritos abaixo, Você: e IA: são o chat, e linhas começando com $ são o terminal.

Não tem certeza do que está construindo ainda? A maioria destas receitas fica mais precisa se você começar com /opsx:explore para pensar antes. A Receita 3 mostra isso em ação, e o guia Explore Primeiro faz o caso completo.

Receita 1: Um recurso pequeno, o caminho rápido

Quando usar: você sabe o que quer e é um trabalho contido. Esta é a receita mais comum.

O processo inteiro são três comandos. Propor, construir, arquivar.

Você: /opsx:propose add-logout-button

IA:  Criado openspec/changes/add-logout-button/
     ✓ proposal.md — por quê e o quê
     ✓ specs/      — o novo requisito e seus cenários
     ✓ design.md   — abordagem técnica
     ✓ tasks.md    — checklist de implementação
     Pronto para implementação. Execute /opsx:apply.

Agora leia o plano. Abra a proposta e a spec de delta. Este é o momento para o qual o OpenSpec foi criado: capturar uma suposição errada enquanto ainda é um parágrafo, não 400 linhas de código. Edite qualquer artefato diretamente se algo estiver errado, e então continue.

Você: /opsx:apply

IA:  Trabalhando nos tarefas...
     ✓ 1.1 Adicionar botão de logout no cabeçalho
     ✓ 1.2 Limpar sessão ao clicar
     ✓ 1.3 Adicionar diálogo de confirmação
     Todas as tarefas concluídas!

Você: /opsx:archive

IA:  Arquivando add-logout-button...
     ✓ Especificações mescladas em openspec/specs/auth/spec.md
     ✓ Movido para openspec/changes/archive/2026-06-22-add-logout-button/
     Concluído. Pronto para a próxima mudança.

É isso. O comportamento de logout agora faz parte das suas especificações, e a mudança está arquivada com todo o seu contexto.

Receita 2: Uma correção de bug

Quando usar: algo está quebrado e você quer que a correção seja registrada como uma mudança deliberada de comportamento, não um commit misterioso.

Correções de bug funcionam exatamente como recursos. A diferença está em como você formula a proposta: descreva o comportamento correto, não apenas "corrigir o bug."

Você: /opsx:propose fix-login-redirect-loop

IA:  Criado openspec/changes/fix-login-redirect-loop/
     A proposta captura o comportamento quebrado atual e o
     comportamento pretendido. A spec de delta MODIFICA o
     requisito de redirecionamento para que agora seja preciso e testável.
     Pronto para implementação.

Como a correção é registrada como um requisito MODIFIED com um cenário novo, a próxima pessoa (ou a próxima sessão de IA) vê não apenas que você corrigiu, mas o que "correto" significa. Então /opsx:apply e /opsx:archive como de costume.

Dica: para uma correção, um bom cenário é o teste de regressão em prosa. "DADO um usuário deslogado, QUANDO ele envia credenciais válidas, ENTÃO ele chega ao painel e não é redirecionado novamente." Escreva isso, e a implementação tem um alvo claro.

Receita 3: Explorando antes de se comprometer

Quando usar: você tem um problema mas ainda não tem um plano. Não tem certeza do que construir ou qual abordagem é a certa.

Comece com /opsx:explore. É um parceiro de pensamento sem estrutura e sem artefatos criados. Ele lê sua base de código e ajuda você a decidir.

Você: /opsx:explore

IA:  O que você gostaria de explorar?

Você: As páginas carregam devagar, mas não sei para onde vai o tempo.

IA:  Deixe-me olhar... Encontrei três prováveis culpados:
     1. Imagens grandes e não otimizadas na lista de produtos
     2. Busca de dados síncrona que bloqueia a renderização
     3. Re-renderizações disparadas por mudanças de contexto
     Qual devemos atacar primeiro?

Você: O da busca de dados.

Você: /opsx:propose optimize-product-list-fetching

IA:  Criado a mudança, com uma proposta informada pelo que
     acabamos de descobrir. Pronto para implementação.

A exploração esclarece seu raciocínio antes de você gastar uma mudança nisso. Quando o insight se cristaliza, proponha, e a IA carrega o contexto para frente.

Receita 4: Gerenciando duas mudanças ao mesmo tempo

Quando usar: você está no meio de um recurso e uma correção urgente pula a fila.

Mudanças são pastas independentes, então trabalho paralelo não conflita. Comece a correção, entregue-a, e então retorne ao recurso exatamente de onde parou.

Você: Estou no meio de add-dark-mode, mas preciso corrigir um bug de login agora.

Você: /opsx:propose fix-login-redirect

IA:  Criado openspec/changes/fix-login-redirect/. Pronto para implementação.

Você: /opsx:apply

IA:  Implementada a correção. Todas as tarefas concluídas.

Você: /opsx:archive

IA:  ✓ Arquivado fix-login-redirect.

Você: De volta ao dark mode.

Você: /opsx:apply add-dark-mode

IA:  Retomando add-dark-mode. Continuando na tarefa 2.3: Atualizar Header...

Nomear a mudança em /opsx:apply add-dark-mode é como você aponta a IA para uma mudança específica quando mais de uma está ativa. Como as tarefas rastreiam conclusão em tasks.md, a IA sabe exatamente onde você parou.

Quando várias mudanças ficam prontas ao mesmo tempo, o /opsx:bulk-archive expandido as arquiva juntas e resolve conflitos de especificação verificando o que realmente foi implementado. Veja Workflows.

Receita 5: Um refactor sem mudança de comportamento

Quando usar: você está reestruturando código e o comportamento visível externamente deve permanecer idêntico.

Este é o caso interessante, porque um refactor puro tem nada para adicionar às suas especificações. O contrato de comportamento não muda; apenas a implementação muda. Então o trabalho fica no design e nas tarefas, e a spec de delta fica vazia ou ausente.

Você: /opsx:propose refactor-payment-module

IA:  Criado a mudança. A proposta declara o objetivo (dividir o
     módulo de pagamento, sem mudança de comportamento) e o design captura
     a nova estrutura. Sem mudanças de especificação, já que o comportamento é idêntico.
     Pronto para implementação.

Declare a delta vazia explicitamente definindo skip_specs: true no .openspec.yaml da mudança:

schema: spec-driven
skip_specs: true

Sem o marcador, openspec validate rejeita uma mudança com zero deltas (para que uma fase de specs esquecida ainda seja detectada); com ele, a validação passa e openspec status mostra a etapa de specs como explicitamente pulada em vez de pendente. Se o refactor acabar mudando o comportamento mesmo assim, remova skip_specs do .openspec.yaml e escreva as specs de delta — o validate trata o marcador mais arquivos de spec como um conflito, então o marcador obsoleto não pode permanecer silenciosamente.

Arquivar uma mudança marcada não requer flags extras (não há deltas para mesclar). Independentemente, a flag --skip-specs instrui o comando de terminal a pular a etapa de spec explicitamente:

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

A mesma flag é útil para ferramentas, CI e mudanças apenas de documentação. O princípio: especificações descrevem comportamento, então se o comportamento não mudou, a spec também não deve. Veja Concepts.

Receita 6: Controle passo a passo (comandos expandidos)

Quando usar: uma mudança complexa ou arriscada onde você quer revisar cada artefato antes de avançar.

O /opsx:propose core rascunha tudo de uma vez. Quando você prefere ir um passo de cada vez, ative os comandos expandidos:

$ openspec config profile      # selecionar os workflows expandidos
$ openspec update              # aplicá-los a este projeto

Agora você pode criar a estrutura e construir incrementalmente:

Você: /opsx:new add-2fa

IA:  Criado openspec/changes/add-2fa/. Pronto para criar: proposal.

Você: /opsx:continue

IA:  Criado proposal.md. Agora disponível: specs, design.

Você: /opsx:continue

IA:  Criado specs/auth/spec.md. Agora disponível: design.

Revise cada artefato conforme ele chega, edite livremente e continue quando estiver satisfeito. Quando quiser o restante rascunhado de uma vez, /opsx:ff avança rápido pelos artefatos de planejamento restantes. Antes de arquivar, /opsx:verify verifica que a implementação realmente corresponde às especificações. Veja Workflows.

Receita 7: Aprendendo o ciclo completo na prática

Quando usar: você instalou o OpenSpec e quer sentir o fluxo de trabalho no seu próprio código, não em um exemplo de brinquedo.

Ative os comandos expandidos (veja Receita 6), e então:

Você: /opsx:onboard

IA:  Bem-vindo ao OpenSpec! Vou guiá-lo por uma mudança completa
     usando sua base de código real. Deixe-me escanear por uma pequena
     melhoria segura que podemos fazer juntos...

/opsx:onboard encontra uma melhoria real (pequena), cria uma mudança para ela, implementa-a e arquiva-a, narrando cada passo. Leva de 15 a 30 minutos e deixa você com uma mudança real que você pode manter ou descartar. É a maneira mais suave de aprender. Veja Commands.

Verificando seu trabalho a partir do terminal

A qualquer momento, a partir do seu terminal, você pode inspecionar o estado das coisas:

$ openspec list                      # mudanças ativas
$ openspec show add-dark-mode        # uma mudança em detalhe
$ openspec validate add-dark-mode    # verificar estrutura
$ openspec view                      # painel interativo

Estes são ferramentas de leitura e inspeção. A proposição e a construção ainda acontecem através de comandos com barra no chat. Detalhes completos na referência CLI.

Para onde ir a seguir

• Explore Primeiro: a maneira recomendada de começar quando você não tem certeza
• Workflows: os padrões acima, com orientação de decisão sobre quando usar cada um
• Commands: todos os comandos com barra em detalhe
• Getting Started: o walkthrough canônico da primeira mudança
• Concepts: por que as peças se encaixam da maneira que fazem