Para que serve o Specsfy
O Specsfy registra o comportamento esperado de uma mudança no seu app para orientar o trabalho do agente. Ele relaciona os requisitos às tarefas e aos testes na spec, que você consulta para comparar a implementação com a definição confirmada.
- Referência técnica
- Specsfy v0.29.1
- Revisão
- 14 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O comportamento que você consegue conferir
A recuperação de senha usada como exemplo na documentação tem um resultado visível: o app responde à solicitação sem revelar informações privadas do cadastro. Escrever somente o nome da tela não descreve essa condição. A especificação registra o resultado esperado para que o teste consiga distinguir uma resposta aceitável de outra que informa se o endereço existe no banco.
Você lê a função pelo comportamento que ela apresenta. O plano explica como o agente pretende construir essa função na stack do projeto. Uma tarefa pode alterar o formulário, enquanto outra modifica a resposta do servidor. As duas precisam apontar para a definição correspondente, porque uma tela pronta não comprova o tratamento correto da solicitação no backend.
O Specsfy registra essas relações em uma única spec. Os identificadores permitem acompanhar a ligação entre o requisito e o cenário de aceite. Os testes usam as mesmas referências para indicar qual comportamento verificam. Durante uma revisão, você localiza o teste que corresponde à função alterada pela referência ao cenário de aceite, além do nome do arquivo de código.
Requisito
FR-001Declara o comportamento obrigatório.
Cenário
AC-001Descreve a ação e a resposta esperada.
Teste
SPECSFY:Relaciona a verificação aos identificadores da spec.
Uma conversa que permanece no repositório
As respostas confirmadas durante a definição entram na especificação. Isso inclui o que a mudança cobre e o que fica fora dela. Quando a conversa termina, o documento continua disponível junto do código. O agente consegue retomar o trabalho a partir da definição registrada, mesmo que a sessão anterior tenha terminado ou a conversa esteja longa.
O entrevistador entra quando uma informação ausente altera a próxima etapa, como o comportamento de uma permissão ou o destino de uma ação da interface. Ele consulta a spec e apresenta uma pergunta por vez para esclarecer essa dúvida. Você pode confirmar uma alternativa ou escrever outra resposta para orientar a definição registrada no documento. A entrevista permanece ligada ao comportamento necessário para continuar o desenvolvimento.
Uma ideia recém-capturada recebe tratamento diferente. A Inbox preserva o texto sem iniciar essa entrevista nem autorizar implementação. O backlog permite aprofundar a ideia escolhida para refinamento. Você pode registrar uma observação durante outro trabalho e retomá-la depois, quando tiver interesse em definir a funcionalidade. A criação da spec depende de uma promoção explícita da ideia.
Trabalhar num app que já existe
O setup lê as fontes do projeto para reconhecer a stack e as convenções presentes. Uma aplicação existente já tem rotas, componentes e testes que precisam ser considerados. O capítulo de casos de uso explica a adoção do método em um projeto existente e a retomada de trabalho interrompido. O planejamento usa a leitura do repositório para explicar a alteração proposta, respeitando a stack que o app utiliza.
Você encontra a finalidade do sistema no PROJECT.md e suas tecnologias estruturais no .specsfy/STACK.md. A spec consulta essas informações para descrever uma mudança compatível com o app existente. Ao planejar a recuperação de senha, por exemplo, o agente precisa reconhecer o mecanismo de autenticação já utilizado. A definição da nova função permanece na spec, sem exigir que cada tarefa repita toda a arquitetura do projeto.
Interfaces também fazem parte do comportamento. O método considera o caminho pelos menus e os estados que você vê na tela. Um formulário precisa descrever o que acontece quando está vazio, quando apresenta erro e quando a ação termina. O plano relaciona a interface às tarefas e aos testes, incluindo a interação por teclado.
Testar uma alteração com referência escrita
A preparação dos testes precisa mostrar uma falha pelo motivo esperado. Quando o comportamento ainda não existe, o teste correspondente deve apontar essa ausência. Uma falha causada por configuração incompleta do ambiente exige correção do ambiente. Ela não demonstra que o teste reconhece a função pretendida, mesmo que o terminal mostre um resultado negativo.
Depois da implementação, os testes registram o resultado atual para que a revisão possa relacioná-lo ao aceite e à documentação afetada. Você consegue conferir qual comando foi utilizado e qual comportamento ele cobriu. Como um teste isolado pode passar sem verificar toda a mudança, o método relaciona cada verificação aos requisitos da spec. Essa referência permite localizar uma condição ainda sem teste e avaliar o trabalho que falta.
O percentual de progresso apresenta uma projeção das tarefas ou dos gates. A lista de tarefas indica quais itens continuam pendentes e quais já foram concluídos. A aceitação da funcionalidade continua ligada à leitura dos resultados e ao estado correspondente da spec. Uma barra preenchida não substitui a demonstração da ação funcionando no app.
O limite da especificação
O documento registra o que você confirmou. Ele não fornece automaticamente uma resposta para toda dúvida de negócio nem define uma permissão que ainda está em discussão. Quando uma alteração modifica o comportamento, a spec precisa refletir essa mudança e as verificações afetadas precisam ser repetidas. A consistência depende dessa atualização durante o desenvolvimento.
A documentação do Specsfy detalha os contratos usados pelo método. Para aprender a conduzir o desenvolvimento com agentes, a Formação Vibe Coding oferece continuidade ao tema. Quando você precisa definir o escopo do seu app com acompanhamento técnico, o Diagnóstico de Produto e Arquitetura da Dev Side Studio examina o escopo e a arquitetura descritos na especificação.