GitHub Spec Kit no VS Code: a ordem certa para transformar ideia em software sem cair no improviso

Para quem é este guia

Este artigo é para quem já entendeu que programar com IA não pode ser apenas “pedir para a ferramenta sair codando”. Isso funciona em protótipos pequenos, mas começa a quebrar quando o projeto tem regra de negócio, integração, segurança, dados, cliente, prazo e manutenção.

O GitHub Spec Kit ajuda justamente nisso: ele organiza o desenvolvimento em etapas. Antes do código, vem a especificação. Antes da implementação, vem o plano. Antes de sair executando tarefas, vem uma validação mínima para garantir que a IA não esteja apenas obedecendo a um pedido mal formulado.

Em português direto: o Spec Kit coloca método onde muita gente está usando pressa.

A ideia central

O Spec Kit segue uma lógica de desenvolvimento orientado por especificação, ou Spec-Driven Development.

Na prática, você deixa de trabalhar assim:

“Crie um sistema de agenda com login, dashboard e relatórios.”

E passa a trabalhar assim:

“Vamos definir primeiro o que esse sistema precisa resolver, quais regras ele deve respeitar, quais dúvidas precisam ser esclarecidas, qual arquitetura será usada, quais tarefas serão executadas e só então implementar.”

Essa mudança parece pequena, mas muda o resultado. A IA passa a trabalhar com contexto, fronteiras e critérios de qualidade. O desenvolvedor deixa de ser apenas alguém que aceita código gerado e passa a atuar como arquiteto, revisor e condutor do processo.

Pré-requisitos

Antes de começar, você precisa ter:

• VS Code instalado.

• Git instalado.

• Python 3.11 ou superior.

• uv ou pipx instalado para executar o CLI do Spec Kit.

• GitHub Copilot ou outro agente compatível com comandos no chat do editor.

O uso mais comum no VS Code é trabalhar com o Copilot Chat aberto dentro do projeto. Depois que o projeto é inicializado com o Spec Kit, os comandos /speckit.* ficam disponíveis para conduzir o fluxo.

A ordem oficial recomendada dos comandos

Para um projeto ou funcionalidade com qualidade de produção, a ordem recomendada é:

/speckit.constitution

/speckit.specify

/speckit.clarify

/speckit.checklist

/speckit.plan

/speckit.tasks

/speckit.analyze

/speckit.implement

Essa é a sequência mais segura porque ela força uma separação saudável entre intenção, requisito, decisão técnica e execução.

Passo 1 - Inicializar o projeto

No terminal do VS Code, rode:

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

Exemplo:

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

Se você já está dentro da pasta do projeto, pode inicializar no diretório atual:

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

No Windows, o Spec Kit normalmente seleciona os scripts PowerShell automaticamente. Se quiser forçar PowerShell:

uvx --from git+https://github.com/github/spec-kit.git specify init nome-do-projeto --script ps

Se quiser forçar shell POSIX:

uvx --from git+https://github.com/github/spec-kit.git specify init nome-do-projeto --script sh

Depois disso, abra a pasta no VS Code:

cd nome-do-projeto
code .

Passo 2 - Criar a constituição do projeto

Com o VS Code aberto, vá até o chat do Copilot ou do agente configurado e execute:

/speckit.constitution

A constituição é onde você define as regras que o projeto deve respeitar sempre.

Pense nela como o combinado técnico do projeto. Não é o lugar para explicar uma funcionalidade específica. É o lugar para definir princípios. Exemplo:

/speckit.constitution Este projeto deve priorizar clareza de código, segurança, baixo acoplamento, testes automatizados nas regras críticas e arquitetura simples. Nenhuma funcionalidade deve ser implementada sem validação de entrada, tratamento de erro e separação entre camada de interface, regra de negócio e persistência.

Uma boa constituição evita que a IA tome decisões soltas. Ela cria um padrão de comportamento para o projeto inteiro.

Passo 3 - Especificar a funcionalidade

Agora vem o comando que define o que será construído:

/speckit.specify

Aqui o foco é o problema, o comportamento esperado e o valor da funcionalidade. Ainda não é hora de escolher framework, banco de dados ou biblioteca. Exemplo:

/speckit.specify Criar uma agenda inteligente para pequenas empresas. O usuário deve conseguir cadastrar clientes, criar compromissos, visualizar a agenda por dia e semana, receber alertas de conflito de horário e marcar compromissos como concluídos ou cancelados. A primeira versão não terá pagamento online nem integração com WhatsApp.

Boa prática: descreva também o que está fora do escopo. Isso reduz muito a chance de a IA inventar funcionalidades.

Passo 4 - Esclarecer ambiguidades

Depois da especificação, execute:

/speckit.clarify

Esse comando serve para revelar dúvidas antes que elas virem código ruim. Exemplo:

/speckit.clarify Foque em regras de conflito de horário, permissões de usuário, status dos compromissos e comportamento esperado quando um compromisso for cancelado.

Esse passo é especialmente importante para times brasileiros porque, na prática, muita regra de negócio fica “subentendida”. O problema é que IA não entende subentendido de forma confiável. Ela preenche lacunas com suposições. E suposição em software vira retrabalho.

Passo 5 - Validar a qualidade da especificação

Antes de criar o plano técnico, rode:

/speckit.checklist

Esse comando valida se a especificação está madura o suficiente para seguir. Ele ajuda a responder perguntas como:

• Os requisitos estão claros?

• Existem regras contraditórias?

• O escopo está delimitado?

• Existem critérios mínimos para saber se a funcionalidade ficou pronta?

Na prática, esse é o momento de evitar aquela frase que todo time conhece:

“Mas eu achei que era para funcionar de outro jeito.”

Passo 6 - Criar o plano técnico

Com a especificação validada, agora sim entra tecnologia:

/speckit.plan

Exemplo:

/speckit.plan Usar Next.js com TypeScript no frontend e backend, banco PostgreSQL com Prisma, autenticação simples por e-mail e senha, componentes com Ant Design, testes unitários para regras de conflito de agenda e estrutura modular separando interface, services, repositories e validações.

Aqui você informa stack, arquitetura, decisões técnicas, restrições e padrões. O erro comum é começar por esse passo. Muita gente quer decidir Next.js, MongoDB, Docker, Redis e filas antes de explicar o problema direito. Isso inverte a lógica. Primeiro se entende a necessidade. Depois se escolhe a solução.

Passo 7 - Gerar as tarefas

Depois do plano, gere a lista de execução:

/speckit.tasks

Esse comando quebra o trabalho em tarefas menores e mais executáveis. Uma boa lista de tarefas deve permitir acompanhamento real. Não basta aparecer algo genérico como “criar backend”. O ideal é que as tarefas tenham sequência, dependências e entregas verificáveis. Exemplo do tipo de tarefa que faz sentido:

Criar modelo de dados para cliente e compromisso.

Implementar validação de conflito de horário.

Criar tela de agenda semanal.

Adicionar testes para criação de compromisso em horário ocupado.

Isso ajuda tanto o desenvolvedor quanto o gestor. O trabalho deixa de ser uma caixa preta.

Passo 8 - Analisar consistência antes de implementar

Antes de mandar implementar, rode:

/speckit.analyze

Esse comando verifica se especificação, plano e tarefas estão coerentes. Ele é uma espécie de revisão de arquitetura e requisito antes da execução. Para funcionalidades simples, talvez pareça burocrático. Para projetos com cliente, contrato, regra sensível, integração, dados ou segurança, é um passo que vale muito. Melhor descobrir inconsistência no Markdown do que no deploy.

Passo 9 - Implementar

Só agora vem o código:

/speckit.implement

Esse comando instrui o agente a executar a implementação com base nos artefatos anteriores.

A diferença é grande: em vez de pedir para a IA “criar uma agenda”, você está pedindo para ela implementar uma funcionalidade já especificada, esclarecida, validada, planejada, quebrada em tarefas e analisada. É outro nível de controle.

Fluxo enxuto para testes rápidos

Para experimentos pequenos, dá para usar uma sequência mais curta:

1. /speckit.specify

2. /speckit.plan

3. /speckit.tasks

4. /speckit.implement

Mas isso deve ser exceção, não regra. Na Inova e-Business, para qualquer funcionalidade com impacto real, a recomendação é usar o fluxo completo:

1. /speckit.constitution

2. /speckit.specify

3. /speckit.clarify

4. /speckit.checklist

5. /speckit.plan

6. /speckit.tasks

7. /speckit.analyze

8. /speckit.implement

Como usar em projetos já existentes

Se o projeto já existe, você não precisa criar um projeto novo. Entre na pasta do repositório e inicialize o Spec Kit no diretório atual:

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

Depois, para cada nova funcionalidade, siga o fluxo:

1. /speckit.specify

2. /speckit.clarify

3. /speckit.checklist

4. /speckit.plan

5. /speckit.tasks

6. /speckit.analyze

7. /speckit.implement

A constituição normalmente é criada uma vez e revisada quando os princípios do projeto mudam.

Exemplo: Cadastro de clientes

Imagine que você quer criar um módulo simples de cadastro de clientes.

1. Constituição

/speckit.constitution O projeto deve ter código simples, legível e organizado. Toda regra de negócio deve ficar fora da interface. Entradas de usuário devem ser validadas. Erros devem ser tratados com mensagens claras. O sistema deve evitar dependências desnecessárias e manter estrutura preparada para crescimento.

2. Especificação

/speckit.specify Criar um módulo de cadastro de clientes. O usuário deve conseguir cadastrar, editar, listar, buscar e inativar clientes. Cada cliente deve ter nome, e-mail, telefone, documento e status. Não deve existir exclusão física nesta primeira versão. Clientes inativos não devem aparecer como opção em novos atendimentos.

3. Clarificação

/speckit.clarify Validar regras para documento duplicado, formato de e-mail, obrigatoriedade de telefone, diferença entre cliente ativo e inativo, e comportamento esperado ao tentar cadastrar um cliente já existente.

4. Checklist

/speckit.checklist

5. Plano técnico

/speckit.plan Usar Next.js com TypeScript, PostgreSQL com Prisma, validação com Zod, componentes com Ant Design e testes unitários para regras de duplicidade e inativação. A estrutura deve separar pages, components, services, repositories e schemas de validação.

6. Tarefas

/speckit.tasks

7. Análise

/speckit.analyze

8. Implementação

/speckit.implement

O que muda na prática

Sem Spec Kit, a IA tende a responder ao último comando. Com Spec Kit, ela passa a trabalhar dentro de um processo.

Isso reduz:

• Código gerado fora do escopo.

• Funcionalidades inventadas.

• Falta de padrão técnico.

• Retrabalho por ambiguidade.

• Implementações que parecem boas, mas não resolvem o problema real.

E aumenta:

• Clareza de requisitos.

• Rastreabilidade das decisões.

• Qualidade da arquitetura.

• Previsibilidade na execução.

• Controle humano sobre a IA.

Uma forma simples de memorizar

Use esta frase:

Regra, intenção, dúvida, validação, plano, tarefas, revisão e código.

Ou, em comandos:

constitution → specify → clarify → checklist → plan → tasks → analyze → implement

Essa ordem importa porque cada etapa protege a próxima.

A especificação protege o plano. O plano protege as tarefas. As tarefas protegem a implementação. A análise protege o projeto inteiro.

Conclusão

O GitHub Spec Kit não substitui o desenvolvedor. Ele melhora a forma como o desenvolvedor conduz a IA.

A diferença entre usar IA para programar e usar IA para construir software está no processo. Sem processo, a IA acelera também os erros. Com processo, ela vira uma força real de produtividade.

Para times que querem usar IA com seriedade, especialmente em projetos com clientes, prazos e manutenção, o Spec Kit é uma boa resposta para uma pergunta que muita empresa ainda está evitando:

Primeiro clareza. Depois código.