Digite para filtrar as páginas da documentação.

    Specsfy

    Casos de uso do Specsfy: receitas para cada situação real

    Veja nove receitas do Specsfy por situação: ideia na Inbox, bug com teste de regressão, CRUD com interface, MVP, banco de dados e projeto existente.

    Escolha o caso pela situação

    Você quer… Caso
    guardar uma ideia sem parar o que está fazendo Anotar uma ideia durante uma reunião
    corrigir um defeito com prova de que ele não volta Corrigir um bug com teste de regressão
    criar uma funcionalidade com telas e formulários Criar um CRUD com interface
    começar um produto do zero Planejar um produto novo pelo MVP
    mudar algo que já foi definido Incluir uma mudança depois da definição
    guardar informações novas no banco Mudar o banco de dados com segurança
    adotar o método em um sistema que já existe Adotar o Specsfy em um projeto existente
    acompanhar várias entregas ao mesmo tempo Acompanhar o andamento do projeto
    retomar um trabalho parado há dias Retomar uma entrega interrompida

    Anotar uma ideia durante uma reunião

    Situação: surgiu uma ideia, uma solicitação de cliente ou uma observação, mas você não quer discutir detalhes agora.

    Caminho: specsfy-01-inbox, uma skill que não faz perguntas. Ela grava o texto original com data, hora e hash de integridade, consulta o contexto do projeto e registra uma análise inicial marcada como inferência.

    Como solicitar:

    Guarde na Inbox: o financeiro pediu para exportar o relatório mensal de
    vendas em CSV, com filtro por vendedor.

    O que fica registrado: um arquivo specs/inbox/AAAA-MM-DD-HHMMSS-exportar-relatorio-vendas.md. O texto original fica intacto, mesmo que tenha erros de digitação.

    Quando a ideia avança: peça para refinar a entrada no backlog. Depois que uma spec cobrir toda a solicitação e passar no Definition Gate, a captura sai da fila ativa e vai para specs/inbox/processed/. Nada é apagado.

    Corrigir um bug com teste de regressão

    Situação: um comportamento está errado e você quer garantir que a correção tenha um teste que falharia sem ela.

    Caminho: o agente percorre as etapas abaixo, anuncia cada transição na conversa e registra o resultado de cada uma na spec da entrega:

    1. specsfy-02-backlog compara o relato com itens existentes e pergunta somente o que muda o comportamento, como o resultado correto esperado.
    2. specsfy-03-specify cria a spec.md com o problema, o resultado esperado e cenários BDD que descrevem o comportamento correto.
    3. specsfy-04-validate aprova o Definition Gate.
    4. specsfy-05-tasks planeja a correção e chama specsfy-06-tdd-bdd.
    5. specsfy-06-tdd-bdd cria o teste e observa o RED: o teste precisa falhar porque o defeito existe, não por erro de sintaxe ou ambiente.
    6. specsfy-07-implement corrige, obtém o GREEN e roda a regressão.

    Como solicitar:

    O desconto de 10% está sendo aplicado duas vezes quando o cupom é usado no
    checkout. Quero corrigir com um teste que comprove o problema.

    O que fica registrado: uma spec com Effort baixo, normalmente entre 1 e 3, tarefas marcadas, a falha observada antes da correção e o teste passando depois dela. A evidência RED mostra a causa da falha, por exemplo: valor total esperado 90,00, recebido 81,00.

    Cuidado: um teste que já passa antes da correção não serve como RED. A skill recusa essa prova e ajusta o caso até ele detectar o defeito.

    Criar um CRUD com interface

    Situação: a entrega cria telas para listar, ver, criar, editar e apagar registros, como um cadastro de clientes.

    Caminho: o mesmo fluxo base, com o contrato de interface ativo. Antes de aprovar a definição, o agente lê o design system do projeto (DESIGNSYSTEM.MD e INTERFACE.md), percorre as telas existentes e pergunta somente as lacunas: telas, navegação, campos, validações, estados de carregamento, vazio, erro e permissão.

    Como solicitar:

    Quero um cadastro de clientes com listagem, detalhe, criação e edição.
    Somente administradores podem apagar.

    O que o método exige de um CRUD:

    • um único PageHeader reutilizado na lista, no detalhe, na criação e na edição,
    • a listagem em um DataGrid de largura total, com a coluna ID visível,
    • a linha inteira funcionando como link para o detalhe, por mouse e teclado,
    • ações independentes de editar e apagar em cada linha, com confirmação antes de apagar e respeito à permissão.

    O que fica registrado: a seção 10 da spec descreve telas, fluxo, formulários, composição e estados. Cada tarefa com interface traz o item VISUAL preenchido com viewport, estados percorridos e ajustes. Componentes novos ou reaproveitados entram em INTERFACE.md.

    Leia Design system de interface para entender as orientações gerais e as exceções com alcance.

    Planejar um produto novo pelo MVP

    Situação: você tem a visão de um produto e quer quebrá-la em entregas demonstráveis antes de escrever código.

    Caminho: o agente percorre as etapas abaixo, anuncia cada transição na conversa e registra o resultado de cada uma na spec da entrega:

    1. specsfy-mvp-milestone-interviewer conduz a conversa sobre o MVP e define marcos que podem ser demonstrados.
    2. specsfy-data-discovery entra quando a conversa revela informações que o sistema precisa guardar.
    3. A importação do MVP.md gera e refina um backlog por item e pode criar specs em Draft, todas com Definition Gate: Pending.
    4. specsfy-milestone-governor mantém specs.md e os arquivos specs/milestones/MNN.md alinhados com specs e backlog.
    5. Após o MVP, specsfy-roadmap-milestone-interviewer planeja a evolução.

    Como solicitar:

    Quero criar um sistema de agendamento para clínicas pequenas. Me ajude a
    definir o MVP e os primeiros marcos.

    O que fica registrado: o MVP com marcos, itens de backlog numerados, specs em rascunho e a projeção em specs.md. Nenhuma spec gerada nessa etapa autoriza implementação: cada uma precisa da sua intenção explícita para avançar.

    Leia Milestones para ver arquivos e sincronização.

    Incluir uma mudança depois da definição

    Situação: a spec já passou no Definition Gate, ou até já foi implementada. Agora surge uma mudança, como um campo novo, uma regra de negócio diferente ou uma remoção.

    Caminho: specsfy-update-spec leva a mudança para a mesma spec.md. A skill classifica o impacto e reabre somente o que perdeu validade:

    Tipo de mudança Atos reabertos Próxima etapa
    muda o comportamento observável I, II e III specsfy-04-validate
    muda apenas o plano técnico II e III specsfy-05-tasks
    falta uma escolha que só você pode fazer permanece em definição specsfy-02-backlog

    Como solicitar:

    Na spec 0003, além do e-mail, o usuário também precisa poder entrar com o
    número do celular.

    O que fica registrado: a spec atualizada, os gates afetados de volta para Pending e uma nova sequência de testes para o comportamento incluído. Nenhum plan.md, tasks.md ou arquivo paralelo é criado.

    Leia Mudanças posteriores para os detalhes.

    Mudar o banco de dados com segurança

    Situação: a entrega cria tabela, campo, relação ou migration.

    Caminho: o agente percorre as etapas abaixo, anuncia cada transição na conversa e registra o resultado de cada uma na spec da entrega:

    1. specsfy-data-discovery pergunta em linguagem simples o que o sistema precisa guardar e registra as respostas confirmadas em .specsfy/DATABASE.md.
    2. specsfy-05-tasks inclui uma tarefa [MIGRATION] com arquivo versionado.
    3. specsfy-07-implement aplica a migration no banco de teste e registra uma consulta de estado.
    4. specsfy-aux-database atualiza o quadro de persistência.

    Como solicitar:

    Os pedidos precisam guardar o código de rastreio e a transportadora.

    Proteções permanentes:

    • nenhum teste roda no banco de desenvolvimento, em Laravel, o projeto precisa de .env.testing com APP_ENV=testing e um banco diferente do .env,
    • comandos que apagam ou recriam banco são recusados em qualquer situação, como migrate:fresh, db:wipe, DROP TABLE e TRUNCATE, mesmo com autorização,
    • testes Laravel usam DatabaseTransactions no lugar de RefreshDatabase.

    O que fica registrado: a migration versionada, DATABASE.md atualizado e a evidência da migration aplicada no banco de teste.

    Adotar o Specsfy em um projeto existente

    Situação: o sistema já existe, tem código e talvez nenhuma documentação. Você quer começar a trabalhar com specs a partir de agora.

    Caminho:

    1. Instale com specsfy install --project . --detected. A opção --detected sugere especialistas pela stack encontrada.
    2. Na primeira skill chamada, specsfy-setup reconcilia o contexto: cria ou atualiza PROJECT.md, .specsfy/STACK.md, .specsfy/RULES.md, .specsfy/DATABASE.md e o perfil em .specsfy/USER-PROFILE.md.
    3. specsfy-documentator lê o projeto inteiro e reconstrói docs/ com arquitetura, banco, fluxos, testes e integrações, além de .specsfy/PACKAGES.md.
    4. Cada mudança nova segue o fluxo base, sem spec retroativa do código antigo.

    Como solicitar:

    Acabei de instalar o Specsfy neste projeto. Prepare o contexto e gere a
    documentação técnica do sistema atual.

    Projetos com GitHub Spec Kit: quando existe .specify/memory/constitution.md, o setup cria .specsfy/SPECKIT.md como uma projeção da constituição e dos arquivos em specs/, sem alterar as fontes do Spec Kit.

    Leia Informações permanentes do projeto e Documentação do sistema.

    Acompanhar o andamento do projeto

    Situação: há várias specs em estados diferentes e você quer saber o que está pronto, o que está parado por dependência e qual é o próximo trabalho.

    Caminho: specsfy-progress na conversa ou o CLI no terminal. Os dois apenas leem as specs, os milestones e o backlog, sem alterar nenhum arquivo do projeto.

    Como solicitar:

    Qual é o estado das specs e o que falta para fechar o milestone M01?

    No terminal:

    Terminal
    specsfy status
    specsfy progress --spec 0005 --json
    specsfy progress --watch
    specsfy milestones sync --project .
    specsfy verify --boundary ci --json
    specsfy

    O último comando abre a TUI, com as abas Overview, Specs, Backlog, Gates, Tests, Skills e About. O formato --json serve para scripts e dashboards. specsfy verify roda todos os gates como etapa da integração contínua. Quando houver skills clickupfy-* instaladas, a transição de estado e o Effort também podem ser sincronizados com uma tarefa do ClickUp, o estado local continua sendo a referência. A tarefa remota fica em próxima etapa até um agente começar a executá-la, passa para em andamento só enquanto ele atua, volta para próxima etapa com comentário quando ele para sem concluir e vai para revisar na entrega. pronto e concluido dependem de ordem humana.

    Retomar uma entrega interrompida

    Situação: você parou no meio de uma entrega e não sabe mais onde parou.

    Caminho: basta solicitar a continuação. O agente relê a spec, os gates, as tarefas e as evidências e escolhe a skill responsável pelo estado encontrado. Se uma tarefa está pela metade, ela é retomada no item do checklist que falta (PREP, EXECUTE, VERIFY, VISUAL, EVIDENCE ou IMPROVE).

    Como solicitar:

    Continue a spec 0005 de onde parou.

    O que esperar: um anúncio como Transição automática: $specsfy-progress → $specsfy-07-implement com o motivo e o resultado esperado, seguido do trabalho na mesma conversa. Se a mesma pendência se repetir sem mudança observável, o agente para e relata o impasse em vez de girar em círculo.

    Combine os casos

    Os casos acima se encaixam. Um produto novo começa pelo MVP, gera specs em rascunho e cada spec segue o fluxo base. Uma mudança de banco ativa as proteções do banco de dados. Uma solicitação tardia volta pela atualização da spec. Para ver todos os arquivos produzidos por uma entrega completa, siga para os Exemplos completos.

    Justificativa de tamanho

    Os casos ficam em uma única página para que você compare caminhos lado a lado e encontre a situação pela tabela inicial. Separar cada caso esconderia como eles se combinam ao longo de um mesmo projeto.

    Planos Promovaweb

    Tire seus projetos do papel

    O Plano Martech cobre automação e atendimento. O Plano IA Makers acrescenta desenvolvimento com IA, enquanto o Plano Founders trata de gestão de negócios. Todos são anuais.

    Plano Martech

    Para conectar automação, marketing e atendimento com infraestrutura própria.

    R$ 897

    R$ 597/ano

    • Grade de automação, atendimento, marketing e análise de indicadores
    • Instalador Exclusivo Promovaweb
    • n8n, Evolution API, Chatwoot e Mautic
    • Trilha DevOps incluída
    • Encontros ao vivo (terça e quinta)
    • Comunidade e acompanhamento
    Conhecer o plano

    Plano Founders

    Plano anual para fazer um projeto de tecnologia avançar, com 90 dias de mentoria intensiva. R$ 1.997 à vista ou até 10x de R$ 219 no cartão.

    R$ 1.997/ano

    • 12 meses de acesso ao Founders
    • 90 dias de mentoria intensiva, um encontro por dia útil
    • Dia de conteúdo (terça e quinta) e War Room (segunda, quarta e sexta)
    • Encontro semanal em grupo após a fase intensiva
    • Formação Vibe Coding incluída no plano anual
    • Consultoria individual de até duas horas (bônus)
    Conhecer o plano