Guia de Uso do GitHub Spec Kit

🚧 Projeto em Desenvolvimento Ativo: O GitHub Spec Kit é experimental e está passando por atualizações constantes. Consulte a documentação oficial para informações mais recentes.

📦 Repositório Oficial: github.com/github/spec-kit

Índice

O GitHub Spec Kit é um toolkit experimental e de código aberto do GitHub que auxilia no desenvolvimento orientado por especificações (spec-driven development). Ele ajuda a estruturar e iniciar projetos de software, garantindo que a implementação siga um plano claro e bem definido, alavancando o poder de agentes de IA.

Visão Geral

O Spec Kit utiliza agentes de IA (como o GitHub Copilot) para gerar código a partir de uma série de artefatos que definem o projeto. O fluxo de trabalho é centrado em comandos que geram e refinam esses artefatos:

  1. Constituição (/constitution): Princípios e regras não negociáveis do projeto.
  2. Especificação (/specify): O "quê" e o "porquê" do produto, sem detalhes técnicos.
  3. Clarificação (/clarify): Um passo opcional para refinar a especificação e evitar ambiguidades.
  4. Plano (/plan): Os detalhes técnicos da implementação (arquitetura, tecnologias).
  5. Tarefas (/tasks): O trabalho dividido em partes gerenciáveis para o agente de IA.
  6. Análise (/analyze): Um passo opcional para verificar a consistência entre os artefatos antes de codificar.
  7. Implementação (/implement): O comando final que instrui o agente a construir o software.

Instalação

A CLI specify é a porta de entrada para o Spec Kit.

Pré-requisitos

Para usar uvx, você precisa ter o uv instalado:

Dentro da pasta do projeto, execute:

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

Download Manual

Como alternativa, você pode baixar os templates manualmente na página de releases do repositório, escolhendo o .zip para seu agente e sistema operacional, e extraindo-o na raiz do projeto.

Fluxo de Trabalho Detalhado

O fluxo de trabalho com o Spec Kit é projetado para ser iterativo e estruturado.

1. Inicie o Projeto (init)

Durante a configuração, você escolherá o agente de IA (copilot, gemini, etc.) e o tipo de script (PowerShell ou shell).

💡 Nota: O comando init --here inicializa o Spec Kit no diretório atual. Para criar um novo projeto em um diretório específico, consulte a documentação oficial.

2. Abra o Projeto no seu Editor

cd <nome-do-projeto>
code .

Importante: Certifique-se de que você está na pasta raiz do projeto para que os comandos (/specify, /plan, etc.) fiquem disponíveis no chat do seu editor.

3. Defina a Constituição (/constitution)

A constituição contém as regras fundamentais do seu projeto.

  • Localização: .specify/memory/constitution.md
  • Ação: Peça ao agente para preencher este arquivo com os princípios do seu projeto.
  • Exemplo de Prompt: Preencha a constituição com os requisitos mínimos para uma aplicação web estática, priorizando HTML, CSS e JS vanilla.

4. Crie a Especificação (/specify)

Descreve o produto do ponto de vista do usuário, focando no "o quê" e "porquê".

  • Ação: Use o comando /specify no chat do seu editor para descrever o que você quer construir.
  • Exemplo de Prompt: /specify estou construindo um site moderno para podcast. A página inicial deve ter um episódio em destaque, e o site deve conter também páginas de "Episódios", "Sobre" e "FAQ".

5. Refine a Especificação (/clarify)

Para evitar o problema de "sub-especificação" (deixar pontos importantes ambíguos), use o comando /clarify.

✅ Recomendado: Embora opcional, este passo evita ambiguidades e melhora significativamente a qualidade da implementação.

  • Ação: Execute /clarify no chat.
  • O que acontece: O agente fará até 5 perguntas de múltipla escolha para esclarecer pontos ambíguos na especificação. Você pode responder com a letra da opção (ex: A, B) ou com seu próprio texto. As respostas são automaticamente registradas no arquivo da especificação.

6. Elabore o Plano Técnico (/plan)

Define os detalhes técnicos da implementação.

  • Ação: Use o comando /plan para especificar as tecnologias.
  • Exemplo de Prompt: /plan usar Next.js com configuração para site estático (SSG). Sem banco de dados. O site deve ser responsivo.

7. Gere as Tarefas (/tasks)

Quebra o trabalho em um checklist de implementação para o agente.

  • Ação: Use o comando /tasks.
  • Exemplo de Prompt: /tasks detalhe o trabalho em tarefas.

8. Analise a Coerência (/analyze)

Antes de implementar, verifique se os artefatos (spec, plan, tasks) são consistentes entre si e com a constitution.

✅ Recomendado: Embora opcional, este passo identifica inconsistências antes da implementação, economizando tempo e evitando retrabalho.

  • Ação: Execute /analyze no chat.
  • O que acontece: O agente analisará os arquivos e apontará discrepâncias, classificando-as por severidade (ex: "Crítica", "Média"). Isso ajuda a corrigir desalinhamentos antes que o código seja escrito, como um plano técnico que viola uma regra da constituição.

9. Implemente o Projeto (/implement)

O passo final, onde o agente de IA escreve o código.

  • Ação: Use o comando /implement.
  • Exemplo de Prompt: Implemente as tarefas para este projeto e atualize a lista de tarefas conforme avança.

10. Construa e Execute

Após a finalização, construa e rode sua aplicação.

npm run build
npm run dev

Tópicos Avançados e Perguntas Frequentes (FAQ)

Como manter os artefatos (Spec, Plan, Tasks) atualizados?

  • A Especificação (spec) é a Fonte da Verdade: É o artefato mais durável. Se surgirem novos requisitos, atualize a especificação. Peça ao agente para "incorporar os aprendizados da nossa conversa na especificação".
  • O Plano (plan) é Flexível: Atualize-o se os detalhes da implementação mudarem (ex: trocar um banco de dados).
  • As Tarefas (tasks) são Descartáveis: Se o plano mudar, apague o arquivo de tarefas e gere-o novamente.

Como lidar com comportamento inesperado da IA?

Use o git a seu favor. O Spec Kit cria uma nova branch para cada /specify. 1. Atualize a Spec: Deixe claro o que você não quer. 2. Descarte as Mudanças: Use um cliente Git para reverter os arquivos indesejados. 3. Reimplemente: Peça ao agente para tentar novamente com a spec corrigida. 4. Commits Frequentes: Faça commits das mudanças que funcionam para criar pontos de verificação seguros.

É possível usar o Spec Kit em projetos existentes?

Sim. O maior desafio é fornecer contexto ao agente. Crie um arquivo context.md descrevendo a arquitetura e as convenções do projeto, ou simplesmente confie na capacidade do agente de analisar o código dinamicamente.

Como trabalhar com múltiplos repositórios (Monorepos)?

  • Abordagem Recomendada: Uma instância do Spec Kit por repositório.
  • Compartilhando Configurações: Use git submodules para compartilhar artefatos como uma constitution padrão.
  • Futuro: A equipe do Spec Kit está trabalhando em uma solução mais robusta para monorepos.

E o Test-Driven Development (TDD)?

Os templates atuais são orientados a TDD. Uma opção "TDD-less" está sendo desenvolvida para permitir prototipagem mais rápida, sem a obrigatoriedade de escrever testes primeiro.