Ir para o conteúdo
Promovaweb

Requisitos, plano e tarefas

Ao retomar uma mudança com outra sessão do agente, você precisa preservar o comportamento aprovado e o trabalho já feito. A spec reúne essa definição, o plano e as tarefas num documento, enquanto os arquivos do projeto descrevem a estrutura do app para orientar a implementação.

Referência técnica
Specsfy v0.29.1
Revisão
14 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. O que fica dentro da spec
  2. Requisito, cenário e teste
  3. Tarefas com caminho e dependência
  4. Informações que permanecem entre mudanças
  5. Milestones e documentação de uso

O que fica dentro da spec

A spec.md orienta uma mudança escolhida para o app. A definição apresenta o comportamento esperado e o plano descreve a construção técnica necessária. As tarefas dividem esse trabalho em ações verificáveis ligadas aos requisitos. Esses conteúdos permanecem em seções do mesmo arquivo, sem criar um plan.md ou um tasks.md paralelo.

Você identifica a spec pelo número e pelo assunto no nome da pasta, enquanto o diretório de estado indica a etapa atual do desenvolvimento. No caminho specs/draft/0001-recuperar-senha/spec.md, por exemplo, a recuperação de senha ainda está em definição. Quando ela avança para outra pasta, o número e o nome do assunto permanecem disponíveis para localizar a mesma mudança e acompanhar seu histórico.

O cabeçalho registra o estado e as verificações gerais. O restante do documento explica o que levou a esses resultados. A tabela inicial lista as verificações pendentes, mas uma conclusão precisa corresponder ao texto e aos testes registrados. Você consegue conferir o comando executado e a parte do comportamento que ele verifica.

  • projeto/Raiz do app consumidor do Specsfy.
  • PROJECT.mdFinalidade e capacidades do app.
  • .specsfy/STACK.mdTecnologias identificadas no repositório.
  • .specsfy/DATABASE.mdEstruturas de persistência e suas relações.
  • specs/draft/0001-recuperar-senha/spec.mdDefinição, plano e tarefas da mudança escolhida.
A spec descreve uma mudança. Os arquivos permanentes descrevem o projeto e permanecem disponíveis para outras especificações.

Requisito, cenário e teste

Um requisito funcional descreve uma obrigação do sistema. O cenário de aceite mostra uma ação e a resposta esperada em uma condição definida. O teste executa a verificação correspondente no código. A documentação usa identificadores como FR-001 e AC-001 para ligar o requisito ao cenário pelo código de identificação.

Essa relação permite ler a mudança nos dois sentidos. A partir de um requisito, você localiza o cenário e o teste que o cobrem. A partir de um teste, consegue consultar o comportamento que motivou sua existência. Uma função com vários caminhos precisa representar as variações relevantes, incluindo condições de erro que o app precisa tratar.

Os exemplos da spec descrevem comportamento, enquanto os arquivos de teste ficam na estrutura da stack utilizada pelo app. O método não exige transferir a suíte inteira para dentro do documento. A spec mantém a referência e o resultado para que você encontre a verificação executável e entenda sua relação com a funcionalidade.

Tarefas com caminho e dependência

A tarefa identifica uma ação concreta do desenvolvimento pelo caminho afetado e pelas referências que atende. Uma alteração no formulário de recuperação de senha pode depender da definição da resposta do servidor, por exemplo. Essa dependência precisa aparecer no planejamento para orientar a execução. Duas tarefas podem avançar em paralelo quando trabalham em arquivos independentes e já dispõem dos contratos necessários para a implementação.

O checklist acompanha a preparação e a execução da tarefa, com a verificação do resultado. Uma mudança de interface também recebe conferência visual e de interação. O registro precisa explicar os comandos utilizados e os identificadores cobertos. Marcar o item como concluído sem essa relação deixa a revisão sem um caminho para conferir o resultado.

O campo Effort descreve a capacidade de raciocínio e execução necessária. A escala de um a dez não representa horas nem prazo. Uma alteração curta pode envolver uma integração desconhecida, enquanto uma alteração extensa pode seguir um padrão já demonstrado no app. A justificativa registrada explica por que a estimativa recebe aquele valor.

Informações que permanecem entre mudanças

O PROJECT.md descreve a finalidade e as capacidades gerais do app, enquanto o .specsfy/STACK.md reúne as tecnologias estruturais identificadas nas fontes do repositório. Para uma mudança que altera a tabela de clientes, o planejamento consulta também o .specsfy/DATABASE.md, com as estruturas e suas relações. Assim, várias especificações conseguem usar as informações permanentes do sistema sem reescrever a descrição da stack em cada mudança.

As definições da interface também têm arquivos próprios: o INTERFACE.md relaciona os componentes e as telas do sistema, com os padrões de composição e os estados registrados no DESIGNSYSTEM.MD. Ao descrever uma alteração no formulário, a spec consulta essas referências para explicar como a mudança se integra ao app. Você consegue conferir se o novo estado de erro segue o comportamento utilizado nas demais telas.

O setup preserva os trechos humanos existentes. As atualizações automáticas atuam nos blocos delimitados quando o contrato do arquivo prevê esse funcionamento. Uma nova leitura do repositório não autoriza apagar uma definição confirmada. Você consegue manter uma explicação própria ao lado das informações derivadas do código, respeitando o limite de cada bloco.

Milestones e documentação de uso

Uma milestone descreve um estado demonstrável do app. O arquivo correspondente relaciona as specs necessárias para chegar a esse estado. O índice specs.md apresenta a sequência e os vínculos, mas o comportamento de cada mudança continua definido na sua spec.md. O progresso do marco depende das especificações relacionadas e da confirmação da condição de conclusão.

A documentação em docs/ explica o sistema implementado para consulta posterior. Ela acompanha as mudanças aplicáveis, sem assumir o papel da spec que descreve o trabalho em andamento. No guia do Specsfy, os exemplos completos mostram arquivos de uma entrega da aplicação de exemplo, desde o texto original até os resultados dos testes. Para organizar a arquitetura do seu app com orientação técnica, o Diagnóstico de Produto e Arquitetura da Dev Side Studio examina o escopo e a arquitetura que esses documentos descrevem.

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.