Dois Meses com o Spec-Kit do GitHub e Claude Code: O Que Funciona, O Que Não Funciona

Após dois meses usando o spec-kit do GitHub para Desenvolvimento Orientado por Especificações (SDD) com o Claude Code como agente principal, um desenvolvedor no r/LocalLLaMA relata o que funciona e o que não funciona. O kit, disponível em github.com/github/spec-kit, impõe um fluxo de trabalho de cinco fases: Constituição, Especificação, Planejamento, Tarefas, Implementação. A ideia central: a especificação, não o prompt, é a fonte da verdade.

O Que Realmente Funciona

• Independente de agente: A mesma especificação funciona com Claude Code, Cursor, Codex, Gemini CLI, Copilot. O autor gerou código com Claude Code e depois passou a especificação para o Cursor para refatoração de testes de forma transparente.
• Checkpoints rígidos entre fases: A fase de Planejamento mostra a arquitetura completa proposta antes de qualquer código ser escrito, capturando decisões ruins a um custo de correção de 5 minutos em vez de 5 horas.
• Arquivo de constituição como gate de qualidade: Você define regras invioláveis antecipadamente — mínimos de cobertura de teste, listas de permissão de dependências, orçamentos de desempenho, rigidez de tipagem. O agente falha na própria validação se tentar violá-las.
• Determinismo melhorado: Reexecutar a fase de implementação produz resultados mais consistentes do que prompts brutos, já que o agente não está preenchendo 30 decisões implícitas.

O Que Irrita

• Deriva é real: Edições manuais de código sem atualizar a especificação causam dessincronização rápida. O spec-kit tem ferramentas, mas são iniciais.
• Sobrecarga para mudanças pequenas: Correções de bugs <50 LOC ou funcionalidades triviais parecem cerimoniais. A regra do autor: apenas SDD completo para novos módulos ou funcionalidades que envolvam 200+ LOC.
• Migração de legado é dolorosa: Adaptar SDD a uma base de código de 30k LOC leva meses.
• Qualidade depende do agente: Claude Code (Sonnet/Opus 4.6+) lida bem; modelos menores geram planos que compilam, mas carecem de raciocínio arquitetural.

Configuração Prática

• Instalação: uv tool install --from git+https://github.com/github/spec-kit.git specify-cli. Apenas o repositório oficial é seguro — PyPI tem typosquatters.
• Agente principal: Claude Code, com validação cruzada no Cursor e Gemini CLI.
• Persistência local: SQLite (fácil de especificar/validar, sem dependência de nuvem).
• Modelo de constituição reutilizável: tipagem estrita, cobertura do pytest >80%, lista de permissão de dependências explícita, sem serviços em nuvem a menos que necessário.

Perguntas em Aberto

• Modelos locais (Qwen, DeepSeek-Coder, GLM, Llama) conseguem lidar competentemente com Planejamento e Implementação? O autor descobriu que modelos pequenos seguem o formato, mas o raciocínio arquitetural falha.
• SDD multiagente funciona? Especificação por um modelo, implementação por outro, auditoria por um terceiro — teoricamente melhor, mas na prática não é mensuravelmente melhor que um único agente.