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.
📖 Leia a fonte completa: r/LocalLLaMA
👀 See Also

Memento v1.0: Memória Persistente Local para Agentes de IA de Codificação
Memento v1.0 é uma camada de memória totalmente local para agentes de IA de programação que executa embeddings, armazenamento e busca na sua máquina sem dependências de nuvem. Ele usa embeddings all-MiniLM-L6-v2, indexação HNSW e suporta múltiplas IDEs com 17 ferramentas MCP.
WCAGent: Agente de IA de Código Aberto para QA de Acessibilidade Automatizada
WCAGent é um agente de IA autônomo que detecta violações das WCAG, atribui gravidade, gera relatórios e abre problemas no GitHub automaticamente.

Mímir: Um Sistema de Memória em Python Baseado em 21 Mecanismos da Neurociência
Mímir é um sistema de memória em Python para agentes de IA que implementa 21 mecanismos da ciência cognitiva, como memória flashbulb e esquecimento induzido por recuperação. Ele usa um índice híbrido BM25 + semântico + data e mostra melhorias em benchmarks, incluindo 13% mais precisão de ferramenta no Mem2ActBench em comparação com VividnessMem.

MCP-Índia-Stack: Servidor offline-first para dados financeiros indianos em agentes de IA
MCP-India-Stack é um servidor MCP offline-first que fornece funcionalidades de API financeira e governamental indiana sem autenticação ou chamadas de API externas. Ele agrupa conjuntos de dados localmente para cálculos fiscais, ferramentas de validação e consultas.