Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

OpenSpec

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

OpenSpec é uma ferramenta de linha de comando para Spec-Driven Development que organiza proposta, execução e histórico de cada mudança do projeto em pastas e comandos padronizados.

A ferramenta aplica Spec-Driven Development com poucas etapas e funciona como a parte de planejamento do harness de agentes de código como o Claude Code. Em vez de pedir ao agente que improvise, cada mudança vira uma proposta versionada, com especificação, plano e tarefas, que o agente implementa e depois arquiva. Funciona em qualquer ferramenta capaz de invocar tools, skills e agentes, sem depender de uma IDE específica.

Instalação e o que fica no repositório

É um executável de terminal, com versões para Windows e Linux. Na pasta do projeto, openspec init abre um seletor das ferramentas a suportar, entre elas Claude Code, Codex, Cursor, Continue, Windsurf, Kiro, Antigravity e OpenCode, e dá para marcar mais de uma. A inicialização cria duas coisas: a pasta do OpenSpec, onde as especificações vão ficar e que permanece vazia até a primeira mudança, e, dentro da pasta de configuração do agente, os comandos e as skills do próprio OpenSpec.

Cada mudança traz um arquivo de especificação com cenários de uso no formato de condição e resultado esperado; um de design, com tecnologias, objetivos, não objetivos e decisões; um de proposta, com o porquê da mudança, as novas capacidades e os impactos; e um de tarefas. No arquivo de tarefas, as marcadas com [P] podem rodar em paralelo e são agrupadas em ondas, e o agente abre Subagentes simultâneos para executá-las. Mudanças pendentes ficam numa pasta de changes; as concluídas vão para o arquivo.

O ciclo de comandos

Todos os comandos começam com o prefixo /opsx:. O ciclo essencial tem três passos:

  • propose: gera proposta, especificação, design e tarefas num único passo, juntando o que outras ferramentas separam em especificar, planejar e quebrar em tarefas.
  • apply: implementa as tarefas de uma mudança. Aparece marcado como experimental, porque a ferramenta ainda não chegou à versão 1.0.
  • archive: fecha a mudança quando o resultado está bom e registra as tarefas concluídas no histórico.

Há comandos opcionais. O explore roda antes da proposta: varre o código existente, aponta problemas de dependência, vulnerabilidade e acoplamento e sugere mudanças; o propose já parte de uma ideia definida. O validate confere se a proposta tem pendências. Se uma proposta sair ambígua e ninguém a esclarecer, o agente resolve sozinho ao aplicar, priorizando fazer o código rodar, o que torna a revisão das specs indispensável.

Histórico, retomada e comandos próprios

O archive transforma o repositório numa documentação viva. Um membro novo do time navega pelas mudanças e entende a evolução do projeto, ou pede ao agente um resumo a partir delas. O mesmo registro permite retomar a implementação quando a cota de uso acaba no meio, sem perder o rastreamento do que já foi feito. Vale respeitar a ordem das specs, porque uma pode depender de outra já implementada e testada; ignorar isso vira bola de neve.

O fluxo é extensível. Um comando novo é só um arquivo markdown de instruções para o agente. Um comando de relatório, que analisa os arquivos modificados e escreve um markdown detalhado das mudanças, nasceu assim porque o resumo padrão do agente era raso demais. É o harness evoluindo com a própria ferramenta.

Quando escolher OpenSpec em vez de Spec Kit

O Spec Kit mantém as etapas mais separadas e é indicado para projetos novos e sistemas inteiros. O OpenSpec é mais enxuto e se encaixa em projetos já existentes com mudanças pequenas, ou numa prova de conceito de um ou dois módulos: usar Spec Kit numa alteração pequena é como usar um canhão para matar uma formiga. As duas ferramentas podem conviver no mesmo projeto, mas escolher só uma é considerado mais seguro.