Como instalar o Spec Kit: specify-cli e as mudanças nos comandos /speckit-*

O Spec Kit é o kit de ferramentas de código aberto do GitHub para o desenvolvimento orientado por especificações (Spec-Driven Development): primeiro se escreve a especificação, depois um plano e tarefas e, por fim, o seu assistente de código de IA implementa as tarefas. A linha de comando se chama specify e vem do pacote specify-cli.

Muitos tutoriais na internet ainda usam o comando de instalação antigo, a opção --ai e nomes de comandos como /speckit.specify, e copiá-los costuma dar erro. Esta página segue a documentação oficial para mostrar a forma correta atual e lista o que mudou.

Quando isto foi verificado

Escrito com base na documentação oficial do Spec Kit, verificada em 2026-10-26. O projeto evolui rápido; quando houver diferença, confie no specify --help da sua máquina e na documentação oficial, e não nesta página.

Para quem é esta página

• Para quem quer experimentar um fluxo orientado por especificações dentro de um assistente de código de IA, como Claude Code, GitHub Copilot, Gemini CLI, CodeBuddy CLI, Pi ou Oh My Pi.
• Para quem instalou o Spec Kit por um tutorial antigo e agora recebe erros ou comandos que não aparecem.

Pré-requisitos

Item	Requisito
Sistema	Linux, macOS ou Windows (os scripts do PowerShell funcionam sem WSL)
Python	3.11 ou superior
Gerenciador de pacotes	uv (recomendado) ou pipx
Assistente de código de IA	Qualquer assistente com suporte; a documentação oficial lista dezenas de integrações
Git	Opcional, necessário apenas quando a extensão git está ativada

O Spec Kit em si não precisa do Node.js. Se o seu assistente é instalado via npm, veja primeiro Instalação dos AI Agent CLI.

Instalar o specify-cli

Opção 1: pelo PyPI (a mais curta)

# Recomendado: uv
uv tool install specify-cli

# Ou pipx
pipx install specify-cli

# Ou pip
pip install specify-cli

Para fixar uma versão: uv tool install specify-cli==0.12.11 (use a versão da página de releases).

Opção 2: por uma tag de release do GitHub

A documentação oficial a apresenta como o caminho reproduzível recomendado. Ela exige o uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Troque vX.Y.Z por uma tag de Releases. Mantenha o v inicial, por exemplo v0.12.11.

Verificar a instalação

specify version
specify self check

specify version confirma que o comando funciona e mostra a versão. specify self check é somente leitura e informa se existe uma versão mais nova.

Inicializar um projeto

specify init my-project --integration claude
cd my-project

--integration escolhe o seu assistente de IA. Valores comuns são claude, copilot, gemini, codebuddy, pi e omp. Opções úteis:

• --script sh|ps|py: escolhe o tipo de script. O padrão é ps no Windows e sh nos demais sistemas.
• --here --force: inicializa dentro de um diretório existente e não vazio. --force reconhece o aviso de mesclagem, então faça commit ou backup das alterações locais antes.
• --non-interactive: para CI. Sem --integration, o padrão é o GitHub Copilot, então não se deixe surpreender por esse padrão.

Nomes dos comandos: /speckit-*

Depois da inicialização, execute-os no chat do seu assistente de IA, não no terminal:

Etapa	Comando	O que faz
1	/speckit-constitution	Escreve os princípios do projeto, com os quais as etapas seguintes são conferidas; uma vez por projeto
2	/speckit-specify	Transforma uma descrição da funcionalidade em linguagem comum em spec.md
3	/speckit-clarify	Pergunta sobre as lacunas da especificação e incorpora as respostas
4	/speckit-plan	Gera plan.md e outros artefatos de design para a sua stack
5	/speckit-checklist	Gera uma lista de verificação da qualidade dos requisitos
6	/speckit-tasks	Gera um tasks.md ordenado por dependências
7	/speckit-analyze	Verificação somente leitura de conflitos e lacunas entre spec.md, plan.md e tasks.md
8	/speckit-implement	Executa o tasks.md em ordem
9	/speckit-converge	Confere o código com a especificação e acrescenta tarefas para as lacunas; repita implement e converge até aparecer Converged

O caminho mais curto é specify → plan → tasks → implement → converge. Só o caminho completo inclui constitution, clarify, checklist e analyze.

O seu assistente pode escrevê-los de outra forma

O guia de início rápido oficial usa os nomes com hífen /speckit-* (o modo de skills padrão do GitHub Copilot). Tutoriais antigos e as notas de atualização ainda mostram a forma com ponto, como /speckit.specify. O formato de chamada varia entre assistentes e modos, então vale o que realmente aparecer na lista de comandos do seu assistente após a inicialização.

O que mudou em relação aos tutoriais antigos

Comum em tutoriais antigos	Agora
Somente uv tool install ... --from git+https://...	O specify-cli também está no PyPI e pode ser instalado com uv, pipx ou pip; a instalação por tag do GitHub continua com suporte
specify init --ai claude	A documentação oficial usa --integration claude em todo lugar
/speckit.specify, /speckit.plan	O início rápido usa /speckit-specify e /speckit-plan e acrescenta /speckit-converge
/constitution propaga mudanças para templates e arquivos de comandos	Agora atualiza apenas .specify/memory/constitution.md; para restaurar a propagação antiga, execute specify preset add constitution-sync
Recursos de git sempre ativos	Agora é uma extensão opcional: specify extension add git
A funcionalidade ativa é deduzida pela branch do Git	.specify/feature.json registra o diretório da funcionalidade ativa

Atualizar

Atualizar a própria linha de comando:

specify self check                 # somente leitura: existe uma versão mais nova?
specify self upgrade --dry-run     # prévia sem atualizar
specify self upgrade               # atualiza para a última versão estável
specify self upgrade --tag vX.Y.Z  # fixa uma tag de release

Atualizar os arquivos dentro de um projeto existente, a partir do diretório do projeto:

specify integration status         # lista as integrações instaladas e os arquivos modificados
specify integration upgrade <key>  # execute uma vez por integração instalada
specify extension update           # atualiza todas as extensões

Passe --force para specify integration upgrade somente quando ele informar arquivos gerenciados modificados localmente e você tiver revisado a diferença.

Problemas comuns

• command not found: uv: instale o uv primeiro e execute o comando de instalação novamente.
• No such option: --integration: um specify antigo (por exemplo, 0.1.6) está antes no seu PATH. Reinstale com a mesma ferramenta usada originalmente, por exemplo uv tool install --force specify-cli, e confirme com specify version.
• Duas cópias instaladas: instalar com uv, pipx e pip deixa uma cópia separada de cada. Atualize com a mesma ferramenta e não as misture.
• Uma instalação pelo PyPI não se atualiza sozinha: a versão fica onde você instalou, então use os comandos de atualização acima.
• A inicialização recusa um diretório existente: depois de fazer commit ou backup, acrescente --here --force.

Próximos passos

• Para decidir entre o Spec Kit e o OpenSpec, leia Spec Kit vs OpenSpec.
• Para ver o fluxo de especificações que o próprio HagiCode usa, leia a Introdução ao OpenSpec.

Documentação oficial do Spec Kit