GitHub Spec Kit 1.0: guia prático de spec-driven development

Spec não é documentação. É o contrato de operação entre a sua intenção e o agente que vai executá-la. O GitHub Spec Kit coloca esse contrato no centro do seu workflow.

O GitHub Spec Kit é o toolkit open source do GitHub que leva o spec-driven development para dentro do seu agente de IA. Você instala a CLI specify, roda specify init no projeto, e o agente ganha um pipeline de skills que transforma a descrição do que você quer numa implementação verificada contra essa descrição. Funciona com GitHub Copilot, Claude Code, Gemini CLI, Cursor, Codex e mais de quarenta outros agentes.

A resposta curta, para quem quer só o resumo: o Spec Kit é um toolkit open source, publicado pelo GitHub sob licença MIT, que dá a agentes de IA para código processos estruturados, templates e resultados documentados. O processo central é spec-driven development; correção de bug e avaliação de ideia vêm como extensions opcionais. Chegou à 1.0 em agosto de 2026 e tem cerca de 140.000 estrelas no GitHub.

Se o método por trás é novidade para você, comece por o que é spec-driven development. A ferramenta vem depois do método. E se você está pesando o Spec Kit contra as alternativas, comparei ele de frente em OpenSpec vs. Spec Kit vs. Superpowers, com o pi-sdd-kit na mistura.

O que mudou a caminho da 1.0

A maioria dos guias do Spec Kit foi escrita no lançamento, no fim de 2025. Metade do que eles dizem está errado agora. A parte engraçada é que a 1.0 em si quase não mudou nada: as notas de release dizem que uma versão major não precisa mais sinalizar dor de migração, e o changelog é de correções de rotina. As mudanças de verdade chegaram nos meses anteriores.

Como o Spec Kit chegou à 1.0

1. 18 de jun. de 2026v0.11.2: o converge chega

   Uma etapa depois do implement que confere o código contra a spec, o plan e as tasks, e adiciona o que estiver faltando.

2. 5 de ago. de 2026v0.16.0: skills por padrão

   O Copilot migra para o modo skills. O Claude Code já instalava skills em .claude/skills.

3. 21 de ago. de 2026v1.0.0

   A versão major, sem mudanças que quebram compatibilidade.

4. 1 de set. de 2026v1.0.3: --require-spec

   Analyze e converge se recusam a rodar sem um spec.md em disco.

5. 15 de set. de 2026v1.0.7: três processos

   O README agora apresenta spec-driven development, correção de bug e avaliação de ideia como pontos de entrada independentes.

6. 21 de set. de 2026v1.0.9: bundles

   Bundles oficiais empacotam as configurações de correção de bug e avaliação numa única instalação.

7. 29 de set. de 2026v1.0.13: extension do github

   O taskstoissues começa a sair do core para uma extension do github empacotada.

Quatro mudanças importam mais que o resto. Branches agora são opt-in: o core do Spec Kit não toca mais no git, e as branches numeradas por feature vêm de uma git extension que você adiciona por conta própria. As pastas de feature mudaram para specs/ na raiz do repositório. O arquivo de contexto do agente (CLAUDE.md no Claude Code) agora é uma extension opt-in, então o specify init não edita ele mais. E existe um caminho curto oficial para trabalho pequeno, que responde à reclamação mais comum sobre a ferramenta.

O problema que o Spec Kit resolve

Agentes de IA para código são rápidos. Também são stateless e literais. Descreva um objetivo de forma vaga e o agente vai na direção da implementação mais comum daquela descrição, não da sua intenção específica. O resultado compila. Está sintaticamente correto. Só não faz o que você queria.

A solução não é um prompt melhor. É um artefato estruturado, escrito e aprovado antes de a implementação começar, que dá ao agente a clareza que ele não consegue inferir de uma mensagem no chat. Esse artefato é a spec.

O Spec Kit não muda essa ideia. Ele a operacionaliza. Em vez de manter a disciplina na mão, você ganha skills que conduzem o agente por cada fase, templates que obrigam você a escrever as coisas certas e uma estrutura de diretórios que mantém os artefatos organizados entre features.

Instalar e inicializar

O Spec Kit exige Python 3.11 ou mais recente e uv. Git agora é opcional: você só precisa dele se ligar a git extension.

Instalar a CLI specify

1. Pelo PyPI

   $ uv tool install specify-cli

2. Fixada numa release

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

3. Rodar uma vez sem instalar

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

pipx install specify-cli e pip install specify-cli também funcionam. Depois de instalado, escolha o seu agente:

Inicializar para o seu agente

1. Claude Code

   $ specify init my-project --integration claude

2. GitHub Copilot

   $ specify init my-project --integration copilot

3. Gemini CLI

   $ specify init my-project --integration gemini

4. OpenAI Codex

   $ specify init my-project --integration codex

A flag --integration diz ao specify qual agente você usa, e ele instala as skills ou comandos no formato que aquele agente espera. No Claude Code isso significa skills em .claude/skills. Omita a flag num terminal interativo e o specify pergunta. Em CI ou em execuções via pipe, o padrão é o Copilot. specify integration list mostra todas elas, 42 no momento em que escrevo, e um projeto pode carregar mais de uma.

Dois hábitos valem a pena manter. Faça upgrade com specify self upgrade em vez de reinstalar. E se você quiser que o Spec Kit mantenha uma seção no seu CLAUDE.md ou AGENTS.md, adicione isso explicitamente com specify extension add agent-context. Sem essa extension, o Spec Kit nunca toca no seu arquivo de contexto do agente.

A estrutura do Spec Kit depois de uma feature

• .specify/
  • memory/
    • constitution.md// princípios do projeto, lidos pelo plan e pelo converge
  • scripts/// helpers que as skills chamam para resolver a feature ativa
  • templates/// templates de spec, plan e tasks que restringem o que o agente escreve
  • feature.json// aponta para a pasta da feature ativa, em vez da branch do git
• specs/
  • 001-feature-name/feature
    • spec.md// requisitos funcionais e user stories
    • plan.md// arquitetura técnica e escolhas
    • research.md// pesquisa de bibliotecas e APIs reunida durante o planejamento
    • data-model.md// entidades e schemas
    • quickstart.md// como rodar e verificar a feature
    • contracts/// contratos de API da feature
    • tasks.md// tarefas ordenadas com marcadores de paralelismo, mais fases de convergência
• .claude/skills/// as skills speckit-*, quando a integração é o Claude Code

Quem faz o trabalho de verdade são os templates dentro de .specify/templates/. Eles instruem o agente a marcar ambiguidades com [NEEDS CLARIFICATION] em vez de chutar, a separar requisitos funcionais de decisões técnicas e a produzir checklists que funcionam como critérios de aceite dentro de cada artefato. A disciplina está embutida nos templates, não na sua força de vontade.

O pipeline, em ordem

Depois do specify init, o agente tem o pipeline completo. Só uma regra é dura: uma spec precisa existir antes do plan. Tudo marcado como opcional é um gate de qualidade que você adiciona quando o trabalho merece.

O pipeline do Spec Kit: da constitution ao converge

Entrada

Uma descrição do que você quer construir e por quê, sem decisão de stack

↓

1. 01/speckit-constitution (uma vez por projeto)

   Escreve os princípios que regem o projeto em .specify/memory/constitution.md: regras de qualidade de código, requisitos de teste, restrições. O plan confere contra ela e o converge trata um MUST quebrado como crítico.

   ↓
2. 02/speckit-specify (por feature)

   Transforma a sua descrição em spec.md com requisitos funcionais e user stories, numa pasta nova dentro de specs/. Só o quê e o porquê. Nada de decisão de stack aqui.

   ↓
3. 03/speckit-clarify (opcional)

   Faz perguntas estruturadas para expor lacunas e contradições na spec, e registra as respostas numa seção Clarifications.

   ↓
4. 04/speckit-plan (por feature)

   Recebe a spec e as suas escolhas de stack, e produz plan.md, além de research.md, data-model.md, quickstart.md e contracts/. Toda escolha técnica remete a um requisito.

   ↓
5. 05/speckit-checklist (opcional)

   Gera checklists de qualidade para os artefatos, que equivalem a testes unitários para texto em inglês: a spec é inequívoca e completa?

   ↓
6. 06/speckit-tasks (por feature)

   Produz tasks.md: unidades ordenadas e testáveis de forma independente, com marcadores [P] nas tarefas que podem rodar em paralelo.

   ↓
7. 07/speckit-analyze (opcional)

   Confere consistência entre os artefatos: todo requisito chega ao plan, e toda decisão do plan chega a uma task?

   ↓
8. 08/speckit-implement (por feature)

   Executa as tarefas na ordem de dependência, respeitando os marcadores de paralelismo, e reporta o progresso.

   ↓
9. 09/speckit-converge (por feature)

   Confere o código contra spec, plan, tasks e constitution, e adiciona as lacunas como novas tasks. Repita implement e converge até ele reportar converged.

↓

Saída

Uma implementação verificada contra a própria spec, com um rastro auditável da intenção até o código

Para features menores, o quickstart oficial reduz isso a cinco: specify, plan, tasks, implement, converge. Os nove completos são para trabalho de produção.

Uma nota sobre sintaxe, porque todo guia mais antigo escreve diferente. Os nomes com hífen acima são skills, o padrão no Claude Code e no Copilot. Você ainda vai ver a forma com ponto (/speckit.specify) na documentação de referência e em posts antigos. O Codex usa $speckit-specify. Mesmos comandos, grafia diferente por agente. /speckit-taskstoissues, que transforma o tasks.md em GitHub Issues, ainda funciona mas está migrando para a github extension empacotada.

Converge: a etapa que admite que o agente diz que terminou cedo demais

Todo time que usou o Spec Kit em 2025 bateu na mesma parede. O agente terminava o implement, reportava sucesso, e o código cobria a maior parte da spec. A maior parte. O converge, adicionado em junho, é o Spec Kit admitindo isso em voz alta.

Depois do implement, o converge lê a spec, o plan, as tasks e a constitution, e confere a codebase contra eles. Cada lacuna ganha uma classe: missing, partial, contradicts ou unrequested (código que ninguém pediu). Ele nunca reescreve a sua spec, o seu plan ou as tasks existentes. Só adiciona uma nova fase de convergência ao tasks.md. Rode implement de novo, depois converge de novo. Cada passagem encontra menos. Quando não sobra nada, o tasks.md fica byte a byte igual e o converge reporta converged.

É o design certo. Ele não confia no relato do próprio agente sobre o que fez. Confere o artefato contra o código, que é exatamente a etapa de revisão que a maioria pula numa noite cansada.

O gate continua seu

Aqui está o que não mudou: não existe gate de aprovação entre as fases. Desde a 1.0.3, analyze e converge rodam com --require-spec, que faz eles falharem se o spec.md estiver faltando. Leia isso com atenção. Ele confere que o arquivo existe. Não confere que um humano leu, ou que concordou com ele.

Então a decisão de passar de tasks para implement continua sua, e nada no Spec Kit impede um agente afobado de avançar em cima de um rascunho. A documentação do workflow é honesta sobre isso: o seu papel em cada fase é refletir e refinar, não aprovar por omissão. Se você quer o gate imposto, adiciona você mesmo. Essa é a lacuna que o token .status do pi-sdd-kit fecha, e eu volto a isso mais abaixo.

A constitution não é opcional

Toda ferramenta de SDD precisa de uma camada de memória estável: o contexto do projeto do qual todas as features se alimentam. No Spec Kit, essa camada é a constitution.

A constitution fica em .specify/memory/constitution.md e reúne os princípios que regem todo o desenvolvimento: quais abstrações são inegociáveis, requisitos de teste, regras de simplicidade, políticas de segurança. Você escreve ela uma vez com /speckit-constitution. O plan roda uma checagem de constitution contra ela, e o converge trata um princípio MUST quebrado como uma lacuna crítica.

Aqui está o tipo que eu escreveria para um serviço de pagamentos, resumido. Segue o formato do próprio template do Spec Kit: princípios numerados, seções extras, governance e uma linha de versão.

# Ledger Service Constitution

## Core Principles

### I. Money Is Integer (NON-NEGOTIABLE)

All amounts are stored and computed as integer minor units (cents, satoshis).
No floats anywhere in a money path. Rounding happens once, at display.

### II. Every Write Is Idempotent

Every operation that moves money takes an idempotency key. A retry with the
same key returns the original result and never charges twice.

### III. Real Database in Integration Tests

Integration tests run against Postgres, not mocks. A test that passes on a
mock and fails on the real database is a failed test.

### IV. Contract Tests First

Every external API (exchange, custody, payment provider) gets a contract test
that fails before any implementation starts.

### V. Simplicity

No new service, queue, or abstraction without a requirement in spec.md that
needs it. Complexity must be justified in plan.md.

## Security Requirements

Secrets come from the environment, never from the repo. Every endpoint that
moves money requires an authenticated session and writes an audit log entry.

## Governance

This constitution overrides conflicting guidance in any spec or plan.
Amendments need a written rationale and a version bump.

**Version**: 1.0.0 | **Ratified**: 2026-09-30 | **Last Amended**: 2026-09-30

O próprio repositório do Spec Kit roda com uma constitution com emendas versionadas (major, minor, patch) e um relatório de sincronização quando um princípio muda. Isso diz muito sobre a seriedade com que o projeto trata a consistência arquitetural. Escreva a constitution no primeiro dia e mantenha ela viva.

Os três casos de uso do GitHub

O próprio GitHub descreve três situações em que o Spec Kit paga o custo de setup.

Desenvolvimento greenfield, que o anúncio chama de zero-to-one, é o caso mais óbvio. Você tem uma ideia, não uma codebase. O workflow do Spec Kit obriga você a definir como é o sucesso antes de o agente escrever qualquer coisa, o que elimina o modo de falha mais comum: o agente constrói algo tecnicamente correto que não bate com o que você imaginou.

Trabalho em features de sistemas existentes, o caso brownfield, é onde a ferramenta é mais útil no dia a dia. Adicionar coisas a uma codebase real exige capturar como a nova feature interage com o que já existe. A spec codifica essas restrições de interação. O plano codifica decisões de arquitetura que respeitam o sistema existente. O resultado é código novo que parece nativo, e não um puxadinho. O Spec Kit agora vem com um guia dedicado para adotar ele num projeto existente, e você ainda precisa dar ao agente contexto suficiente sobre a codebase que já existe.

Modernização de legado é o caso mais difícil e o mais interessante. Quando a intenção original de um sistema se perdeu no tempo e em código sem documentação, o Spec Kit dá um processo para capturar a lógica de negócio essencial numa spec moderna antes de reconstruir. Você não está só migrando código. Está reconstruindo intenção, que é o problema mais difícil.

A crítica da Böckeler, um ano depois

Birgitta Böckeler, da Thoughtworks, publicou a melhor avaliação independente do Spec Kit em outubro de 2025, no martinfowler.com. Ela estava certa, e o Spec Kit claramente leu: a própria documentação sobre persistência de spec cita o artigo dela pelo nome. Aqui está onde cada ponto está na 1.0.

As quatro críticas da Böckeler vs. o Spec Kit 1.0

As observações originais dela ainda descrevem a experiência padrão. A diferença é que a 1.0 te dá saídas documentadas para cada uma.

Crítica (out. 2025)	O que mudou	Veredito
Um workflow para todos os tamanhos	Caminho curto oficial, o preset lean e uma extension de bug separada	Resolvido na maior parte
Markdown demais para revisar	O preset lean reduz cada fase a um arquivo focado. Os templates padrão continuam prolixos.	Parcialmente resolvido
Agentes pulam instruções	O converge confere o código contra os artefatos e adiciona o que falta	Pego depois, não prevenido
Spec-first, não spec-anchored	Branches agora são opt-in, e a documentação nomeia três formas de manter uma spec viva	Documentado, não imposto

Um workflow para todos os tamanhos. O exemplo mais afiado dela foi uma correção de bug pequena que saiu com user stories e dezesseis critérios de aceite, incluindo “como desenvolvedor, quero que a função de transformação trate edge cases de forma elegante”. Uma marreta para quebrar uma noz. A resposta do Spec Kit são três saídas. O caminho curto do quickstart derruba os gates opcionais. O preset lean (specify preset add lean, empacotado, sem download) substitui os templates do core por prompts autocontidos que produzem um arquivo focado por fase. E bugs ganham a própria extension (specify extension add bug) com três etapas, assess, fix e test, e nenhum workflow de feature de SDD.

Volume de markdown para revisar. Cada feature ainda produz spec, plan, research, data model, quickstart, contracts e tasks por padrão. O ponto dela continua de pé: se revisar os artefatos leva o mesmo tempo que implementar a feature na mão, a conta não fecha. O lean é a correção, e você precisa escolher ele.

Agentes nem sempre seguem todas as instruções. Mais contexto na janela não é o mesmo que mais obediência. Ela viu o agente tratar notas de pesquisa sobre classes existentes como especificações novas e gerá-las de novo como duplicatas. O converge não impede isso de acontecer. Ele pega o desvio depois e transforma em tasks, que é a versão honesta de uma correção.

Spec-first contra spec-anchored. A pergunta dela era se uma spec vive para uma solicitação de mudança ou para a vida inteira de uma feature. O Spec Kit agora responde isso por escrito. A documentação nomeia três modelos: Flow-Back (editar qualquer artefato e reconciliar na mão), Flow-Forward (uma pasta de spec nova por mudança, as antigas ficam como histórico) e Living Spec (editar o spec.md como o contrato e regenerar plan e tasks a partir dele). Nenhum é o padrão, e a ferramenta não impõe nenhum. O seu time escolhe um e segue com ele.

Então use para features de tamanho relevante, em codebases greenfield ou brownfield bem conhecidas. Para trabalho exploratório e tarefas pequenas, use o caminho curto, o lean ou a bug extension, ou pule o Spec Kit de vez.

Spec Kit vs Kiro vs Claude Code com pi-sdd-kit

Três setups de SDD são comparados com mais frequência. Não são a mesma ferramenta com nomes diferentes.

Spec Kit vs Kiro vs Claude Code com pi-sdd-kit

Escopos diferentes, tradeoffs diferentes. O Spec Kit ganha em variedade de agentes. O Kiro ganha em integração com as próprias ferramentas. O pi-sdd-kit adiciona um gate de aprovação explícito e legível por máquina.

Característica	Spec Kit	Kiro	Claude Code + pi-sdd-kit
Workflow central	Pipeline de skills até o converge, em qualquer agente	Requirements, design, tasks, nas ferramentas próprias do Kiro	Slash commands de 5 fases no Claude Code
Camada de memória estável	constitution.md	steering/ (product, tech, structure)	steering/ com 4 arquivos de contexto
Gate de aprovação legível por máquina	Nenhum: --require-spec confere que o arquivo existe	Nenhum: a pessoa decide quando avançar	Arquivo .status com token explícito
Suporte a agentes	40+ integrações via specify init	Kiro IDE, CLI e web	Claude Code como principal
Artefatos por feature	7 por padrão; um arquivo por fase com o preset lean	3 arquivos: requirements, design, tasks	Pasta por feature com gate .status
Customização	Extensions, presets, workflows, bundles	Steering documents e hooks	Markdown puro, qualquer estrutura
Custo	Grátis, licença MIT	Camada grátis, planos pagos a partir de US$ 20/mês	Grátis, pacote npm open source

Esta é a visão honesta de quem usa Claude Code e pi-sdd-kit como workflow diário.

O Spec Kit é a melhor escolha quando você trabalha com vários agentes, quer um padrão open source mantido pela comunidade com um ecossistema de verdade ao redor, ou trabalha em times em que cada dev usa uma ferramenta diferente. A abordagem baseada em constitution é boa de verdade para codificar restrições da organização, e o converge é a melhor resposta que qualquer uma dessas ferramentas tem para o agente que declara o próprio trabalho concluído.

O Spec Kit serve menos quando você quer um gate legível por máquina que impeça o agente de avançar sem aprovação explícita. O token .status do pi-sdd-kit não é cerimônia: ele elimina a ambiguidade entre “escrevi a spec” e “aprovei a spec”. Um tasks.md concluído e um tasks.md aprovado são idênticos para um agente que varre o diretório. O --require-spec do Spec Kit vê a mesma coisa: um arquivo que existe. A aprovação fica na sua cabeça.

Com o Kiro, a comparação é outra. Veja o que é o Kiro para o quadro completo. A versão curta: o workflow de spec do Kiro mora dentro da própria IDE, CLI e app web do Kiro, enquanto o Spec Kit se conecta ao agente que você já usa. Os três arquivos do Kiro (requirements, design, tasks) também são mais leves que os sete padrão do Spec Kit, que é a lacuna que o preset lean fecha.

Quando o trabalho merece o Spec Kit

Esse trabalho se beneficia do Spec Kit?

Esse trabalho se beneficia do Spec Kit?. Winner: Projeto greenfield with a weighted score of 50. Scale 1-5 (5 = best).

Critério (peso)	Script avulso	Correção de bug pequena	Feature de várias sessões	Projeto greenfield
Dura mais que uma sentada (3)	1	1	4	5
Atravessa várias sessões ou pessoas do time (3)	1	2	4	5
Exige decisões de arquitetura (2)	1	1	4	5
Ganha com um documento de spec vivo (2)	1	1	3	5
Pontuação ponderada	10	13	38	50

Scale 1-5 (5 = best). Highlighted column: winner by weighted score.

O pipeline completo tem overhead real, e esse overhead não é proporcional para trabalho pequeno. A própria documentação da ferramenta já admite isso, com o caminho curto e o processo de bug como pontos de entrada separados. Não rode nove etapas para uma correção de bug.

Use o pipeline em features em que o custo de construir a coisa errada é maior que o custo da spec. Use em projetos greenfield em que você quer consistência arquitetural desde o início, carregada em todas as features. Use em times em que você quer artefatos de spec compartilhados no controle de versão, como fonte da verdade entre os devs.

Extensions, presets, workflows, bundles

A customização foi onde a 1.0 mais cresceu. Agora existem quatro mecanismos.

Extensions adicionam capacidades: novos comandos, novas fases, integrações com ferramentas como Jira ou GitHub. Várias já vêm empacotadas com a CLI e só precisam de specify extension add: git (branches por feature), agent-context (a sua seção no CLAUDE.md ou AGENTS.md), bug, assess e github. Presets mudam como os comandos existentes se comportam, sobrescrevendo os templates deles. O lean é o empacotado que vale conhecer. Workflows automatizam processos de várias etapas em YAML, com loops, fan-out e pause and resume. Bundles empacotam um conjunto selecionado de extensions, presets e workflows para um papel, como um product manager ou um pesquisador de segurança, instalado de uma vez.

Os catálogos da comunidade moram dentro do próprio repositório do Spec Kit, com mais de 130 extensions da comunidade de mais de 70 autores, buscáveis com specify extension search e specify preset search. A ordem de resolução é documentada e estável: overrides locais do projeto vencem os presets, presets vencem as extensions, extensions vencem os templates do core.

O que importa é o método, não a ferramenta

O Spec Kit é uma implementação de spec-driven development. O método existe independentemente de qualquer ferramenta. Dá para fazer SDD com arquivos markdown simples, sem CLI, sem skills, e ainda ter o benefício. O método é: escrever e aprovar uma spec antes de a implementação começar, manter a spec como fonte da verdade e usar gates claros para impedir que o agente saia correndo na frente.

O que o Spec Kit dá em cima disso é consistência, uma comunidade e o maior ecossistema do espaço. O template de constitution é bem desenhado. A separação entre spec funcional e plano técnico é clara e garantida pelos templates. O converge fecha o loop que a maioria deixa aberto. E as integrações cuidam das diferenças de formato entre mais de quarenta agentes.

Se você usa Claude Code, a abordagem que construí ao fazer sozinho uma fintech cripto com 13 apps em 70 dias está em Spec-driven development com Claude Code. A abordagem do pi-sdd-kit adiciona o gate .status e o sistema de contexto em três camadas (CLAUDE.md, steering, specs), que dão ao agente memória durável e um sinal de aprovação explícito e legível por máquina. As duas abordagens resolvem partes vizinhas do mesmo problema. Dá para aproveitar ideias das duas.

FAQ

O que é o GitHub Spec Kit?+

O GitHub Spec Kit é um toolkit open source publicado pelo GitHub sob licença MIT. Ele dá a agentes de IA para código processos estruturados, templates e resultados documentados. Você instala a CLI specify, roda specify init, e o seu agente ganha um pipeline de skills para spec-driven development: constitution, specify, clarify, plan, checklist, tasks, analyze, implement e converge.

Desde a 1.0 ele também oferece correção de bug e avaliação de ideia como extensions opcionais. Funciona com mais de 40 agentes, incluindo Claude Code, GitHub Copilot, Gemini CLI, Cursor e Codex.

O que há de novo no Spec Kit 1.0?+

Menos do que o número da versão sugere. A 1.0.0 saiu em agosto de 2026 sem mudanças que quebram compatibilidade; as grandes mudanças chegaram nas versões anteriores a ela. As que importam: a etapa converge, skills como a invocação padrão, pastas de feature em specs/ na raiz do repositório, branches do git movidas para uma extension opt-in, o arquivo de contexto do agente movido para uma extension opt-in, e extensions empacotadas para correção de bug e avaliação de ideia.

Depois da 1.0: --require-spec para analyze e converge, bundles que empacotam a configuração de um papel numa única instalação, e uma github extension assumindo o taskstoissues.

O que o /speckit-converge faz?+

Ele roda depois do implement e confere a codebase contra a spec, o plan, as tasks e a constitution. Cada lacuna é classificada como missing, partial, contradicts ou unrequested, e adicionada ao tasks.md como uma nova fase de convergência. Ele nunca reescreve os seus artefatos existentes.

Você repete implement e converge até ele reportar converged, momento em que o tasks.md fica inalterado. Ele pega o que o agente deixou de fora depois do fato. Não impede o agente de deixar de fora.

Existe um jeito mais leve de usar o Spec Kit para mudanças pequenas?+

Sim, três. O caminho curto oficial roda só specify, plan, tasks, implement e converge. O preset lean empacotado (specify preset add lean) substitui os templates do core por prompts autocontidos que produzem um arquivo focado por fase. E bugs têm a própria extension (specify extension add bug) com assess, fix e test, sem nenhum workflow de feature de SDD.

O Spec Kit é gratuito?+

Sim. O Spec Kit é publicado sob licença MIT. Não há plano pago, assinatura nem limite de uso. A CLI specify instala a partir do PyPI com uv, pipx ou pip.

Como eu instalo o Spec Kit?+

Instale o uv (https://docs.astral.sh/uv/), depois rode: uv tool install specify-cli. Para fixar uma versão, use uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z. Depois inicialize o projeto com specify init my-project --integration claude para Claude Code, ou --integration copilot para GitHub Copilot.

Para testar rapidamente sem instalar: uvx --from git+https://github.com/github/spec-kit.git specify init my-project. Para fazer upgrade depois: specify self upgrade.

O Spec Kit funciona com Claude Code, Cursor e Copilot?+

Sim. O Spec Kit lista 42 integrações, incluindo Claude Code, GitHub Copilot, Gemini CLI, Cursor, OpenAI Codex, Kiro CLI e Goose. No Claude Code ele instala skills em .claude/skills. O Copilot também usa o modo skills por padrão.

Rode specify integration list para ver todas as integrações da sua versão instalada. Um projeto pode carregar mais de uma.

Spec Kit ou Kiro: qual devo escolher?+

O Spec Kit se conecta ao agente que você já usa, com mais de 40 integrações e um ecossistema grande de extensions e presets. O Kiro é o ambiente próprio da AWS (IDE, CLI e web) com um workflow de spec mais leve, de três arquivos (requirements, design, tasks), embutido.

Se você quer flexibilidade de agente e um padrão aberto que qualquer pessoa do time possa usar com a ferramenta que preferir, use o Spec Kit. Se você quer o workflow de spec embutido no ambiente e topa trabalhar nas ferramentas do Kiro, leia o guia dedicado ao Kiro. A lógica do workflow é parecida. Os ambientes são bem diferentes.

O que o specify init de fato cria?+

Um diretório .specify com memory/ (para a constitution), scripts/ e templates/, além das skills ou comandos do seu agente, como .claude/skills no Claude Code. Ele não edita o CLAUDE.md nem o AGENTS.md a menos que você adicione a agent-context extension.

As pastas de feature são criadas depois pelo /speckit-specify, dentro de specs/ na raiz do repositório (specs/001-feature-name/). O arquivo .specify/feature.json aponta para a feature ativa, então o Spec Kit não depende mais da sua branch do git.

Quais são as principais fraquezas do Spec Kit?+

Três que vale conhecer. Primeiro, não há gate de aprovação: o --require-spec confere que o spec.md existe, não que alguém aprovou ele, então avançar entre fases ainda é disciplina sua. Segundo, o volume de artefatos padrão é alto (sete arquivos por feature) a menos que você escolha o preset lean. Terceiro, o converge pega o que o agente deixou passar depois do fato; não previne.

A análise de outubro de 2025 da Birgitta Böckeler no martinfowler.com continua sendo a melhor avaliação independente, e a própria documentação do Spec Kit sobre persistência de spec agora responde a ela.