Configurar GitHub Spec Kit em seu ambiente

  • 3 minutos

Antes de usar GitHub Spec Kit para praticar o desenvolvimento controlado por especificações, você precisa configurar seu ambiente. Esta unidade aborda os pré-requisitos, o processo de instalação e as etapas de configuração para obter GitHub Kit de Especificações em execução em seu ambiente de desenvolvimento.

Pré-requisitos e requisitos do sistema

Antes de instalar GitHub Kit de Especificações, verifique se o ambiente de desenvolvimento atende aos requisitos de sistema operacional, dependências de software e suporte ao assistente de codificação de IA.

Sistema Operacional

Seu ambiente de desenvolvimento deve usar um dos seguintes sistemas operacionais:

  • Linux ou macOS: Totalmente compatível.
  • Windows: totalmente compatível com scripts do PowerShell.

Software necessário

Seu ambiente de desenvolvimento deve incluir o seguinte software:

  • Python 3.11 ou posterior: A CLI do Kit de Especificações do GitHub é uma ferramenta em Python.
  • Git: necessário para integração de controle de versão e pull do kit de ferramentas.
  • uv tool: GitHub Spec Kit usa a ferramenta uv para gerenciamento de pacotes. A ferramenta uv é um gerenciador de pacotes moderno que pode instalar ferramentas diretamente de GitHub.

Assistente de codificação de IA

Seu ambiente de desenvolvimento deve ter pelo menos um assistente de codificação de IA com suporte configurado e funcionando. O GitHub Spec Kit dá suporte a:

Agente Ambiente Suporte ao Comando barra
GitHub Copilot Visual Studio Code Yes
Código Claude CLI/IDE Yes
Cursor Cursor IDE Yes
Windsurf Windsurf IDE Yes
CLI do Desenvolvedor Q da Amazon CLI/IDE verificação
Gemini CLI CLI Yes
E outros Vários Varia

O exercício de laboratório neste módulo usa Visual Studio Code com GitHub Copilot.

Instalar a ferramenta UV

Você pode instalar a uv ferramenta usando um dos seguintes métodos:

  • No macOS e Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

  • No Windows (no PowerShell):

    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Após a instalação, reinicie o terminal para garantir que uv esteja disponível no PATH.

Instalar a CLI Specify

GitHub Spec Kit usa a ferramenta specify CLI para gerenciar especificações e interagir com assistentes de codificação de IA. Há duas maneiras principais de instalar a specify ferramenta da CLI.

A abordagem recomendada é instalar specify-cli globalmente usando uv. Uma instalação global disponibiliza o specify comando em qualquer projeto.

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

A instalação global oferece estes benefícios:

  • Disponível em qualquer diretório do projeto.
  • Fácil de atualizar usando uv tool upgrade specify-cli.
  • Não é necessário executar comandos de instalação novamente todas as vezes.

Método 2: uso único

Se você preferir não instalar globalmente, poderá executar GitHub Spec Kit diretamente usando uvx:

uvx --from git+https://github.com/github/spec-kit.git specify init

O uso único baixa e executa o GitHub Spec Kit apenas para essa única chamada. É útil para:

  • Experimentar o GitHub Spec Kit antes de decidir instalar
  • Em execução em sistemas em que você não pode instalar globalmente (como alguns servidores de CI)

A desvantagem é que você precisa prefixar cada comando com uvx --from ... completo todas as vezes, o que é menos conveniente no uso regular.

Verificando sua instalação

Após a instalação, verifique se o GitHub Spec Kit está funcionando corretamente:

specify check

Esse comando verifica as ferramentas necessárias e confirma se a instalação foi bem-sucedida. Ele relata:

  • Se o Git foi encontrado e configurado ou não.
  • Se o assistente de codificação de IA é detectado ou não.
  • Quaisquer dependências ou problemas de configuração ausentes.

Se o specify check reportar problemas, resolva-os antes de prosseguir.

Configurando Visual Studio Code com GitHub Copilot

Você pode usar as seguintes etapas para configurar Visual Studio Code com GitHub Copilot (para uso com GitHub Spec Kit):

  1. Instale Visual Studio Code.

    Baixe e instale Visual Studio Code de code.visualstudio.com caso ainda não tenha feito isso.

  2. Instale GitHub Copilot extensão.

    1. Abra o Visual Studio Code.
    2. Vá para o modo de exibição Extensões (Ctrl+Shift+X ou Cmd+Shift+X).
    3. Pesquise por "GitHub Copilot".
    4. Instale a extensão GitHub Copilot.
    5. Entre com sua conta GitHub que tenha uma assinatura GitHub Copilot ativa.

  3. Verifique se GitHub Copilot está funcionando.

    Abra o painel Copilot Chat GitHub e verifique se a funcionalidade de chat está funcionando.

  4. Abra o terminal integrado.

    Você pode executar comandos specify no terminal integrado do Visual Studio Code:

    1. Abra um novo Terminal.
    2. Navegue até o diretório do projeto.
    3. Para verificar se tudo está configurado, execute specify check.

Instalação para outros ambientes

Se você não estiver usando Visual Studio Code, o processo será semelhante:

Código Claude

  1. Instalar specify-cli globalmente, conforme descrito anteriormente
  2. Abrir a interface do Claude na pasta do projeto
  3. Digite comandos de barra (/speckit.specify etc.) diretamente no chat

Cursor

  1. Instale specify-cli globalmente.
  2. Abra seu projeto no Cursor.
  3. Verifique se o agente de IA está em execução.
  4. Utilize comandos de barra na interface de chat de IA do Cursor.

Outras ferramentas de IA

A maioria dos assistentes de codificação de IA com suporte segue o mesmo padrão:

  1. Instale o specify-cli globalmente.
  2. Abra seu projeto em seu ambiente preferencial.
  3. Use os comandos barra na interface de chat de IA da ferramenta.

Verifique a tabela "Agentes de IA com suporte" no arquivo README do Kit de Especificações no GitHub para quaisquer considerações específicas da ferramenta.

Solução de problemas comuns

Você pode encontrar alguns problemas comuns durante a instalação ou configuração. As seções a seguir fornecem soluções para problemas comuns.

comando uv não encontrado

Se uv não for reconhecido após a instalação:

  • Feche e reabra o terminal.
  • Verifique se o diretório de instalação está em seu PATH.
  • Em Windows, talvez seja necessário reiniciar o computador.

Especificar o comando não encontrado

Se specify não for encontrado após a instalação:

  • Feche e reabra o terminal.
  • Verifique se ~/.local/bin (ou o diretório da uv caixa de ferramentas) está em seu PATH.
  • Tente executar uv tool list para ver se "specify-cli" aparece.

Ferramenta de IA não detectada

Se specify check relata que sua ferramenta de IA não foi encontrada:

  • Verifique se a ferramenta de IA está instalada e em execução.
  • Para Visual Studio Code com GitHub Copilot, verifique se a extensão está instalada e se você está conectado.
  • Verifique se você está executando a verificação de um terminal em que a ferramenta de IA está acessível.

Problemas específicos do Windows

Se você estiver em Windows e enfrentando problemas:

  • Verifique se o PowerShell está disponível (normalmente pré-instalado).
  • Execute comandos do PowerShell em um terminal do PowerShell (não no Prompt de Comando).
  • Instale os pré-requisitos (Python, uv, Git) para Windows.

Para problemas além desses problemas comuns, consulte o GITHUB SPEC Kit README e os recursos da comunidade no repositório GitHub.

Resumo

GitHub Spec Kit dá suporte a vários ambientes de desenvolvimento e assistentes de codificação de IA. Os principais requisitos incluem Python 3.11+, Git e a ferramenta uv. Você pode instalar a specify CLI globalmente ou usá-la uma única vez por meio do uvx. Visual Studio Code com GitHub Copilot é uma configuração comum, mas também há suporte para outras ferramentas de IA. Verificar sua instalação com specify check ajuda a garantir que tudo esteja configurado corretamente.

Observação

Consulte a guia Texto e imagens para obter mais detalhes!