Solução de problemas

Soluções concretas para problemas concretos. Cada entrada nomeia um sintoma, explica a causa provável em uma frase e fornece a correção. Se você não encontrar seu problema aqui, o FAQ pode ajudar, e o Discord com certeza ajudará.

Instalação e configuração

openspec: command not found

A CLI não está instalada ou seu shell não consegue encontrá-la. Instale-a globalmente e verifique:

npm install -g @fission-ai/openspec@latest
openspec --version

Se ela foi instalada mas ainda assim não for encontrada, é provável que o diretório binário global do npm não esteja no seu PATH. Execute npm prefix -g para ver onde os pacotes globais residem: no macOS e Linux, os binários estão na pasta bin/ desse diretório, e no Windows eles ficam diretamente nele. Certifique-se de que esse caminho esteja no seu PATH. (npm bin -g foi removido no npm 9.)

Se você usou a instalação assistida por IA, este é o ponto esperado de transição: esse prompt instrui seu assistente a mostrar a alteração no PATH em vez de editar seus arquivos de inicialização do shell diretamente.

"Requires Node.js 20.19.0 or higher"

O OpenSpec roda na versão Node 20.19.0 ou superior. Verifique sua versão e atualize se necessário:

node --version

Se você usar o bun para instalar o OpenSpec, observe que o OpenSpec ainda roda no Node, então você precisa ter o Node 20.19.0+ disponível no seu PATH, independentemente disso. Consulte Instalação.

openspec init não configurou minha ferramenta de IA

O init pergunta quais ferramentas configurar. Se você pulou sua ferramenta ou deseja adicionar outra, basta executá-lo novamente, ou use a forma não interativa:

openspec init --tools claude,cursor

A lista completa de IDs de ferramentas está em Ferramentas Suportadas. Use --tools all para tudo, --tools none para pular a configuração de ferramentas.

Comandos não aparecem

Se /opsx:propose (ou o equivalente da sua ferramenta) não aparecer ou não fizer nada, percorra esta lista. Eles estão ordenados do mais rápido para verificar ao mais lento.

1. Você pode estar no lugar errado. Os comandos slash vão no chat do seu assistente de IA, não no seu terminal. Se você digitou /opsx:propose no seu shell, esse é o problema. Consulte Como os Comandos Funcionam.

2. Regenere os arquivos. A partir da raiz do seu projeto:

   openspec update

   Isso reescreve os arquivos de habilidade e comando para todas as ferramentas que você configurou.

   Os arquivos de instrução vêm da CLI instalada, então uma CLI desatualizada relata tudo como atualizado sem nunca escrever os fluxos de trabalho mais novos. O openspec update agora verifica isso e oferece atualizar — aceite a oferta se vir.

3. Reinicie seu assistente. A maioria das ferramentas procura por habilidades e comandos na inicialização. Uma janela nova frequentemente resolve.

4. Confirme que os arquivos existem. Para o Claude Code, verifique se .claude/skills/ contém pastas openspec-*. Outras ferramentas usam seus próprios diretórios, todos listados em Ferramentas Suportadas.

5. Verifique se você inicializou este projeto. As habilidades são escritas por projeto. Se você clonou um repositório ou mudou de pasta, execute openspec init (ou openspec update) lá.

6. Confirme que sua ferramenta suporta arquivos de comando. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent e o alvo compartilhado .agents não recebem arquivos de comando gerados opsx-*; eles usam invocações baseadas em habilidades, então /opsx nunca fará autocompletar para eles. Digite $openspec-propose no Codex, /skill:openspec-propose no Kimi Code e /openspec-propose nos demais. O alvo compartilhado .agents é neutro em relação ao fornecedor, então /openspec-propose é a forma comum em vez de garantida — se seu assistente não responder a ele, consulte sua própria documentação sobre como invocar uma habilidade. O Amazon Q recebe arquivos de comando, mas os carrega em sua biblioteca de prompts em vez de seu menu slash — digite @opsx-propose lá, não /opsx. A forma de cada ferramenta está listada em Como Invocar.

Trabalhando com alterações

"Change not found"

O comando não conseguiu identificar qual alteração você quis dizer. Nomeie-a explicitamente ou verifique o que existe:

openspec list                    # ver alterações ativas
/opsx:apply add-dark-mode        # nomeie a alteração no chat

Também confirme que você está no diretório do projeto correto.

"No artifacts ready"

Cada artefato já foi criado ou está bloqueado aguardando uma dependência. Veja o que está bloqueando:

openspec status --change <name>

Em seguida, crie a dependência faltante primeiro. Lembre-se da ordem: a proposta habilita especificações e design; especificações e design juntos habilitam tarefas.

openspec validate relata avisos ou erros

A validação verifica suas especificações e alterações quanto a problemas estruturais. Leia a mensagem: ela nomeia o arquivo e o problema.

openspec validate <name>           # validar um item
openspec validate --all            # validar tudo
openspec validate --all --strict   # verificações mais rigorosas, bom para CI
openspec validate --archived       # falhar se alterações arquivadas tiverem tarefas não verificadas

As causas comuns são uma seção obrigatória ausente (como uma especificação sem cenários) ou um cabeçalho delta mal formado. Corrija o arquivo e execute novamente. A referência da CLI documenta o formato de saída.

Uma mensagem merece sua própria nota:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Um requisito MODIFIED substitui todo o bloco de requisitos, então ele deve conter todos os cenários que sobrevivem à alteração, não apenas aqueles que você editou. Copie os cenários nomeados de openspec/specs/<capability-path>/spec.md de volta para o delta, preservando quaisquer diretórios de domínio no caminho. Isso frequentemente aparece em uma alteração mais antiga após a alteração de outra pessoa ter adicionado um cenário ao mesmo requisito — o arquivamento recusa essa alteração de qualquer maneira, e a validação agora diz isso antes de você implementá-la.

A IA criou artefatos incompletos ou incorretos

A IA não tinha contexto suficiente. Algumas alavancas ajudam:

• Adicione contexto do projeto em openspec/config.yaml para que sua pilha e convenções sejam injetadas em cada solicitação. Consulte Personalização.
• Adicione rules: por artefato para orientações que se aplicam apenas, por exemplo, às especificações.
• Forneça uma descrição mais detalhada ao propor.
• Use o /opsx:continue expandido para criar um artefato por vez e revisar cada um, em vez de /opsx:ff fazer todos de uma vez.

O arquivamento não termina ou avisa sobre tarefas incompletas

O arquivamento não bloqueia em tarefas incompletas, mas avisa você, porque arquivar geralmente significa que o trabalho está concluído. Se as tarefas permanecerem propositalmente (você está registrando uma alteração parcial), prossiga. Caso contrário, conclua as tarefas primeiro. O arquivamento também oferecerá sincronizar suas especificações delta nas especificações principais se você ainda não as tiver sincronizado; diga sim, a menos que tenha um motivo para não fazer.

"User force closed the prompt with 0 null"

Algo executou openspec archive onde nada pode responder a uma pergunta — um agente de IA chamando-o de uma ferramenta, um trabalho de CI ou qualquer shell com stdin fechado. O arquivamento faz até três confirmações, e uma inquestionável costumava falhar com essa mensagem bruta.

Passe --yes para respondê-las antecipadamente:

openspec archive <change-name> --yes

Mantenha quaisquer flags que você já estivesse passando — --skip-specs e --no-validate alteram o que o arquivamento faz, então uma execução única com --yes não é o mesmo comando. Versões atuais nomeiam a flag para você e imprimem uma linha Fix: que você pode colar. Se você pretendesse escolher de uma lista, passe o nome da alteração explicitamente: o seletor também precisa de uma resposta.

Se você, em vez disso, executou o arquivamento com sua saída redirecionada para um arquivo ou capturada por uma ferramenta e de fato canalizou uma resposta (printf 'y\n' | openspec archive …), versões mais antigas escreviam códigos de escape do terminal nessa captura enquanto desenhavam o prompt — em alguns ambientes o suficiente para inflar o arquivo gravemente. Versões atuais leem as confirmações como texto simples sempre que stdout não é um terminal, e um openspec archive sem argumentos (que caso contrário desenharia um seletor de alteração interativo) pede que você passe um nome de alteração antecipadamente em vez de renderizar um menu na captura. De qualquer forma, execuções redirecionadas e de agentes permanecem limpas; passar --yes (com um nome de alteração) pula as confirmações inteiramente.

Configuração

Meu config.yaml não está sendo aplicado

Três suspeitos habituais:

1. Nome de arquivo errado. Deve ser openspec/config.yaml, não .yml.
2. YAML inválido. Execute-o por qualquer validador de YAML; a CLI também relata erros de sintaxe com números de linha.
3. Você esperava uma reinicialização. Você não precisa de uma. As alterações de configuração entram em vigor imediatamente.

"Unknown artifact ID in rules: X"

Uma chave sob rules: não corresponde a nenhum artefato no seu esquema. Para o esquema padrão spec-driven, os IDs válidos são proposal, specs, design, tasks. Para ver os IDs de qualquer esquema:

openspec schemas --json

"Context too large"

O campo context: é limitado a 50KB, propositalmente, porque é injetado em cada solicitação. Resuma-o ou vincule a documentos mais longos em vez de colá-los. Contexto enxuto também produz resultados melhores e mais rápidos.

"Schema not found"

O nome do esquema que você referenciou não existe. Liste o que está disponível e verifique a ortografia:

openspec schemas                    # listar esquemas disponíveis
openspec schema which <name>        # ver de onde um esquema é resolvido
openspec schema init <name>         # criar um personalizado

Consulte Personalização.

Migração do fluxo de trabalho legado

"Legacy files detected in non-interactive mode"

Você está em CI ou em um shell não interativo, e o OpenSpec encontrou arquivos antigos para limpar, mas não pode perguntar a você. Aprovar automaticamente:

openspec init --force

Para o Codex, o OpenSpec pode detectar arquivos de prompt gerenciados antigos em $CODEX_HOME/prompts ou ~/.codex/prompts. Essa limpeza é limitada aos nomes de arquivos de prompt legados do Codex na lista permitida do OpenSpec, e o openspec init não interativo remove apenas os arquivos cujas habilidades de substituição .agents/skills/openspec-* existem. O openspec update não interativo deixa toda a limpeza legacy intocada, a menos que você passe --force.

Comandos não apareceram após a migração

Reinicie sua IDE. As habilidades são detectadas na inicialização. Se elas ainda não aparecerem, execute openspec update e verifique os locais dos arquivos em Ferramentas Suportadas.

Meu antigo project.md não foi migrado

Isso é intencional. O OpenSpec nunca exclui project.md automaticamente porque ele pode conter contexto que você escreveu. Mova as partes úteis para a seção context: do config.yaml, depois exclua-o você mesmo. o Guia de Migração percorre isso, incluindo um prompt que você pode entregar à sua IA para fazer a destilação.

Ainda preso?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Do seu terminal: openspec feedback "what went wrong" abre uma issue para você.

Ao relatar um problema, inclua sua versão do OpenSpec (openspec --version), sua versão do Node (node --version), sua ferramenta de IA e o comando e saída exatos. Isso torna a ajuda muito mais rápida.