OpenSpec

Perguntas frequentes ​

Respostas rápidas para as perguntas mais comuns. Se sua dúvida é na verdade algo quebrado, a página Resolução de problemas é mais adequada. Se você quer uma definição de termo, veja o Glossário.

O básico ​

O que é o OpenSpec, em uma frase? ​

Uma camada leve que faz você e seu assistente de codificação de IA concordarem por escrito sobre o que será construído, antes de qualquer código ser escrito.

Por que eu iria querer isso? ​

Porque assistentes de IA são confiantes mesmo quando estão errados. Quando os requisitos ficam apenas no histórico do chat, a IA preenche lacunas com suposições, e você só descobre depois que o código já existe. O OpenSpec antecipa o acordo para um momento em que erros são baratos de corrigir. Veja Conceitos essenciais de relance para o caso completo.

Preciso usá-lo para tudo? ​

Não. Use onde o acordo é importante, ou seja, na maior parte do trabalho não trivial. Para corrigir um erro de digitação de um caractere, a cerimônia provavelmente não vale a pena, e tudo bem.

Posso usá-lo em uma base de código grande já existente ou apenas em projetos novos? ​

Bases de código existentes são o foco principal. O OpenSpec é voltado para projetos brownfield: você não documenta todo o aplicativo de antemão. Você escreve especificações apenas para o que cada mudança afeta, e suas especificações são preenchidas ao longo do tempo em torno do trabalho que você de fato realiza. Há um guia dedicado: Usando o OpenSpec em um projeto existente.

Ele é vinculado a uma única ferramenta de IA? ​

Não. O OpenSpec funciona com mais de 30 assistentes, incluindo Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex e outros. A lista completa e detalhes por ferramenta estão em Ferramentas suportadas.

Executando comandos ​

Onde digito /opsx:propose? ​

No chat do seu assistente de IA, e não no terminal. Este é o ponto de confusão mais comum, então ele tem sua própria página: Como os comandos funcionam. Resumindo: openspec ... é executado no terminal, /opsx:... é executado no chat.

Como eu "inicio o modo interativo"? ​

Não há um modo separado para iniciar. Você abre seu assistente de IA normalmente e digita um comando com barra no chat. O comando com barra é a forma de "entrar" no OpenSpec. (O único recurso realmente interativo do terminal é o openspec view, um painel para navegar por especificações e mudanças.) Explicação completa em Como os comandos funcionam.

Digitei um comando com barra e nada aconteceu. Por quê? ​

Provavelmente você digitou no terminal em vez do chat da IA, usou uma grafia que sua ferramenta não reconhece ou os comandos ainda não estão instalados. Se os arquivos estiverem ausentes — ou você nunca configurou a ferramenta — execute openspec init; openspec update apenas atualiza arquivos que já existem. Em seguida, reinicie o assistente e use a forma impressa em "Primeiros passos" — veja Como invocar. A página Resolução de problemas tem a lista de verificação completa.

Por que a sintaxe é /opsx:propose em uma ferramenta e /opsx-propose em outra? ​

Cada ferramenta de IA expõe comandos personalizados de forma ligeiramente diferente, e o OpenSpec os escreve conforme a ferramenta carrega o arquivo que gerou. Um arquivo de comando chamado opsx-propose.md é digitado como /opsx-propose; um arquivo dentro de commands/opsx/ é digitado como /opsx:propose. Ferramentas que usam skills em vez de comandos usam o nome da skill — Codex precisa de $openspec-propose, Kimi Code de /skill:openspec-propose. A linha "Primeiros passos" do openspec init já imprime a forma correta para as ferramentas que você escolheu; a tabela completa está em Como invocar.

Qual é a diferença entre uma skill e um comando? ​

Ambos são arquivos que o OpenSpec gera para que seu assistente possa executar o fluxo de trabalho. As skills (.../skills/openspec-*/SKILL.md) são o padrão mais recente e multi-ferramenta; os comandos (.../commands/opsx-*) são os arquivos de barra mais antigos, específicos por ferramenta. Você não precisa escolher. Basta digitar o comando com barra, e o OpenSpec instala o que sua ferramenta usar.

O fluxo de trabalho ​

Por onde devo começar se não tenho certeza do que construir? ​

Com o /opsx:explore. É um parceiro de raciocínio sem riscos que lê sua base de código, apresenta opções e transforma um problema vago em um plano concreto, tudo antes de qualquer mudança ou código existir. Está no perfil padrão, então está sempre disponível. Quando o plano está claro, ele repassa para o /opsx:propose. Este é o melhor hábito a se formar, porque impede que uma IA ansiosa construa confiantemente a coisa errada. Veja Explorar primeiro.

Qual é o fluxo mais simples possível? ​

text
/opsx:explore (opcional)   depois   /opsx:propose <o que você quer>   depois   /opsx:apply   depois   /opsx:archive

Explore para pensar, proponha para esboçar o plano, aplique para construir, arquive para guardar. Pule o explore quando já souber exatamente o que quer.

Qual é a diferença entre /opsx:propose e /opsx:new? ​

/opsx:propose é o comando padrão de uma etapa: ele cria a mudança e gera todos os artefatos de planejamento de uma só vez. /opsx:new faz parte do conjunto expandido e apenas monta o esqueleto de uma mudança vazia, deixando você criar os artefatos um de cada vez com /opsx:continue (ou todos de uma vez com /opsx:ff). Use propose, a menos que queira controle passo a passo. Veja Comandos.

O que são os perfis core (básico) e expandido? ​

Um perfil decide quais comandos com barra são instalados. O perfil básico (padrão) oferece propose, explore, apply, update, sync, archive. O conjunto expandido acrescenta new, continue, ff, verify, bulk-archive e onboard para um controle mais fino. Alterne com openspec config profile e depois aplique com openspec update.

Preciso executar /opsx:sync? ​

Normalmente, não. O sync mescla as especificações delta da mudança nas suas especificações principais, e o /opsx:archive se oferece para fazer isso por você. Execute o sync manualmente apenas quando quiser as especificações mescladas antes de arquivar, por exemplo, em uma mudança de longa duração. Veja Comandos.

Como edito uma proposta, especificação ou tarefa depois de ter começado? ​

Basta editar o arquivo. Todo artefato é Markdown simples em openspec/changes/<nome>/, e não há fase bloqueada ou modo especial de edição. Altere à mão ou peça para sua IA revisar ("atualize o design para usar uma fila") e depois continue. A IA sempre trabalha a partir do conteúdo atual do arquivo. Guia completo: Editando e iterando sobre uma mudança.

Posso voltar e alterar o plano depois de implementar uma parte? ​

Sim, a qualquer momento. O fluxo de trabalho é fluido, então revisão e edição não são fases das quais você é excluído. Edite o artefato e continue. Se quiser uma verificação estruturada de que o código ainda corresponde ao plano, execute /opsx:verify. Veja Editando e iterando sobre uma mudança.

Editei o código manualmente. Como concilio isso com a especificação? ​

Recoloque-os em sincronia antes de arquivar, pois o arquivamento torna suas especificações o registro da verdade. Se o código agora está correto, atualize a especificação delta para corresponder ao que você entregou; se a especificação está correta, continue construindo até o código concordar. O /opsx:verify revela as discrepâncias. Veja Editando e iterando sobre uma mudança.

Quando devo atualizar uma mudança existente em vez de começar uma nova? ​

Atualize quando é o mesmo trabalho, apenas refinado. Comece do zero quando a intenção mudou fundamentalmente ou o escopo explodiu em um trabalho diferente. Há um fluxograma de decisão e exemplos em Fluxos de trabalho.

E se minha sessão ficar sem contexto ou os requisitos mudarem no meio da implementação? ​

É aí que as especificações mostram seu valor. Como o plano vive em arquivos (não apenas no histórico do chat), você pode limpar o contexto, iniciar uma nova sessão de IA e continuar com /opsx:apply; ele lê os artefatos e retoma a partir da primeira tarefa não concluída. Se os requisitos mudarem, edite os artefatos para corresponder à nova realidade e continue. Manter uma janela de contexto limpa também produz melhores resultados; limpe-a antes da implementação.

Devo fazer commit da pasta openspec/ no git? ​

Sim. Suas especificações, mudanças ativas e arquivo fazem parte do histórico do seu projeto. Faça commit deles como qualquer outro código-fonte. O arquivo, em particular, torna-se um registro duradouro do porquê seu sistema funciona da maneira que funciona.

Especificações e mudanças ​

O que vai em uma especificação e o que vai em um design? ​

Uma especificação descreve o comportamento observável: o que o sistema faz, suas entradas, saídas e condições de erro. Um design descreve como você vai construí-lo: a abordagem técnica, decisões de arquitetura, mudanças de arquivos. Se a implementação pudesse mudar sem alterar o comportamento externamente visível, isso pertence ao design, não à especificação. Conceitos aprofunda o assunto.

O que é uma especificação delta? ​

Uma especificação que descreve apenas o que está mudando, usando seções ADDED (ADICIONADO), MODIFIED (MODIFICADO) e REMOVED (REMOVIDO), em vez de reafirmar toda a especificação. É assim que o OpenSpec lida com edições em sistemas existentes de forma limpa. Veja Conceitos.

Para onde vão as mudanças arquivadas? ​

Para openspec/changes/archive/YYYY-MM-DD-<nome>/, com todos os artefatos da mudança preservados. A mudança sai da sua lista ativa. Uma mudança que declare explicitamente retire_capabilities: true também pode excluir uma especificação de capacidade principal quando remove o último requisito dessa capacidade.

Configuração e personalização ​

Como informo à IA sobre minha pilha de tecnologia? ​

Coloque em openspec/config.yaml sob context:. Esse texto é injetado em todas as solicitações de planejamento, para que a IA sempre conheça sua pilha e convenções. Veja Personalização.

Posso gerar especificações em um idioma diferente do inglês? ​

Sim. Adicione uma instrução de idioma ao context: da sua configuração. Múltiplos idiomas tem trechos prontos para copiar e colar para vários idiomas.

Posso mudar o próprio fluxo de trabalho? ​

Sim, com esquemas personalizados. Um esquema define quais artefatos existem e como eles dependem uns dos outros. Faça um fork do padrão com openspec schema fork spec-driven meu-fluxo, depois edite-o. Veja Personalização.

Modelos, privacidade e atualizações ​

Qual modelo de IA devo usar? ​

O OpenSpec funciona melhor com modelos de alto raciocínio. O README recomenda modelos como Codex 5.5 e Opus 4.7 tanto para planejamento quanto para implementação. Além disso, mantenha sua janela de contexto limpa: limpe-a antes da implementação para obter melhores resultados.

O OpenSpec coleta dados? ​

Ele coleta estatísticas de uso anônimas: apenas nomes de comandos e versão. Sem argumentos, caminhos, conteúdo ou dados pessoais, e é desativado automaticamente em CI. Desative com export OPENSPEC_TELEMETRY=0 ou export DO_NOT_TRACK=1.

Como faço para atualizar? ​

Dois passos. Atualize o pacote (npm install -g @fission-ai/openspec@latest) e execute openspec update dentro de cada projeto para atualizar as skills e comandos gerados.

Como desinstalo o OpenSpec? ​

Não há um comando de desinstalação, porque é apenas um pacote global mais arquivos no seu projeto. Remova o pacote (npm uninstall -g @fission-ai/openspec) e, opcionalmente, exclua o diretório openspec/ e os arquivos de ferramentas gerados. O passo a passo, incluindo o que é seguro manter, está em Instalação: Desinstalando.

Obtendo ajuda ​

Onde faço perguntas ou relato bugs? ​

Esta documentação está errada ou confusa. O que faço? ​

Avise-nos ou corrija você mesmo. Pull requests para a documentação são bem-vindos e valorizados. Abra uma issue ou envie um pull request.