GitHub Spec Kit no VS Code: a ordem certa para transformar ideia em software - passo a passo prático

Artigo atualizado em 17/09/2026

Pedir para uma IA criar uma aplicação é fácil. Explicar o que ela deve construir, impedir que invente regras e comprovar que a entrega funciona exige mais cuidado. O GitHub Spec Kit organiza esse trabalho. Em vez de depender de uma conversa longa e de pedidos soltos, você passa a ter especificação, plano, tarefas e registros que podem ser revisados junto com o código. Esses registros são os artefatos do processo. O agente continua executando o trabalho; o desenvolvedor continua responsável pelas decisões. ^[1]

A pergunta inicial, porém, não deve ser "qual comando eu executo?". Deve ser: estou construindo uma funcionalidade, corrigindo um defeito ou decidindo se uma ideia merece investimento? A resposta muda o caminho.

1. O que é o Spec Kit e qual fluxo escolher

O Spec Kit é um kit de ferramentas de código aberto do GitHub. Ele fornece processos, instruções e modelos de documentos para agentes de programação. Não é um novo modelo de IA nem substitui o Copilot ou outro agente. Sua documentação atual apresenta três entradas independentes. ^[1]

Sua necessidade	Processo	Resultado esperado
Construir uma funcionalidade ou aplicação	Spec-Driven Development, ou SDD	Requisitos conectados ao planejamento, à implementação e à verificação de aderência
Reparar algo que deveria funcionar	Bug fixing	Diagnóstico, correção delimitada e evidência de verificação
Avaliar uma proposta antes de desenvolver	Idea assessment	Decisão fundamentada para seguir, esclarecer ou parar

O SDD já faz parte do núcleo. Os processos de bugs e avaliação de ideias são extensões opcionais distribuídas pelo projeto. Não é necessário executar os três em sequência. ^[1]

Na prática: adicionar uma agenda é trabalho de SDD; corrigir uma reserva duplicada é trabalho de bug fixing; investigar se vale oferecer atendimento offline é trabalho de assessment. Uma correção não precisa virar um projeto inteiro, e uma ideia ainda incerta não precisa virar código.

2. Como instalar e configurar no VS Code

Para este guia, use VS Code com GitHub Copilot configurado, Python 3.11 ou superior e o gerenciador uv. O Spec Kit funciona em Windows, macOS e Linux. Git é opcional para o toolkit, mas nossa recomendação é versionar os artefatos e o código desde o início. ^[3]

Instale o uv, caso ainda não esteja disponível

No Windows, uma opção documentada é usar o PowerShell: ^[15]

winget install --id=astral-sh.uv -e

No macOS com Homebrew:

brew install uv

No Linux, o instalador oficial pode ser baixado e revisado antes da execução:

curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.sh

Reabra o terminal depois da instalação. A verificação inicial é:

uv --version

Instale o CLI e crie o projeto

O caminho simples apresentado no README usa o pacote oficial specify-cli: ^[1,3]

uv tool install specify-cli
specify version
specify init agenda-servicos --integration copilot
cd agenda-servicos
code .

specify é o comando de terminal. specify-cli é o nome do pacote. Se code . não estiver disponível no seu terminal, abra a pasta agenda-servicos pelo menu do VS Code.

Para padronizar a mesma versão em uma equipe, use uma instalação fixada. Este é um caminho alternativo ao primeiro comando, não uma segunda instalação obrigatória: ^[2,3]

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

Para essa alternativa de instalação a partir do repositório, mantenha o Git instalado.

O inicializador também aceita --script ps, --script sh e --script py. No Windows, o padrão é PowerShell; nos demais sistemas, shell. A variante Python é uma escolha explícita disponível. ^[3]

Terminal e chat são lugares diferentes

Instalação, atualização e configuração usam o terminal. As etapas de trabalho usam o chat do agente. No Copilot atual, o padrão é instalar skills em .github/skills/ e chamá-las com hífen. ^[4]

Ambiente ou modo	Exemplo de chamada
Copilot, modo padrão de skills	/speckit-specify
Notação de comandos com pontos, usada em referências e outros modos	/speckit.specify
Codex, no modo de skills	$speckit-specify
Kimi, no modo de skills	/skill:speckit-specify

Portanto, um tutorial com /speckit.specify não está necessariamente errado. Ele pode estar descrevendo outro modo de integração. Não misture sintaxes: use a que a sua integração instalou. Neste artigo, os exemplos de chat usam o padrão atual do Copilot. ^[4]

Abra o chat na pasta do projeto, escolha uma sessão do agente com acesso aos arquivos e digite /speckit- para localizar as skills. O VS Code permite invocar skills como comandos no chat. Execute uma etapa por mensagem e examine o resultado antes de continuar. ^[5,14]

3. A ordem atual do desenvolvimento orientado por especificação

O ciclo principal é:

VISÃO DO FLUXO

Uma vez por projeto:

constitution

Para cada funcionalidade:

specify -> plan -> tasks -> implement -> converge

Para uma funcionalidade com regras relevantes, use a sequência ampliada do guia oficial: ^[5]

ETAPAS:

/speckit-constitution

/speckit-specify

/speckit-clarify

/speckit-plan

/speckit-tasks

/speckit-analyze

/speckit-implement

/speckit-converge

Esse bloco é um mapa da ordem, não um comando para colar e executar de uma vez. A constituição é estabelecida no projeto e revisada quando os princípios mudam. As outras etapas acompanham cada funcionalidade. ^[5,6]

clarify, checklist e analyze são etapas adicionais de qualidade, não exigências universais para qualquer alteração. Na sequência ampliada, o checklist aparece depois do plano. Também é possível fazer uma revisão antecipada de requisitos, mas ela não deve ser confundida com uma ordem única e obrigatória. ^[5,6]

A regra prática é dimensionar o processo pelo risco. Uma alteração pequena precisa de pouco ritual; uma regra de permissão ou concorrência precisa de mais evidência.

4. Exemplo completo: uma agenda de serviços

Vamos usar um exemplo único: uma agenda interna para uma pequena empresa. O primeiro recorte deve permitir cadastrar clientes, consultar horários e criar, reagendar ou cancelar compromissos. Pagamentos, WhatsApp, recorrência e múltiplas unidades ficam fora desta entrega.

Os prompts abaixo são exemplos completos para esse cenário. As tecnologias são uma composição possível, não uma exigência do Spec Kit.

4.1. Constitution: estabeleça regras que realmente orientem o trabalho

A constituição registra princípios do projeto em .specify/memory/constitution.md. Evite frases como "usar as melhores práticas" sem dizer o que elas significam. ^[6,8]

CHAT DO COPILOT

/speckit-constitution Priorize simplicidade, manutenção e segurança. Valide entradas no servidor e verifique permissões em cada operação protegida. Regras críticas devem ter testes automatizados, inclusive de concorrência quando houver disputa por recursos. Não registre segredos ou dados pessoais desnecessários em logs. Toda mudança de banco deve ter estratégia de recuperação. Não amplie o escopo nem adicione infraestrutura sem justificar a necessidade. Registre em português as decisões do projeto.

Para avançar: a equipe deve conseguir explicar como verificar cada princípio. "Código excelente" não é verificável. "Operações protegidas verificam permissão no servidor" é.

4.2. Specify: descreva o comportamento, não a arquitetura

Esta etapa produz a especificação da funcionalidade. Informe quem usa, o problema, as regras, os limites e os resultados esperados. Deixe frameworks e banco de dados para o plano. ^[7]

CHAT DO COPILOT

/speckit-specify Crie uma agenda interna para uma empresa de serviços. Usuários autenticados, cadastrados previamente, podem cadastrar clientes com nome e telefone, consultar a agenda diária e semanal e criar, reagendar ou cancelar compromissos para profissionais previamente cadastrados. Não permita horários sobrepostos para o mesmo profissional, inclusive com solicitações simultâneas. Cancelamentos liberam o horário e preservam o histórico. Use o fuso America/Sao_Paulo na experiência do usuário. Não inclua pagamentos, WhatsApp, recorrência, cadastro público nem múltiplas unidades. Inclua cenários de aceite e testes automatizados para conflitos, cancelamentos e acesso não autorizado. Registre as dúvidas de negócio antes de assumir regras.

Para avançar: leia o spec.md. Confira se o agente transformou alguma suposição em requisito. Se aparecer, por exemplo, uma regra de multa por cancelamento, ela deve ser removida ou discutida, não aceita por estar bem escrita.

4.3. Clarify: resolva as ambiguidades que mudam o resultado

O comando faz perguntas direcionadas e incorpora as respostas à especificação. Responder apenas no chat, sem conferir o documento atualizado, deixa a decisão fora do registro do projeto. ^[6]

CHAT DO COPILOT

/speckit-clarify Priorize duração dos compromissos, limites de horário, permissões, cancelamento e reagendamento. Esclareça se um compromisso pode começar exatamente quando outro termina e o que acontece quando duas pessoas reservam o mesmo horário. Não invente decisões comerciais.

Para este exemplo, adotaremos as seguintes decisões: compromissos com duração positiva; horários adjacentes permitidos; somente um pedido concorrente confirmado; reagendamento recusado sem perder o horário original; cancelamento sem exclusão do histórico. Todos os operadores autenticados podem trabalhar na agenda da única empresa.

Envie essas respostas e confirme que elas foram incorporadas ao spec.md. Uma regra importante não deve depender da memória da conversa.

4.4. Plan: transforme as regras em uma solução técnica

O planejamento organiza as decisões de implementação e pode gerar pesquisa, modelo de dados, contratos de interface e roteiro de validação. Nem toda aplicação precisa de todos os artefatos; eles devem servir ao projeto. ^[7]

CHAT DO COPILOT

/speckit-plan Use Next.js com TypeScript e PostgreSQL, em uma aplicação modular simples. Separe interface, regras de negócio e persistência. Selecione e justifique uma biblioteca mantida para autenticação, sem criar criptografia ou sessões caseiras. Planeje a prevenção transacional de reservas sobrepostas e o reagendamento atômico. Defina contratos para criar, consultar, reagendar e cancelar, incluindo erros e permissões. Use dados fictícios no ambiente local. Inclua testes unitários, de integração e ponta a ponta para os cenários de aceite. Padronize os scripts npm: lint, typecheck, test, test:e2e e build. Documente execução, migrações e recuperação no quickstart.md. Não adicione microsserviços, filas ou cache sem necessidade demonstrada.

Para avançar: o plano precisa explicar como uma regra será garantida. "Verificar disponibilidade antes de salvar" é uma descrição insuficiente quando duas solicitações podem passar pela mesma verificação simultaneamente. Exija uma estratégia de concorrência e um teste que a exercite.

Um contrato de interface também deve dizer mais do que o nome de um endpoint: quais entradas aceita, quem pode usá-lo, o que devolve e como comunica uma reserva recusada. Isso permite revisar frontend e backend contra o mesmo combinado.

4.5. Checklist: revise a qualidade dos requisitos

O checklist personalizado verifica se os requisitos estão claros e completos. Ele não é uma suíte de testes do software e não comprova que a implementação funciona. ^[7]

CHAT DO COPILOT

/speckit-checklist Gere um checklist de qualidade dos requisitos com foco em concorrência, fuso horário, permissões e preservação do histórico. Avalie se os comportamentos estão definidos, sem tratar o checklist como teste da implementação.

Compare: "o sistema bloqueia sobreposições?" é uma pergunta de teste. "A especificação define quais intervalos contam como sobreposição?" é uma pergunta sobre a qualidade do requisito.

O checklist customizado pertence ao revisor. Marcar [x] significa que o critério de qualidade foi revisado e atendido, não que o código está pronto. Existe também checklists/requirements.md, mantido pelo fluxo de especificação; não confunda esse artefato com a aprovação dos checklists personalizados. ^[7]

4.6. Tasks: gere entregas pequenas e verificáveis

As tarefas devem trazer ordem, dependências, arquivos envolvidos e relação com as histórias de usuário. O marcador [P] indica possibilidade de paralelismo, não uma autorização para ignorar dependências. ^[7]

CHAT DO COPILOT

/speckit-tasks Gere tarefas por história de usuário, com dependências e caminhos dos arquivos. Inclua explicitamente os testes solicitados no spec.md e no plano. Relacione os testes de concorrência, cancelamento, reagendamento e permissões aos respectivos critérios de aceite. Mantenha cada entrega pequena o suficiente para revisão independente.

Não presuma que os testes aparecerão automaticamente. O modelo de geração de tarefas condiciona sua inclusão ao pedido explícito ou à adoção de desenvolvimento orientado por testes. Peça-os na especificação e confira o tasks.md. ^[7]

Para revisar a lista, procure uma cadeia concreta: requisito de impedir reserva simultânea, tarefa de garantir a exclusão mútua no banco e teste concorrente. Uma tarefa genérica chamada "criar backend" não oferece esse controle.

4.7. Analyze: encontre contradições antes do código

CHAT DO COPILOT

/speckit-analyze

O comando compara especificação, plano e tarefas, sem editar os arquivos. Um relatório não corrige as lacunas por conta própria: ajuste o documento responsável e execute a análise novamente. ^[6]

No exemplo, uma inconsistência seria o spec.md exigir preservação do histórico enquanto o plano propõe excluir registros cancelados. Outra seria exigir controle de concorrência e não ter nenhuma tarefa para implementá-lo.

Para avançar: resolva primeiro os conflitos que afetam comportamento, segurança ou viabilidade. Não transforme uma falha conhecida de requisito em "ajuste para depois" apenas para começar a programar.

4.8. Implement: execute por partes e revise o resultado

O agente executa o tasks.md. Em funcionalidades maiores, limite cada rodada a uma parte revisável. O fluxo padrão consulta o estado dos checklists antes de implementar e não deve aprovar silenciosamente seus itens. ^[6]

CHAT DO COPILOT

/speckit-implement Execute somente as fases de preparação e fundação do tasks.md. Rode as validações aplicáveis e pare antes das histórias de usuário. Informe arquivos alterados, comandos executados, resultados e impedimentos. Não execute deploy nem use credenciais de produção.

Depois de revisar essa base, continue:

CHAT DO COPILOT

/speckit-implement Implemente agora a história de criar compromisso, incluindo os testes de conflito e solicitações simultâneas previstos nas tarefas. Pare ao concluir essa história para revisão antes das demais.

Prossiga com consulta, reagendamento e cancelamento conforme a organização real do tasks.md. Confira o diff, rode a aplicação e observe os testes. Uma mensagem "concluído" não substitui essa verificação.

4.9. Converge: confira o que ainda falta entregar

CHAT DO COPILOT

/speckit-converge

Depois da implementação, converge compara o código atual com a especificação, o plano e as tarefas. No comando padrão, ele não corrige o código nem reescreve os documentos: quando encontra lacunas, acrescenta tarefas ao final de tasks.md. ^[7]

Se houver tarefas adicionais, revise-as, execute /speckit-implement e rode /speckit-converge novamente. O resultado Converged indica que essa análise não encontrou trabalho pendente em relação aos artefatos. Não é uma certificação de segurança nem prova de que todos os testes passaram. ^[7]

Se o ciclo continuar criando trabalho sem terminar, pare e examine a origem de cada tarefa. Pode haver requisito ambíguo, tarefa mal delimitada ou escopo sendo ampliado. Corrija a causa em vez de pedir "continue" indefinidamente.

O objetivo não é fazer a IA declarar sucesso. É conseguir demonstrar o que foi entregue, o que foi verificado e o que ainda está pendente.

5. Como comprovar que a agenda ficou pronta

Antes de discutir aparência ou acrescentar funcionalidades, teste o comportamento combinado. Para o exemplo, estes são critérios de aceite propostos:

Cenário	Resultado esperado
Reservar o mesmo profissional das 09:00 às 10:00 e das 09:30 às 10:30	O segundo intervalo é recusado
Um compromisso termina às 10:00 e outro começa às 10:00	Os horários adjacentes são aceitos
Duas solicitações simultâneas disputam o mesmo horário	Apenas uma é confirmada, sem dupla reserva persistida
Cancelar um compromisso e reservar seu horário	O horário fica disponível e o cancelamento permanece no histórico
Reagendar para um horário ocupado	A mudança é recusada e o compromisso original permanece intacto
Chamar diretamente uma operação protegida sem autenticação	O servidor recusa o acesso, independentemente da interface

No ambiente de teste configurado pelo quickstart.md, execute os scripts que foram solicitados no plano:

TERMINAL

npm run lint
npm run typecheck
npm run test
npm run test:e2e
npm run build

Esses nomes são uma convenção do exemplo, não comandos do Spec Kit. A implementação deve tê-los criado no package.json, e o ambiente precisa cumprir os pré-requisitos descritos no guia local. Registre as saídas e diferencie "passou", "falhou" e "não foi executado".

Aprovação técnica também inclui revisar migrações, tratamento de erros, dados de exemplo e segredos. A publicação em produção continua sendo uma decisão separada, com o procedimento de entrega da equipe.

6. Onde ficam as especificações e como retomar o trabalho

Os documentos são parte da entrega, não arquivos temporários da conversa. A estrutura abaixo ilustra uma funcionalidade; o nome exato da pasta pode variar. ^[7]

ESTRUTURA DE REFERÊNCIA

.specify/
  memory/constitution.md
  feature.json
  integration.json
  templates/.github/
  skills/specs/
  001-agenda-servicos/
    spec.md
    plan.md
    research.md
    data-model.md
    contracts/
    quickstart.md
    tasks.md
    checklists/

spec.md define o comportamento. plan.md descreve a solução. research.md registra decisões e alternativas. data-model.md e contracts/ detalham dados e interfaces quando aplicáveis. quickstart.md orienta a execução e a validação. tasks.md organiza o trabalho. ^[7]

Um detalhe importante: a funcionalidade ativa é resolvida por .specify/feature.json, com possibilidade de substituição por SPECIFY_FEATURE_DIRECTORY. Trocar a branch Git, sozinho, não troca esse contexto. Confirme o diretório antes de planejar ou implementar outra funcionalidade. A extensão Git é opcional e pode ser instalada com specify extension add git. ^[5]

Ao abrir uma conversa nova, use uma instrução de retomada, não um resumo feito de memória:

CHAT DO COPILOT

Leia a constitution.md e identifique a funcionalidade ativa em .specify/feature.json, considerando também SPECIFY_FEATURE_DIRECTORY se estiver definido. Leia spec.md, plan.md e tasks.md dessa funcionalidade. Resuma o escopo aprovado, as tarefas concluídas, as pendências e a próxima etapa. Não altere arquivos ainda.

7. Como corrigir bugs sem refazer o fluxo de desenvolvimento

Quando uma funcionalidade existente apresenta um defeito, use o processo de bugs. Instale sua extensão na raiz do projeto já inicializado: ^[9]

TERMINAL

specify extension add bug

O fluxo é diagnosticar, corrigir e verificar. Cada bug recebe um identificador curto, o slug, reutilizado em todas as etapas. No caso da agenda:

CHAT DO COPILOT

/speckit-bug-assess "Duas requisições simultâneas conseguem confirmar o mesmo profissional no mesmo intervalo. Reprodução: enviar duas reservas concorrentes para um horário livre e consultar os registros persistidos. Esperado: somente uma reserva confirmada e um conflito controlado na outra." slug=reserva-duplicada

Revise o diagnóstico. Depois, execute separadamente:

CHAT DO COPILOT

/speckit-bug-fix slug=reserva-duplicada

CHAT DO COPILOT

/speckit-bug-test slug=reserva-duplicada

Os registros ficam em .specify/bugs/reserva-duplicada/: assessment.md para o diagnóstico, fix.md para a correção e test.md para a verificação. No processo padrão, somente bug-fix altera o código-fonte. Diagnóstico e teste não devem transformar uma constatação em uma correção silenciosa. ^[9]

O veredito final pode ser verified, partial ou failed. partial significa que alguma verificação ficou incompleta; failed indica um problema encontrado. Uma suíte verde, sem exercitar a reprodução original, não basta para declarar o defeito verificado. ^[9]

Nossa recomendação é manter o reparo concentrado na causa. Se o agente propuser reorganizar toda a arquitetura para corrigir uma validação, peça a justificativa e separe o trabalho adicional. Refatoração pode ser necessária, mas não deve entrar escondida em um ajuste urgente.

8. Como avaliar uma ideia antes de investir em código

Para investigar uma proposta, instale a extensão de assessment. Ela pode trabalhar até em um projeto sem código-fonte. Seu resultado é uma decisão, não uma implementação. ^[10]

TERMINAL

specify extension add assess

Imagine que a empresa queira atender sem internet. Em vez de pedir imediatamente "adicione modo offline", execute cada etapa no chat, revisando o documento gerado:

CHAT DO COPILOT

/speckit-assess-intake "Avaliar se a agenda deve permitir consultas e novos agendamentos sem internet, com sincronização posterior. Precisamos entender a frequência real de indisponibilidade, o impacto no atendimento e o risco de conflitos." slug=agenda-offline

/speckit-assess-research slug=agenda-offline

/speckit-assess-define slug=agenda-offline

/speckit-assess-shape slug=agenda-offline

/speckit-assess-decide slug=agenda-offline

As etapas produzem intake.md, research.md, problem.md, concept.md e decision.md em .specify/assessments/agenda-offline/. A pesquisa deve considerar evidências favoráveis e contrárias. Afirmações sem fonte continuam sendo suposições. ^[10]

Para esse caso, peça uma comparação entre alternativas concretas: consultar uma cópia local sem permitir novas reservas, registrar solicitações pendentes de confirmação ou permitir criação offline com tratamento posterior de conflitos. Não é a mesma experiência, o mesmo custo nem o mesmo compromisso com o usuário.

O resultado pode ser go, needs-clarification ou kill: seguir, resolver incertezas ou encerrar a proposta por enquanto. Sem evidência suficiente, o correto é esclarecer, não fabricar uma aprovação. ^[10]

Quando surgirem informações novas, atualize os artefatos existentes e suas conclusões, em vez de regenerar todas as etapas. Caso a decisão seja seguir com software, a passagem para SDD é explícita, não automática: ^[10]

CHAT DO COPILOT

/speckit-specify Use o resumo de encaminhamento em .specify/assessments/agenda-offline/decision.md para especificar somente o conceito aprovado. Preserve os limites e as decisões registradas. Não inclua alternativas que foram descartadas.

9. Como adotar o Spec Kit em um sistema existente

Não é necessário reconstruir o sistema nem documentar retrospectivamente cada comportamento antes de começar. Adote o processo na próxima mudança bem delimitada. ^[11]

Primeiro, preserve o estado atual em um commit revisado, stash ou backup. Em um repositório Git, crie uma branch de adoção e inicialize na raiz:

TERMINAL

git status
git switch -c chore/adotar-spec-kit
specify init --here --force --integration copilot
git status
git diff

--here usa a pasta atual. --force permite inicializar uma pasta não vazia e pode substituir arquivos em caminhos gerenciados conflitantes. Ele não deve ser usado sem revisar o estado inicial. Examine também os arquivos novos listados pelo git status, que ainda podem não aparecer no git diff. ^[11]

Antes de escrever a constituição, peça um reconhecimento limitado do projeto:

CHAT DO COPILOT

Leia o README, as configurações de build e CI, os testes e os módulos relacionados à mudança. Identifique arquitetura, dependências, padrões existentes e restrições de compatibilidade, citando os arquivos que sustentam cada conclusão. Não altere código nem proponha uma reescrita geral.

Capture na constituição os padrões reais ou os que a equipe decidiu adotar. Depois especifique a mudanção, indicando o que deve permanecer intacto: contratos de API, permissões, dados históricos, comportamento de integrações ou formatos de exportação. ^[11]

Para uma exportação CSV, por exemplo, não peça apenas "adicione um botão para exportar". Diga quais filtros valem, quais usuários podem exportar, quais campos entram e como tratar caracteres especiais. O que precisa ser preservado é parte do requisito.

Quando o requisito mudar depois da implementação

Mantenha código e documentos coerentes. Para equipes que adotam a especificação como contrato vivo, a rotina recomendada é atualizar a regra aprovada, reconciliar plano e tarefas, implementar e verificar novamente. Evite regenerar documentos indiscriminadamente e perder decisões ou evidências anteriores. A documentação também admite preservar cada funcionalidade como registro histórico; escolha conscientemente o modelo da equipe. ^[13]

Uma nova regra comercial deve voltar para a especificação. Um defeito de aderência à regra existente pede diagnóstico e correção. Essa distinção ajuda a não chamar mudança de escopo de bug.

10. Como personalizar o processo sem perder o controle

A personalização atual combina mecanismos diferentes. Use cada um para o problema certo. ^[12]

Necessidade	Mecanismo
Acrescentar comandos, capacidades ou integrações	Extension
Adaptar modelos, terminologia ou comportamento existente	Preset
Ajustar um modelo somente neste projeto	Override local
Automatizar uma sequência de etapas	Workflow
Distribuir uma composição pronta para um papel ou equipe	Bundle

Um padrão reutilizável de requisitos, revisão de segurança e critérios de entrega pode virar um preset. Já um novo processo de diagnóstico ou integração pede uma extensão. Um bundle pode reunir os componentes aprovados para a equipe. ^[12]

Para ajustes pontuais de templates, a pasta indicada é .specify/templates/overrides/. A ordem padrão de substituição prioriza overrides locais, depois presets, extensões e templates do núcleo. ^[12]

Comece pelo processo padrão e personalize um problema demonstrado. Instalar muitas extensões de uma vez dificulta identificar qual delas mudou o comportamento. Revise origem, versão, arquivos e hooks dos componentes: eles podem acrescentar ações ao fluxo. As descrições deste guia se referem ao comportamento padrão, sem customizações que o substituam.

11. Como atualizar uma instalação antiga com segurança

Há duas camadas distintas: o executável specify, instalado na máquina, e os arquivos gerenciados em cada projeto. Atualizar somente o CLI não instala automaticamente novas skills nos repositórios existentes. ^[8]

Na raiz de um projeto, depois de preservar e revisar as alterações locais:

TERMINAL

specify version
specify self check
specify self upgrade --dry-run
specify self upgrade
specify integration status
specify integration upgrade copilot
specify extension update
specify version
specify integration status

self check consulta a disponibilidade de atualização. --dry-run mostra a operação prevista. Já self upgrade, sem essa opção, executa a atualização. A atualização automática atende instalações persistentes via uv tool e pipx; outros ambientes recebem orientação específica. ^[8]

Para fixar a versão desta edição, substitua a etapa de atualização do CLI por:

TERMINAL

specify self upgrade --tag v1.0.8

Se o CLI for antigo e ainda não reconhecer self upgrade, a alternativa para uma instalação via uv tool é:

TERMINAL

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

A atualização da integração usa um manifesto para detectar modificações locais. Se houver bloqueio, examine os arquivos antes de acrescentar --force. specify init --here --force fica como recurso de recuperação para situações específicas, não como primeira escolha de atualização. ^[8]

Migrando o Copilot para o modo atual de skills

Uma instalação no modo de comandos pode continuar nesse modo. Para migrá-la explicitamente, o comando documentado é: ^[4]

TERMINAL

specify integration upgrade copilot --integration-options="--skills"

Presets registrados podem bloquear a troca de layout. Nesse caso, registre a configuração, siga a orientação para remover os presets afetados, migre e reinstale-os. Depois confira o diff e reabra o editor. ^[4]

O uso de uvx merece atenção: ele executa uma cópia temporária para aquela chamada. Uma execução com uma versão nova via uvx não atualiza o specify persistente da máquina. ^[8]

12. Problemas comuns e como diagnosticar

Sintoma	O que verificar primeiro
uv ou specify não é encontrado	Instalação e PATH. Reabra o terminal e confirme com uv --version ou specify version.
/speckit- não aparece no chat	Pasta aberta, integração instalada e modo de invocação. Consulte specify integration status e verifique .github/skills/ no modo padrão do Copilot.
converge não existe no projeto	Versão do CLI e atualização dos arquivos da integração. Atualizar apenas um deles pode deixar o projeto antigo.
A IA trabalha na funcionalidade errada	.specify/feature.json e SPECIFY_FEATURE_DIRECTORY. Não deduza o contexto apenas pela branch.
A implementação pede confirmação por checklist pendente	Revise os requisitos e a aprovação correspondente. Não marque tudo como concluído só para liberar a execução.
bug-test termina como partial	Verifique qual reprodução, ambiente ou evidência faltou. Complete a verificação, sem tratar o resultado como sucesso.

Essas verificações combinam as orientações de integração, contexto da funcionalidade, atualização e verificação de bugs. Se o editor ainda não reconhecer arquivos recém-atualizados, reinicie-o e confira novamente o estado da integração. ^[4,5,6,8,9]

13. Perguntas frequentes

O Spec Kit é gratuito?

O projeto tem licença MIT. Isso não inclui automaticamente o acesso ao agente ou ao modelo de IA: verifique separadamente as condições do serviço escolhido. ^[1]

Preciso usar GitHub Copilot?

Não. Há integrações com outros agentes. O Copilot é a referência deste guia, mas a seleção pode ser feita com --integration durante a inicialização. Consulte as opções com specify integration list. ^[4]

Preciso executar todos os comandos em toda alteração?

Não. Escolha primeiro o processo correto e acrescente revisões conforme o risco. Para uma funcionalidade pequena, o ciclo principal de SDD continua incluindo converge; para um defeito, há o fluxo próprio de bugs. ^[5,9]

Posso escrever os requisitos em português?

Nos exemplos deste guia, sim: os nomes dos comandos permanecem os mesmos e as instruções são escritas em português. Peça explicitamente que os documentos também usem o idioma da equipe e revise a terminologia de negócio.

Posso transformar as tarefas em issues do GitHub?

O comando opcional /speckit-taskstoissues faz essa passagem a partir de tasks.md. Ele requer um remoto origin do GitHub e acesso às ferramentas GitHub MCP para listar e criar issues. Não é um pré-requisito para implementar. ^[6]

O Spec Kit substitui testes, revisão de código ou validação com o cliente?

Não trate o processo dessa forma. Uma especificação pode estar coerente e descrever a necessidade errada. Um código pode parecer aderente e falhar em execução. Valide a necessidade com quem usa, a solução com quem responde tecnicamente e o comportamento com evidência.

14. O que realmente torna o processo útil

O valor do Spec Kit não está em gerar mais documentos. Está em tornar o trabalho compreensível e revisável: o problema foi definido, as decisões ficaram registradas, a implementação seguiu um plano e o resultado foi confrontado com o que se prometeu entregar.

Na Inova e-Business, nossa recomendação é usar a IA para acelerar o trabalho sem abrir mão da engenharia. Comece com uma funcionalidade delimitada, revise cada transição e aumente a automação conforme o processo se mostrar confiável.

IA acelera o desenvolvimento, mas sem engenharia acelera riscos. O critério de sucesso continua sendo software que resolve o problema e pode ser mantido com confiança.

Referências e documentação oficial

Documentação consultada em 17 de setembro de 2026. Os exemplos de comandos estão alinhados à versão v1.0.8; integrações e customizações podem alterar arquivos e formas de invocação.

[1] GitHub Spec Kit. README oficial (v1.0.8). README

[2] GitHub Spec Kit. Release 1.0.8, publicada em 17/09/2026. Release v1.0.8

[3] Spec Kit. Instalação, pré-requisitos e opções do CLI. Installation Guide

[4] Spec Kit. Integrações, sintaxe, modos e migração. Supported AI Coding Agent Integrations

[5] Spec Kit. Sequência de trabalho e contexto da funcionalidade. SDD Quickstart

[6] Spec Kit. Referência dos comandos de desenvolvimento. Agentic SDD

[7] GitHub Spec Kit. Modelos oficiais dos comandos (v1.0.8). specify | plan | checklist | tasks | converge

[8] Spec Kit. Atualização do CLI e dos arquivos do projeto. Upgrade Guide

[9] Spec Kit. Diagnóstico, reparo e verificação de bugs. Bug Fixing Quickstart | Agentic Bug Fix

[10] Spec Kit. Avaliação de ideias, evidências e decisões. Idea Assessment Quickstart | Agentic Idea Assessment

[11] Spec Kit. Adoção em sistemas existentes. Adopting Spec Kit in an Existing Project

[12] Spec Kit. Extensões, presets, overrides, workflows e bundles. Customize Spec Kit

[13] Spec Kit. Evolução e persistência das especificações. Evolving Specs in Existing Projects

[14] Visual Studio Code. Skills no Copilot e chamadas pelo chat. Use Agent Skills in VS Code

[15] Spec Kit. Instalação do uv por sistema operacional. Installing uv