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 devendas 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:
specsfy-02-backlogcompara o relato com itens existentes e pergunta somente o que muda o comportamento, como o resultado correto esperado.specsfy-03-specifycria aspec.mdcom o problema, o resultado esperado e cenários BDD que descrevem o comportamento correto.specsfy-04-validateaprova o Definition Gate.specsfy-05-tasksplaneja a correção e chamaspecsfy-06-tdd-bdd.specsfy-06-tdd-bddcria o teste e observa o RED: o teste precisa falhar porque o defeito existe, não por erro de sintaxe ou ambiente.specsfy-07-implementcorrige, obtém o GREEN e roda a regressão.
Como solicitar:
O desconto de 10% está sendo aplicado duas vezes quando o cupom é usado nocheckout. 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
PageHeaderreutilizado na lista, no detalhe, na criação e na edição, - a listagem em um
DataGridde largura total, com a colunaIDvisí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:
specsfy-mvp-milestone-interviewerconduz a conversa sobre o MVP e define marcos que podem ser demonstrados.specsfy-data-discoveryentra quando a conversa revela informações que o sistema precisa guardar.- A importação do
MVP.mdgera e refina um backlog por item e pode criar specs emDraft, todas comDefinition Gate: Pending. specsfy-milestone-governormantémspecs.mde os arquivosspecs/milestones/MNN.mdalinhados com specs e backlog.- Após o MVP,
specsfy-roadmap-milestone-interviewerplaneja a evolução.
Como solicitar:
Quero criar um sistema de agendamento para clínicas pequenas. Me ajude adefinir 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 onú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:
specsfy-data-discoverypergunta em linguagem simples o que o sistema precisa guardar e registra as respostas confirmadas em.specsfy/DATABASE.md.specsfy-05-tasksinclui uma tarefa[MIGRATION]com arquivo versionado.specsfy-07-implementaplica a migration no banco de teste e registra uma consulta de estado.specsfy-aux-databaseatualiza 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.testingcomAPP_ENV=testinge um banco diferente do.env, - comandos que apagam ou recriam banco são recusados em qualquer situação, como
migrate:fresh,db:wipe,DROP TABLEeTRUNCATE, mesmo com autorização, - testes Laravel usam
DatabaseTransactionsno lugar deRefreshDatabase.
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:
- Instale com
specsfy install --project . --detected. A opção--detectedsugere especialistas pela stack encontrada. - Na primeira skill chamada,
specsfy-setupreconcilia o contexto: cria ou atualizaPROJECT.md,.specsfy/STACK.md,.specsfy/RULES.md,.specsfy/DATABASE.mde o perfil em.specsfy/USER-PROFILE.md. specsfy-documentatorlê o projeto inteiro e reconstróidocs/com arquitetura, banco, fluxos, testes e integrações, além de.specsfy/PACKAGES.md.- 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 adocumentaçã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:
specsfy statusspecsfy progress --spec 0005 --jsonspecsfy progress --watchspecsfy milestones sync --project .specsfy verify --boundary ci --jsonspecsfyO ú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.