O fluxo de especificação
Uma mudança no app precisa de uma definição que o agente consiga consultar durante a implementação. O fluxo do Specsfy mantém o comportamento esperado, o plano e as tarefas na mesma spec, com testes que permitem comparar o código com o que você aprovou.
- Referência técnica
- Specsfy v0.29.1
- Revisão
- 14 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
A ideia na Inbox e no backlog
A Inbox guarda o texto que você apresenta sem exigir uma definição completa da funcionalidade. O arquivo permanece em specs/inbox/ enquanto precisa de tratamento. Capturar essa ideia não autoriza o agente a implementar código nem cria uma spec automaticamente. Você consegue registrar uma observação durante outro trabalho e continuar a atividade que já estava em andamento.
O backlog recebe uma ideia escolhida para refinamento. Nessa etapa, o agente esclarece o problema e o resultado esperado, com perguntas sobre o que ainda falta definir. A proposta continua separada das especificações escolhidas para implementação. Uma melhoria pode permanecer no backlog enquanto você confirma sua necessidade ou resolve uma dependência do app.
Quando a ideia é promovida, a spec preserva o vínculo com a origem. A referência aponta o texto original que motivou a mudança, mas o comportamento que orienta a construção fica na especificação. A captura processada mantém o texto original e as relações com as specs derivadas. O tratamento da ideia não exige apagar o registro que iniciou a conversa.
Definição e planejamento na mesma spec
A skill specsfy-03-specify desenvolve a definição da mudança. O documento descreve a função esperada e as condições que você consegue verificar. A validação procura contradições ou lacunas que impedem o planejamento. O Definition Gate só pode refletir uma definição conferida, com os requisitos e os cenários correspondentes registrados na spec.
O planejamento utiliza essa definição para explicar como o app muda. A skill specsfy-05-tasks escreve as tarefas dentro do mesmo documento. Uma tarefa registra uma ação e o caminho afetado, com referências aos requisitos que atende. As dependências indicam qual trabalho precisa estar pronto para que outra tarefa possa começar com as condições necessárias.
Definir
$specsfy-03-specifyEscreve o comportamento e as condições de aceite.
Planejar
$specsfy-05-tasksRelaciona arquivos e tarefas aos requisitos.
Implementar
$specsfy-07-implementExecuta o trabalho e registra os resultados dos testes.
O plano também prepara os testes. O comportamento descrito nos cenários precisa corresponder a verificações executáveis na stack do app. Essa passagem exige interpretar a condição de aceite, identificar o componente afetado e observar uma falha causada pela função ausente. O Plan Gate depende dessa preparação, além da descrição técnica da implementação.
A falha esperada e o código que a corrige
O ciclo RED, GREEN e REFACTOR descreve a relação entre teste e implementação. No RED, o teste falha porque o comportamento ainda não está presente. No GREEN, o código implementa a função necessária para o teste passar. A refatoração reorganiza o código preservando o comportamento verificado, com a suíte executada para conferir o resultado.
Você consegue distinguir uma funcionalidade ausente de um ambiente incompleto pelo motivo da falha. Um teste que não abre o banco porque falta configuração não verifica a resposta de uma função. A preparação precisa corrigir esse problema para que o resultado mostre a ausência do comportamento pretendido. O terminal vermelho, isoladamente, não comprova o RED esperado pelo método.
A implementação segue as tarefas relacionadas aos requisitos. Cada resultado precisa indicar o que foi executado e qual parte da spec ele confere. A regressão verifica o comportamento existente que pode ser afetado pela alteração. Quando a documentação do app muda, ela também acompanha a implementação para que a referência de uso corresponda ao sistema atual.
As pastas mostram a etapa atual
A spec começa em draft e chega a defined quando sua definição é conferida. O planejamento leva a mudança a planned, enquanto a implementação utiliza in-progress. A pasta review guarda o trabalho que aguarda aceite e completed preserva o resultado concluído. O campo Status acompanha essa posição. Na v0.29.1, specsfy specs transition mantém o cabeçalho e o diretório alinhados para que você encontre a mesma etapa nas duas consultas.
O estado review indica que a implementação passou pela verificação correspondente e aguarda o aceite final. A conclusão em completed preserva o histórico da mudança aceita. Essa separação permite identificar trabalho tecnicamente conferido que ainda precisa da revisão prevista, sem apresentar como concluída uma função que você ainda está avaliando.
Uma alteração de comportamento exige rever a definição. Uma alteração da construção técnica pode afetar o plano e os testes. A skill specsfy-update-spec incorpora a nova informação e identifica as verificações que perderam validade. O fluxo retorna à etapa afetada para que uma comprovação antiga não seja usada como confirmação de um comportamento diferente.
Acompanhar sem conduzir cada comando
O agente anuncia as transições entre as skills e explica a pendência que motivou o retorno. Você participa das definições que alteram a funcionalidade e acompanha o resultado registrado. A consulta de progresso lê a spec para mostrar o estado e os itens restantes, mantendo a referência no repositório do app.
A referência do método detalha os estados e os gates. O conteúdo que permanece em cada arquivo está em artefatos. Para discutir a sequência de construção do seu app com acompanhamento técnico, o Diagnóstico de Produto e Arquitetura da Dev Side Studio trabalha essas definições junto do escopo.