GitHub Spec Kit: como transformar requisitos em etapas para agentes de IA

O método é chamado Spec-Driven Development (SDD), ou desenvolvimento guiado por especificações. Neste guia, vamos instalar a CLI, iniciar um projeto e percorrer um fluxo básico sem tratar os comandos do agente como comandos de terminal.

O que é o GitHub Spec Kit

O Spec Kit é um kit open source que prepara arquivos e processos reutilizáveis para agentes de programação. Ele não é um modelo de IA nem substitui o agente: a CLI configura o projeto, enquanto as etapas de especificação e implementação são executadas dentro do chat do agente.

A documentação oficial apresenta diferentes processos. O SDD organiza uma mudança em especificação, plano, tarefas, implementação e convergência. O projeto também oferece fluxos separados para corrigir bugs e avaliar uma ideia, que podem ser instalados conforme a necessidade.

Pré-requisitos e instalação

Para seguir o quick start, você precisa de Python 3.11 ou superior, do gerenciador uv e de um agente de programação compatível. O exemplo abaixo usa o GitHub Copilot:

$ uv tool install specify-cli
$ specify init taskify --integration copilot
$ cd taskify

Esses são comandos de terminal: eles instalam a CLI e inicializam o projeto taskify. O parâmetro --integration copilot escolhe a integração. O specify init também pode apresentar opções interativas; para outros agentes, confira as integrações e a sintaxe de invocação.

Fluxo curto para uma funcionalidade

Depois de inicializar o projeto, abra-o no agente e execute cada skill no chat, revisando a saída antes de avançar. No modo padrão do Copilot, um caminho curto é:

/speckit-constitution Defina princípios que já são verdadeiros neste projeto: preservar a API pública, manter os limites entre serviços e executar os testes existentes.
/speckit-specify Adicione exportação CSV à página de pedidos sem mudar os filtros nem as regras de autorização.
/speckit-plan Reutilize a arquitetura, as dependências e os padrões de teste existentes.
/speckit-tasks
/speckit-implement
/speckit-converge

A constituição é criada uma vez por projeto; use apenas princípios já adotados pela equipe ou confirmados na documentação do repositório. Para funcionalidades maiores, o quick start completo recomenda acrescentar etapas como /speckit-clarify, /speckit-checklist e /speckit-analyze como pontos de revisão.

Esses comandos são skills invocadas no chat, não comandos para colar no terminal. A grafia varia conforme o agente: por exemplo, a referência oficial documenta $speckit-specify para Codex e /skill:speckit-specify para Kimi. Use a forma indicada para a integração selecionada.

Como adotar em um projeto existente

O Spec Kit também pode ser inicializado em um repositório já existente. Antes, faça commit ou stash do trabalho atual para ter uma linha de base revisável. A documentação propõe:

$ specify init --here --force --integration copilot

--here aponta para o diretório atual e --force permite inicializar em uma pasta não vazia. O próprio guia alerta que o comando pode substituir arquivos em caminhos gerenciados que já existam. Revise o diff antes de continuar. A inicialização não reescreve a aplicação nem deduz automaticamente especificações de todo o comportamento existente; consulte o guia para projetos existentes.

Outro detalhe: a funcionalidade ativa é identificada pelo diretório registrado em .specify/feature.json, não simplesmente pela branch atual do Git. O projeto oferece uma extensão Git opcional para criar branches numeradas, mas trocar de branch, por si só, não altera o diretório ativo.

Se instalar extensões ou componentes comunitários, revise o código antes de executá-los. O catálogo ajuda a descobrir componentes, mas o projeto ressalta que as listagens comunitárias não são auditorias nem endossos.

Para complementar as instruções do projeto, veja nosso guia de AGENTS.md. Se quiser automatizar tarefas no GitHub depois de validar o fluxo, confira também o artigo sobre GitHub Agentic Workflows e os passos para trabalhar com agentes de programação e revisão.