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
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.
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.