Spec Kit em Full-Stack Real: Como 17 Sprints Levaram o Rastreador de Hábitos para Produção

Spec-Driven Development conseguiu chegar não a uma demo de uma noite, mas a um lançamento full-stack completo. O caso LifeSync descreve 17 sprints de desenvolvimento de um rastreador de hábitos e metas, dois repositórios separados, centenas de testes e um lançamento em produção — e leva à conclusão principal: em larga escala, SDD é valioso não pela velocidade de geração de código, mas por impedir a perda de controle quando backend, frontend e infraestrutura começam a puxar o projeto em direções diferentes. O estudo de caso usa um serviço B2C para hábitos e metas como exemplo.

O backend é construído em Spring Boot 3.5 e Java 21, organizado usando arquitetura hexagonal em seis módulos Maven, usa jOOQ em vez de JPA, Kafka para lógica orientada a eventos, JWT RS256 e OpenAPI 3.1 como contrato de API principal.

O frontend é construído em React 19, TypeScript 5.9, Vite 8, TanStack React Query, Zustand e shadcn/ui com Tailwind CSS. Ao longo de 17 sprints, o projeto cresceu para 251 testes no lado do servidor e 77 testes no lado do cliente, recebeu 19 migrações Liquibase e foi lançado em produção: backend implantado no Railway, frontend no Vercel.

O insight central do caso é que a escala exigiu uma disciplina diferente ao trabalhar com IA. Se um pequeno projeto pudesse se contentar com um chat pensante e um ambiente de execução, o autor chegou a um esquema de três chats para o projeto full-stack. Um contexto separado é necessário para backend, um separado para frontend, e outro para coordenar decisões comuns que afetam ambos os repositórios: implantação, recursos transversais, mudanças de API e retrospectivas.

Isso é complementado por dois arquivos de constituição diferentes. Para backend, o documento cresceu ao longo do tempo de um template para 437 linhas e incorporou regras sobre migrações, commits, estilo e OpenAPI. Para frontend, a constituição era muito mais compacta — 137 linhas, porque o stack e os padrões foram mais rigidamente definidos desde o início.

Ênfase especial é colocada no comando speckit.analyze, que o autor usa como um loop de feedback obrigatório após cada sprint. Ele não substitui os testes e não pretende ser um linter, mas reconcilia entre spec.

md, plan.md, tasks.md e a implementação real.

De acordo com o autor, exatamente este tipo de análise ajudou a detectar um problema crítico no sprint Kafka do backend: a publicação de eventos em múltiplos casos de uso estava acontecendo dentro de uma transação sem um try-catch protetor. No ambiente de teste, o erro não se manifestou porque Kafka nos containers estava sempre disponível, mas em uma falha real poderia ter revertido dados já salvos e deixado o sistema em estado inconsistente. Após análise, proteção foi adicionada ao código, a lógica de retry foi melhorada e as verificações de integração foram expandidas.

Outro pilar importante é a abordagem API-first como contrato entre os dois repositórios. No projeto, um módulo separado é alocado para isso com uma especificação OpenAPI de aproximadamente 2.669 linhas e 32 endpoints.

O backend gera interfaces de controladores Java a partir dela, e o frontend usa o mesmo YAML como a única fonte de verdade e mantém manualmente tipos TypeScript para cenários reais de UI. O autor observa especificamente que speckit.analyze não pode validar automaticamente a consistência entre dois repositórios, portanto as verificações entre repositórios ainda precisam ser feitas manualmente através do contexto de coordenação.

Mas mesmo nesta forma, o esquema reduz o risco de dessincronização silenciosa entre servidor e interface: se a API muda, é primeiro registrada na especificação e depois aparece no estágio de geração de interface ou compilação do frontend. A conclusão prática deste caso é bastante rigorosa: SDD escala, mas apenas se você o tratar como um sistema de gestão de mudanças, não como uma maneira de pedir a IA para escrever uma feature. Em tarefas curtas você pode não notar a diferença, mas ao longo de dezenas de sprints, os elementos entediantes do processo começam a se pagar — constituições vivas, contextos separados, artefatos formais e verificações regulares de sua consistência.

O caso é interessante porque mostra SDD não em um MVP de brinquedo, mas em um projeto que já tem produção, um loop de teste, repositórios separados e custo real de erros arquiteturais e de contrato.