Ir para o conteúdo
Promovaweb

O que é o Specsfy

O Specsfy é um método de desenvolvimento com CLI e skills para agentes de IA. Ele reúne os requisitos do seu app, o plano técnico e as tarefas na mesma especificação, com referências aos testes de cada comportamento.

Referência técnica
Specsfy v0.29.1
Revisão
14 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Uma spec junto do código
  2. O papel da CLI e das skills
  3. O que os testes precisam demonstrar
  4. Os arquivos acompanham o estado
  5. Projeto da Promovaweb

Uma spec junto do código

A spec.md descreve uma alteração escolhida para o app, com o comportamento esperado e os limites da mudança. O plano técnico explica os arquivos afetados e as tarefas apontam para os requisitos que atendem. As referências aos testes permitem conferir o resultado. Você consegue abrir o documento e relacionar uma alteração no código à função que ela precisa cumprir.

O agente lê essa especificação durante o trabalho. Uma resposta na conversa pode esclarecer um campo ou alterar uma condição, mas a definição confirmada precisa entrar no arquivo. Assim, uma nova sessão tem uma referência escrita para retomar a mudança. A continuidade depende da leitura da spec atual, em vez de exigir que você repita toda a conversa que produziu o plano.

O Specsfy mantém o plano e as tarefas dentro da própria spec.md, junto dos requisitos que descrevem o comportamento do app. O plano explica a construção técnica necessária para atender a essa definição. Cada tarefa delimita uma ação verificável pelo caminho do arquivo afetado e pelas referências ao comportamento correspondente. Você pode acompanhar a alteração do formulário até o requisito que descreve a resposta esperada da aplicação.

  • projeto/Código do seu app e documentos do desenvolvimento.
  • .specsfy/Templates e instruções do framework.
  • specs/inbox/Ideias preservadas para tratamento posterior.
  • specs/draft/0001-recuperar-senha/spec.mdExemplo de uma mudança ainda em definição.
A especificação fica no repositório do app. A pasta indica a etapa atual e a spec reúne a definição, o plano e as tarefas.

O papel da CLI e das skills

A CLI é o programa specsfy executado no terminal. Ela instala o framework no projeto, consulta especificações e executa verificações. A versão de referência v0.29.1 usa um binário compilado com runtime embutido. O pacote distribuído pelo npm baixa o executável da plataforma. Você também encontra o binário nos downloads oficiais, sem precisar de Node.js para executá-lo diretamente.

As skills orientam o agente durante cada etapa, começando pela definição do comportamento com a specsfy-03-specify. Quando essa definição está conferida, a specsfy-05-tasks escreve o plano e as tarefas correspondentes. Se uma nova informação altera o trabalho, o agente informa a transição e retoma a atividade adequada ao estado da especificação. Uma mudança de permissão, por exemplo, precisa voltar à definição para atualizar o comportamento esperado.

Você continua usando o agente no ambiente de desenvolvimento. O Specsfy fornece os documentos e os procedimentos que ele consulta, além das verificações executáveis da CLI. O código do app continua no repositório do app. O runner de testes também continua sendo o da stack utilizada, com os resultados relacionados aos requisitos da spec.

O que os testes precisam demonstrar

Um comportamento escrito recebe exemplos verificáveis. Na recuperação de senha usada pela documentação, a resposta do sistema precisa respeitar a privacidade do cadastro. A descrição do cenário registra uma condição inicial, a ação executada e a resposta esperada. Você consegue discutir esse resultado sem começar pela escolha de uma biblioteca ou pela implementação de um formulário.

O desenvolvimento orientado por comportamento, conhecido como BDD, descreve esses cenários. O desenvolvimento orientado por testes, conhecido como TDD, leva o comportamento a testes executáveis no projeto. O primeiro resultado esperado é uma falha causada pela funcionalidade ausente. Depois da implementação, o teste precisa passar. Uma dependência ausente ou um erro de sintaxe não demonstra a ausência da funcionalidade.

Os gates verificam se cada etapa dispõe do trabalho necessário para avançar. A definição passa pelo Definition Gate e orienta o planejamento, cujo Plan Gate também depende da preparação dos testes. O Delivery Gate reúne a comprovação atual da implementação para revisão. Você pode acompanhar a proporção de tarefas concluídas pelo percentual de progresso, mas o aceite depende da leitura dos resultados que demonstram o comportamento descrito.

Os arquivos acompanham o estado

A pasta da spec mostra a etapa do trabalho, como draft, planned ou review. O campo Status do documento corresponde a essa pasta. Na v0.29.1, o comando specsfy specs transition coordena a movimentação e a atualização do estado. Essa correspondência permite localizar as especificações em revisão sem abrir cada arquivo para descobrir sua situação.

Uma mudança de comportamento pode exigir uma nova definição e novos testes. A skill specsfy-update-spec incorpora a alteração ao documento existente e identifica quais verificações precisam ser refeitas. O histórico concluído permanece separado das mudanças em andamento. Você consulta o resultado anterior sem confundi-lo com uma nova funcionalidade ainda em construção.

Projeto da Promovaweb

A Promovaweb mantém o Specsfy sob licença AGPL 3.0. A documentação completa apresenta a instalação e a referência dos comandos. O portal explica a função das peças para você reconhecer o que aparece no projeto e entender a relação entre uma ideia e o trabalho que o agente executa.

Essa relação também faz parte do desenvolvimento com IA apresentado na Formação Vibe Coding. Para um app cujo escopo e arquitetura precisam de acompanhamento técnico, o Diagnóstico de Produto e Arquitetura da Dev Side Studio oferece um caminho de conversa sobre essas definições. A especificação registra as escolhas confirmadas para orientar a implementação.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.