Spec-kit: o kit de desenvolvimento do GitHub
Nesta série de postagens sobre Spec Driven Development, iremos abordar diversos frameworks que implementam o conceito de Spec Kit de maneira diferente. Iremos começar hoje com o kit de desenvolvimento do GitHub, um dos mais famosos.
Em constante evolução, lançado em meados de agosto de 2025, hoje possui cerca de quase 9k forks, mais de 145 releases e mais de 101 mil estrelas no GitHub. Esse SDD kit é um sucesso de uso.
Você pode instalá-lo localmente com uv, um package manager de Python, com 1 comando:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v[tag release]
Feito isso, basta inicializar o projeto passando o nome e o agente que você irá utilizar:
specify init my-project --integration copilot
cd my-project
Antes de começar o desenvolvimento, a documentação sugere que você defina os princípios do projeto, criando uma espécie de constituição. O comando /speckit.constitution cria um arquivo de mesmo nome, que recebe as informações sobre guias de como o seu projeto deve ser estruturado, regras de governança com restrições, princípios e tudo o que é relevante para ser levado em consideração ao longo do desenvolvimento. Esse arquivo se cria uma vez só.
Depois disso, iremos especificar o que precisamos criar nessa spec com /speckit.specify. O objetivo aqui não é falar sobre como, e sim o que e por que iremos criar. Será criada uma pasta com o número da spec, o nome e, dentro, um arquivo .spec.md juntamente com o requirements.md.
Arquivos criados:
spec.md/checklists/requirements.md
A spec guarda informações como requisitos funcionais, entidades-chave, edge cases, user stories e outras informações inferidas pelo agente. Esse documento é interessantíssimo e deve ser lido com calma para refinamento do problema. Além dele, é criado também o requirements.md.
Esse outro arquivo é um documento mais direto: ele documenta o que será feito e o que foi entendido em lista, definindo o que falta e o que já foi feito no processo da spec.
Após essa primeira etapa realizada, é hora de documentar como tecnicamente iremos resolver o problema. Quais tecnologias, bibliotecas, frameworks e tudo mais que iremos utilizar como stack.
Usando /speckit.plan, nesse momento são criados alguns documentos:
data-model.mdquickstart.mdresearch.mdResearch.mdplan.md
O data model serve para mapearmos os modelos utilizados nesse processo, além do fluxo de utilização desses dados. O quickstart serve para entendermos os arquivos-chave do processo, quais comandos iremos utilizar e quais pré-requisitos.
O research é um documento que vai servir como “pesquisa do agente”. Ele vai documentar como e por que cada tecnologia foi escolhida e utilizada, qual arquitetura, estratégia para testes, insights e muito mais. O interessante é que também são registradas dúvidas ou ambiguidades que não foram respondidas.
O plan é o documento que registra o contexto técnico, resumo, branch, verificação de compatibilidade com a constituição, e deixa registros de justificativas técnicas. Ele possui infos valiosas de como será o processo de implementação, performance, escopo e limitações.
Depois de planejar, devemos quebrar o plano em tasks. Usamos /speckit.tasks para que o agente quebre a implementação em tasks dentro de diversas fases, categorizando se é de infra, projeto, user story, se uma depende da outra, ordem e tudo mais. É um arquivo bem rico que podemos acompanhar tudo o que foi registrado até agora de forma mais objetiva.
caso durante o processo tenha algo que deva ser corrigido ou revisado, podemos usar
speckit.clarify.
Depois disso, é só implementar. Usamos /speckit.implement para concretizarmos a ideia. Idealmente, é recomendado que utilizemos diferentes janelas de contexto, com um modelo mais inteligente para gerar os planos e um mais básico para implementar a solução. Isso porque, com um plano bem definido, pensado, sem ambiguidades e com um passo a passo bem robusto, o agente a assumir terá pouco espaço para alucinar, errar ou sair dos trilhos. O desenvolvimento é previsível, claro e transparente.
Problemas
Esse Spec Kit é extremamente completo, deixa o projeto muito bem documentado e fácil de compartilhar o processo com outros desenvolvedores, mas isso faz com que ele seja token-hungry. Não indico para coisas muito simples e tarefas rápidas.
Por ter diversas etapas, a velocidade em primeiro momento pode ser afetada. Se você precisa de algo estruturado, mas rápido, também não aconselho. O processo fica um pouco mais burocrático, e pode ser que não faça sentido todos os documentos gerados para o tamanho do projeto.
