Spec-Driven Development: Tática
Índice
- Escopo deste fluxo
- Workflow com fases interativas por feature
- Fase 0: Pesquisa, exploração e prototipagem
- Fase 1: Especificação (
/speckit.specify) - Fase 2: Planejamento técnico (
/speckit.plan) - Fase 3: Detalhamento de tarefas (
/speckit.tasks) - Fase 4: Implementação (
/speckit.implement) - Fase 5: Arquivamento (
/archive) — extensão deste fluxo
Escopo deste fluxo
A documentação oficial do Spec Kit define o fluxo principal como Spec → Plan → Tasks → Implement. Os comandos exatos podem variar conforme a versão e a integração com o agente. Verifique a instalação local com specify integration list antes de tratar este documento como instrução executável.
As etapas de pesquisa anterior à especificação e de preservação de aprendizados depois da entrega são extensões propostas neste documento. Elas não fazem parte do fluxo principal do Spec Kit.
Workflow com fases interativas por feature
Fase 0: Pesquisa, exploração e prototipagem
Esta é uma etapa anterior ao Spec Kit. Use-a quando ainda houver incerteza sobre o problema, as necessidades do usuário ou a viabilidade técnica. A pesquisa pode incluir documentação, código existente, alternativas e protótipos descartáveis.
O resultado não é software pronto nem uma especificação validada. É um conjunto rastreável de fatos, hipóteses, restrições e questões abertas que servirá de entrada para a especificação. Um artefato possível é uma feature request ou issue, por exemplo feature-request-login-social.md.
Fase 1: Especificação (/speckit.specify)
O comando /speckit.specify gera uma especificação centrada no que precisa ser construído e por quê. Na configuração padrão descrita pelo projeto, ele cria uma branch e um diretório de feature com spec.md. Confirme esse comportamento na versão e na integração instaladas.
A especificação deve manter decisões de implementação fora dos requisitos, tornar critérios de sucesso verificáveis e deixar incertezas visíveis. Algumas versões e templates usam [NEEDS CLARIFICATION: pergunta]; o comando opcional /speckit.clarify ajuda a resolver áreas subespecificadas antes do planejamento.
Revise o arquivo gerado antes de continuar. A existência de spec.md não o transforma automaticamente em fonte da verdade: requisitos ainda podem estar incompletos, contraditórios ou diferentes da necessidade real.
Fase 2: Planejamento técnico (/speckit.plan)
O comando /speckit.plan transforma a especificação em uma proposta de implementação. Dependendo do template e das necessidades da feature, os artefatos podem incluir plan.md, research.md, data-model.md, quickstart.md e arquivos em contracts/.
A constituição do projeto fornece critérios para avaliar o plano, mas não garante simplicidade, modularidade ou ausência de duplicação. Antes de aprovar, verifique:
- se cada decisão responde a um requisito;
- quais alternativas foram rejeitadas e por quê;
- se contratos e modelos são compatíveis com o sistema existente;
- quais riscos de segurança, migração e operação permanecem;
- como a implementação será testada e revertida.
Fase 3: Detalhamento de tarefas (/speckit.tasks)
O comando /speckit.tasks decompõe o plano em tasks.md. Esta fase prepara o trabalho; ela não implementa a funcionalidade.
No formato padrão, [P] indica tarefas que podem ser executadas em paralelo porque não possuem dependência direta. Isso não significa que subagentes serão usados automaticamente nem que o paralelismo reduzirá tempo ou tokens. Confirme dependências, caminhos de arquivo, critérios de conclusão e pontos de integração antes de executar.
Quando disponíveis, /speckit.checklist pode apoiar a revisão dos requisitos e /speckit.analyze pode procurar inconsistências entre spec.md, plan.md e tasks.md. A análise também precisa ser revisada; ela não substitui os testes da implementação.
Fase 4: Implementação (/speckit.implement)
O comando /speckit.implement orienta o agente a executar as tarefas. Para features grandes, limite cada execução a um subconjunto explícito de tarefas e revise o estado antes de continuar. A própria documentação sobre features complexas alerta que agentes podem perder o plano ou ignorar tarefas quando uma implementação longa esgota o contexto.
O comando não garante aderência à especificação, segurança ou qualidade. Antes do merge, valide no mínimo:
- critérios de aceitação e testes automatizados relevantes;
- mudanças não previstas no plano;
- tratamento de dados, permissões e segredos;
- compatibilidade e migração;
- observabilidade e procedimento de rollback;
- revisão humana proporcional ao impacto da mudança.
Fase 5: Arquivamento (/archive) — extensão deste fluxo
O arquivamento é uma etapa autoral deste modelo de SDD, posterior ao fluxo principal do Spec Kit. O comando customizado speckit.archive.run consolida os artefatos da feature e os aprendizados que devem permanecer disponíveis depois do merge. Ele não deve ser confundido com um comando padrão distribuído pelo Spec Kit.
O objetivo é reduzir a divergência entre a memória canônica do projeto e o que foi implementado. Para isso, a etapa deve:
- comparar
spec.md,plan.mdetasks.mdcom a alteração integrada; - registrar decisões que continuem válidas, desvios e limitações;
- preservar lições relevantes para manutenção ou reconstrução;
- atualizar os arquivos aplicáveis em
.specify/memory/; - vincular os registros ao pull request, aos testes e à especificação de origem;
- produzir um relatório com os caminhos alterados e pendências encontradas.
Antes de arquivar, confirme que o merge ocorreu e que as validações exigidas pelo projeto passaram. Depois, revise o relatório e o diff da memória. O comando melhora a rastreabilidade, mas não garante sozinho que a memória permaneça fiel ao código; mudanças futuras ainda precisam atualizar os artefatos correspondentes.
