Spec Kit: o que é, como funciona e como instalar
O Spec Kit é o toolkit open source do GitHub que guia agentes de IA a partir de uma especificação. Em vez de um prompt solto, você descreve o que quer, revisa um plano técnico e então libera o agente.
Neste artigo, você vai entender o que é a ferramenta, como ela funciona por dentro, como instalar e quais comandos usar em cada etapa. Além disso, vamos ver um exemplo com .NET 10, as extensões disponíveis e as críticas mais comuns à abordagem.
O que é o Spec Kit
O Spec Kit é um conjunto de templates, scripts e comandos que dá aos agentes de código processos estruturados e resultados documentados. O GitHub anunciou a ferramenta em setembro de 2025, sob licença MIT, e hoje o repositório oficial no GitHub passa de 140 mil estrelas.
Na prática, a ferramenta tem duas partes. Uma é o specify, CLI que prepara o projeto, e a outra são os comandos que você roda no chat do agente.
Por isso, o fluxo do Spec Kit acontece em dois lugares diferentes. Você usa o terminal para instalar e inicializar, enquanto o trabalho de especificar, planejar e implementar acontece na conversa com o agente.
Além disso, a ferramenta não depende de um agente específico. Ela funciona com GitHub Copilot, Claude Code, Gemini CLI, Codex, Cursor e várias outras integrações, sem prender a especificação a um único fornecedor.
O que o Spec Kit não é
Muita gente confunde a ferramenta com um agente de IA, mas o Spec Kit não escreve código sozinho. Quem gera o código continua sendo o agente que você já usa, enquanto o toolkit define a estrutura, os templates e a ordem das etapas.
Também não se trata de um gerador de documentação extensa, no estilo dos antigos documentos de requisitos com dezenas de páginas. Os artefatos são arquivos Markdown curtos, versionados junto com o código e pensados para pessoas e agentes lerem com facilidade.
Em outras palavras, o Spec Kit funciona como um trilho. O agente continua sendo o motor, mas agora ele anda em uma direção que você definiu e revisou.
Spec driven development: a ideia por trás da ferramenta
O Spec Kit é uma implementação de referência do spec driven development, ou SDD. Nessa abordagem, a especificação deixa de ser um documento descartável e passa a ser a fonte da verdade sobre o que o sistema deve fazer.
O princípio central é separar o "o que" e o "porquê" do "como". Primeiro você descreve o comportamento esperado e os objetivos do usuário, e só depois escolhe stack, arquitetura e bibliotecas.
Se você quer se aprofundar no conceito, o artigo spec driven development: o que é e como aplicar explica os três níveis da prática em detalhes. Aqui, o foco fica na ferramenta e no seu fluxo de trabalho.
Por que o Spec Kit surgiu
Com a popularização dos agentes de código, o chamado vibe coding virou rotina em muitos times. Nesse estilo, você descreve um objetivo em poucas linhas, aceita o que o modelo devolve e vai ajustando por tentativa e erro.
O problema aparece quando o projeto cresce. Muitas vezes o código compila, mas ignora a intenção original, usa uma stack inadequada ou esquece requisitos não escritos.
Segundo o anúncio do GitHub, o Spec Kit nasceu justamente para trocar esse improviso por um processo repetível e verificável. Assim, a especificação vira uma referência compartilhada que o agente consulta e contra a qual você valida o resultado a cada etapa.
Outro ganho importante é o controle do contexto. Ao quebrar o trabalho em especificação, plano e tarefas, o toolkit entrega ao agente porções menores e mais objetivas, o que reduz respostas genéricas.
Pré-requisitos para usar o Spec Kit
Antes de instalar, confira se o ambiente atende aos requisitos da documentação oficial:
- Python 3.11 ou superior instalado na máquina.
- O gerenciador uv, que é o recomendado, ou o pipx para instalar a CLI.
- Um agente de código compatível, como GitHub Copilot, Claude Code ou Gemini CLI.
- Linux, macOS ou Windows, já que os scripts têm versões em Bash, PowerShell e Python.
Nas versões mais recentes, o Git aparece como opcional, porque a ferramenta só precisa dele quando a extensão de Git está ativa. Mesmo assim, vale manter o projeto versionado, pois os artefatos do Spec Kit fazem mais sentido quando acompanham o histórico do código.
Como instalar o Spec Kit
A forma mais simples é instalar a CLI a partir do PyPI com o uv. O pacote se chama specify-cli e disponibiliza o comando specify no terminal.
# Instala a CLI a partir do PyPI
uv tool install specify-cli
# Alternativa usando o pipx
pipx install specify-cli
# Confere se o comando está disponível e mostra a versão
specify version
Se preferir fixar uma versão, instale direto do repositório usando a tag da release. Nesse caso, troque vX.Y.Z pela versão desejada, que você encontra na página de releases do projeto.
# Instala uma release específica a partir do GitHub
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
Depois da instalação, rode specify self check de tempos em tempos. Esse comando apenas verifica se existe uma versão mais nova do Spec Kit, sem alterar nada na sua máquina.
Inicializando um projeto
Com a CLI instalada, o próximo passo é criar o projeto e escolher a integração com o agente. O parâmetro --integration define quais arquivos de comandos e skills a CLI vai gerar.
# Cria um novo projeto configurado para o GitHub Copilot
specify init my-project --integration copilot
# Inicializa na pasta atual usando o Claude Code e scripts em Bash
specify init --here --integration claude --script sh
Em terminais interativos, a CLI pergunta qual agente e qual tipo de script usar. Por outro lado, em ambientes de CI sem teclado, use --non-interactive, que assume o GitHub Copilot quando você não informa nenhuma integração.
Para projetos que já existem, a documentação de instalação traz um guia específico. Vale fazer commit ou backup antes, porque o specify init --here --force mescla os arquivos do toolkit com o conteúdo atual da pasta.
Estrutura de pastas criada pelo Spec Kit
Ao final da inicialização, o projeto ganha uma pasta .specify e os arquivos de comandos do agente escolhido. A estrutura fica parecida com esta:
my-project/
├── .github/ # comandos ou skills do agente escolhido
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── scripts/
│ │ └── bash/
│ └── templates/
│ ├── spec-template.md
│ ├── plan-template.md
│ └── tasks-template.md
└── specs/
└── 001-bills-management/
├── spec.md
├── plan.md
└── tasks.md
A pasta memory guarda a constituição, que vale para o projeto inteiro. Já templates contém os modelos que o agente preenche, enquanto scripts reúne as automações em Bash, PowerShell ou Python.
Cada funcionalidade nova ganha sua própria pasta dentro de specs, numerada em sequência. Dessa forma, você consegue revisar a especificação, o plano e as tarefas de cada entrega no mesmo lugar, inclusive em um pull request.
Os comandos do fluxo de SDD
O fluxo principal do Spec Kit reúne comandos que você executa em ordem dentro do chat do agente. A constituição roda uma vez por projeto, enquanto especificar, planejar, quebrar em tarefas, implementar e convergir se repetem a cada funcionalidade.
| Comando | Etapa | Resultado |
|---|---|---|
/speckit.constitution |
Princípios do projeto | constitution.md |
/speckit.specify |
Requisitos e histórias de usuário | spec.md |
/speckit.clarify |
Esclarecimento de ambiguidades (opcional) | Respostas gravadas no spec.md |
/speckit.plan |
Plano técnico | plan.md e artefatos de design |
/speckit.checklist |
Qualidade dos requisitos (opcional) | Checklists de revisão |
/speckit.tasks |
Quebra em tarefas | tasks.md |
/speckit.analyze |
Consistência entre artefatos (opcional) | Relatório somente leitura |
/speckit.implement |
Execução das tarefas | Código |
/speckit.converge |
Verificação final | Novas tarefas ou "Converged" |
/speckit.taskstoissues |
Integração com GitHub (opcional) | Issues no repositório |
Um detalhe importante é a sintaxe de chamada. A documentação usa a forma /speckit.*, mas o GitHub Copilot, no modo padrão de skills, usa /speckit-*, e outros agentes podem ter variações próprias.
Constitution: as regras do projeto
A constituição registra os princípios que todas as etapas seguintes precisam respeitar. Padrões de código, estratégia de testes, regras de segurança e restrições de arquitetura costumam aparecer aqui.
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency and performance requirements. All APIs must use .NET 10 Minimal APIs and every feature needs unit tests.
Como a constituição vale para o projeto inteiro, você roda esse comando uma vez no início. Depois, só volta a ele quando os princípios mudarem, e a ferramenta sincroniza os templates dependentes.
Specify e clarify: o que e por quê
O comando /speckit.specify transforma uma descrição em linguagem natural na especificação da funcionalidade. Aqui, o foco está no comportamento visível para o usuário e nos objetivos, nunca na stack.
Em seguida, o /speckit.clarify faz até cinco perguntas sobre pontos mal definidos e grava as respostas no próprio spec.md. Você pode repetir o comando várias vezes, cada uma focando uma área diferente, antes de partir para o planejamento.
Essa etapa evita um erro clássico: desenhar a solução em cima de ambiguidades. Afinal, se o requisito está confuso, o plano e o código herdam a mesma confusão.
Plan, checklist e tasks: o como
Somente no /speckit.plan entram as decisões técnicas, como linguagem, frameworks, banco de dados e restrições de arquitetura. Nessa etapa, o agente lê a especificação e gera o plano de implementação com os artefatos de design.
Opcionalmente, o /speckit.checklist cria listas de verificação que funcionam como testes de unidade para os requisitos. Em vez de testar código, elas perguntam se a especificação está completa, clara e consistente.
Depois disso, o /speckit.tasks gera o tasks.md com tarefas ordenadas por dependência. A lista tem fases de setup, fundação, uma por história de usuário e polimento, marcando o que roda em paralelo.
Analyze, implement e converge
Antes de implementar, vale rodar o /speckit.analyze. Ele faz uma análise somente leitura entre especificação, plano e tarefas, apontando requisitos sem tarefa, decisões contraditórias e lacunas.
Com tudo consistente, o /speckit.implement executa as tarefas na ordem das fases. Em funcionalidades grandes, a documentação recomenda rodar por etapas, validando cada parte antes de seguir.
Por fim, o /speckit.converge compara o código com os artefatos e só acrescenta tarefas ao tasks.md quando encontra lacunas. Quando nada falta, ele informa que a implementação convergiu, e o ciclo daquela funcionalidade termina.
Exemplo prático do Spec Kit com .NET 10
Para visualizar o fluxo completo, imagine uma API de contas a pagar construída com .NET 10. A sequência de comandos no chat do agente ficaria assim:
/speckit.specify Build a bills management feature. Users can register bills with a description, amount and due date, mark them as paid and list overdue bills.
/speckit.clarify Focus on what happens when a paid bill is edited and how the overdue status is calculated.
/speckit.plan Use .NET 10 with Minimal APIs, Entity Framework Core and PostgreSQL. Expose endpoints under /api/bills and return errors as ProblemDetails.
/speckit.tasks
/speckit.analyze
/speckit.implement Implement only the Setup and Foundational phases. Stop before the user stories.
/speckit.implement Now implement the overdue bills user story.
/speckit.converge
Repare que a especificação não menciona .NET, banco de dados ou endpoints. Essas escolhas entram somente no plano, o que facilita trocar a stack sem reescrever os requisitos.
Também vale observar a implementação em duas rodadas. Dessa forma, o agente trabalha com um contexto menor e você revisa a fundação do projeto antes de avançar para as histórias de usuário.
Ao final, cada arquivo que o Spec Kit gerou fica em specs/001-bills-management/. Assim, o pull request carrega não só o código, mas também a justificativa de cada decisão.
Além do SDD: bug fixing, avaliação de ideias e extensões do Spec Kit
As versões mais recentes ampliaram o escopo da ferramenta. Hoje, o SDD é apenas um dos processos, e o toolkit também oferece correção de bugs e avaliação de ideias como extensões opcionais.
# Adiciona o processo de correção de bugs
specify extension add bug
# Adiciona o processo de avaliação de ideias
specify extension add assess
# Pesquisa extensões e presets nos catálogos ativos
specify extension search
specify preset search
No processo de bugs, o agente separa diagnóstico, correção e verificação, registrando relatórios em .specify/bugs. Já a avaliação de ideias termina com uma decisão de seguir, esclarecer ou descartar, sempre com base em evidências.
Além disso, o Spec Kit permite adaptar o processo à realidade da sua empresa. Extensões adicionam comandos, presets ajustam templates e terminologia, workflows automatizam etapas e bundles empacotam uma configuração completa para um time.
Para conhecer cada um desses mecanismos, veja o artigo sobre extensões, presets, bundles e workflows. Ele mostra também como montar um catálogo privado apenas com componentes que a empresa aprovou.
Quando usar o Spec Kit e quando evitar
O GitHub destaca três cenários em que a ferramenta brilha: projetos novos, funcionalidades em sistemas existentes e modernização de legado. Em todos eles, existe ambiguidade suficiente para justificar uma especificação revisada antes do código.
Por outro lado, o Spec Kit pesa em tarefas pequenas. Para corrigir um texto ou criar um script descartável, gerar especificação, plano e tarefas custa mais que a própria entrega.
Uma regra prática ajuda a decidir. Se a mudança cabe em uma frase, um prompt direto resolve; caso contrário, o fluxo estruturado compensa.
Vale lembrar também que o Spec Kit não é a única opção do mercado. O Kiro, da AWS, oferece um ambiente integrado e opinativo, enquanto o OpenSpec aposta em especificações enxutas para projetos existentes.
Limitações e críticas
Nenhuma ferramenta escapa de críticas, e o próprio GitHub descreve o projeto como um experimento para testar a metodologia. Por isso, vale conhecer os pontos fracos antes de adotá-lo em todo o time.
A crítica mais frequente é o excesso de Markdown. Em funcionalidades simples, o volume de artefatos pode parecer burocracia, lembrando o modelo cascata que o desenvolvimento ágil tentou deixar para trás.
Outro ponto é o desvio entre especificação e código. O Spec Kit governa bem a primeira geração, mas depois a especificação só continua válida se o time mantiver o hábito de atualizá-la.
Por fim, a qualidade do resultado ainda depende do agente e do modelo. Uma especificação excelente reduz erros, contudo não substitui revisão de código, testes automatizados e responsabilidade humana sobre o que vai para produção.
Conclusão
O Spec Kit organiza a programação com IA em torno de algo que sempre fez falta: uma especificação clara, revisada e versionada. Com ele, o agente deixa de adivinhar e passa a seguir princípios, requisitos, plano e tarefas que você aprovou.
A instalação leva poucos minutos e o fluxo cabe em uma dezena de comandos. Mesmo assim, o ganho real vem da disciplina de pensar no "o que" antes do "como", algo que vale para qualquer ferramenta.
Portanto, comece por uma funcionalidade pequena, mas não trivial, em um projeto real. Assim, você sente o ritmo do Spec Kit, ajusta a constituição e decide se ele merece ficar no time.
FAQ
O Spec Kit é gratuito?
Sim. O projeto é open source sob licença MIT, e o custo fica por conta do agente que você já usa.
Preciso usar o GitHub Copilot com o Spec Kit?
Não. A ferramenta oferece integrações para Claude Code, Gemini CLI, Codex, Cursor e vários outros agentes de código.
O Spec Kit funciona no Windows?
Sim. Os scripts têm versões em PowerShell e Python, então você não precisa do WSL para usar a ferramenta.
Posso usar o Spec Kit em um projeto que já existe?
Sim. Basta rodar o specify init --here na pasta do projeto, de preferência depois de um commit, e seguir o guia de projetos existentes.
Qual a diferença entre analyze e converge?
O analyze verifica a consistência entre os artefatos antes da implementação. Já o converge compara o código pronto com a especificação e acrescenta as tarefas que faltam.