Spec Kit do GitHub - desenvolvendo software de alta qualidade mais rápido

• Desenvolvimento orientado por especificação (Spec-Driven Development): uma abordagem que eleva a especificação (Spec), antes um recurso auxiliar no desenvolvimento tradicional, a uma especificação executável, com o objetivo de gerar diretamente implementações funcionais a partir dela
  • Muda a prática centrada em código para enfatizar o desenvolvimento orientado por intenção, definindo primeiro o o quê e o porquê e detalhando depois o como
  • A ideia central é criar entregáveis consistentes por meio da especificação e automatizar trabalhos repetitivos, permitindo que desenvolvedores foquem nos problemas do produto
• O Spec Kit é um conjunto de ferramentas que ajuda a converter essa especificação em artefatos executáveis, automatizando a implementação
• Após a instalação, use /specify para descrever o quê/porquê, /plan para declarar a stack/arquitetura e /tasks para gerar unidades de trabalho
• O objetivo é ajudar organizações a sair da escrita de código comum não diferenciado e focar em cenários de produto, em um framework experimental que busca elevar ao mesmo tempo qualidade e velocidade por meio da abordagem orientada por especificação

Filosofia central: Core philosophy

• Uma mentalidade de especificação em primeiro lugar, com desenvolvimento orientado por intenção, priorizando o o quê e detalhando o como depois
• Escrita de especificações ricas com guardrails e princípios organizacionais, passando por um processo de refinamento em múltiplas etapas, em vez de geração de código pontual
• Uma forma de uso que depende ativamente da capacidade de interpretação de modelos avançados de IA para converter especificações em resultados executáveis

Processo orientado por especificação com o Spec Kit

• O Spec Kit coloca a especificação no centro do processo de engenharia, guiando implementação, checklists e decomposição de trabalho, enquanto os desenvolvedores atuam principalmente como orientadores
  • O agente de codificação fica responsável pela maior parte da escrita
• O processo é composto por 4 etapas, cada uma com checkpoints claros, e a próxima etapa só começa quando o trabalho atual estiver totalmente validado
• Etapa Specify: ao fornecer uma descrição de alto nível, o agente de codificação gera uma especificação detalhada, focada na jornada do usuário, na experiência e nas métricas de sucesso, e não na stack técnica
  • Mapeia quem é o usuário, qual problema está sendo resolvido, como será a interação e quais resultados são importantes
  • Isso assume a forma de um artefato vivo, que evolui conforme o aprendizado sobre o usuário
• Etapa Plan: ao fornecer a stack desejada, a arquitetura e as restrições, o agente de codificação gera um plano técnico abrangente
  • Inclui padrões tecnológicos da empresa, integração com sistemas legados, conformidade regulatória e metas de desempenho
  • Também é possível solicitar várias versões de plano para comparação e, ao fornecer documentação interna, integrar diretamente padrões de arquitetura
• Etapa Tasks: com base na especificação e no plano, o agente de codificação decompõe o trabalho em blocos pequenos e revisáveis
  • Cada tarefa pode ser implementada e testada de forma independente, e foi desenhada para que a IA consiga validar e acompanhar o trabalho
  • Por exemplo, em vez de "construir autenticação", algo específico como "criar endpoint de cadastro de usuário com validação de formato de e-mail"
• Etapa Implement: o agente de codificação executa as tarefas uma a uma ou em paralelo, e os desenvolvedores revisam mudanças focadas
  • A especificação informa o que construir, o plano informa como construir e as tarefas informam no que trabalhar
• Em cada etapa, os desenvolvedores refletem e refinam, exercendo um papel de validação para verificar se a especificação captura a intenção, se o plano considera as restrições reais e se há omissões ou casos de borda

Como usar o Spec Kit em workflows agentic

• O Spec Kit funciona com agentes de codificação como GitHub Copilot, Claude Code, Gemini CLI e, por meio de uma série simples de comandos, orienta o agente e gera artefatos
  • Isso transforma prompts ambíguos em intenções claras para execução confiável
• Após inicializar o projeto, ao fornecer um prompt de alto nível com o comando /specify, o agente de codificação gera a especificação completa, focada no "o quê" e no "porquê" do projeto
• Com o comando /plan, ao fornecer uma direção técnica de alto nível, o agente de codificação gera um plano detalhado que respeita a arquitetura e as restrições
• Com o comando /tasks, decompõe a especificação e o plano em uma lista de tarefas executáveis, e o agente de codificação implementa os requisitos do projeto com base nisso

Fases de desenvolvimento: Development phases

• Etapa 0-to-1 (greenfield): dá suporte ao fluxo de geração de especificação → planejamento → criação de app pronto para produção, com base em requisitos de alto nível
• Etapa de exploração criativa: enfatiza um processo de experimentação com diferentes stacks/arquiteturas e padrões de UX por meio de implementações em paralelo
• Etapa de melhoria incremental (brownfield): um desenvolvimento evolutivo que repete adição de funcionalidades, modernização de legado e adaptação de processos

Três cenários em que essa abordagem funciona bem

• Greenfield (zero-to-one): ao iniciar um novo projeto, em vez de começar a programar de imediato, cria-se antes a especificação e o plano para garantir que a IA construa o que foi pretendido, oferecendo resultados personalizados em vez de soluções genéricas baseadas em padrões comuns
• Trabalho de funcionalidades em sistemas existentes (N-to-N+1): ao adicionar funcionalidades a uma base de código complexa, a especificação esclarece como a nova funcionalidade interage com o sistema existente, e o plano codifica as restrições arquiteturais para gerar código que pareça nativo
  • Isso torna o desenvolvimento contínuo mais rápido e seguro, embora possa exigir técnicas avançadas de engenharia de contexto
• Modernização de legado: ao reconstruir sistemas legados nos quais a intenção original se perdeu, o processo do Spec Kit captura a lógica de negócio essencial em uma especificação moderna e planeja uma arquitetura nova para que a IA reconstrua sem dívida técnica

Prerequisites

• Requer Linux/macOS ou WSL2 no Windows
• Escolha entre Claude Code, GitHub Copilot, Gemini CLI e Cursor como agente de IA

[edunga1]

Lembra o Copilot Workspace.

[cocofather]

Parece que isso vai se tornar a base da programação com IA baseada em linguagem natural.

[tested]

A vantagem do Spec Kit do GitHub é que ele também pode ser usado no GitHub Copilot.
Como foi feito pelo GitHub, isso é até esperado, mas muitas outras ferramentas eram baseadas no Claude.

[skageektp]

Lembra o Kiro IDE.

[kandk]

Interessante. Até faz sentido também.

[xguru]

O link com a apresentação detalhada de SDD no meio do texto é muito bom. Abaixo está um resumo que fiz com IA.

Desenvolvimento Guiado por Especificação (Specification-Driven Development, SDD)

The Power Inversion

• Inverte o fluxo em que o código era o centro e PRD/documentos de design eram auxiliares: a especificação é a fonte original, e o código é um artefato de expressão, implementado em uma linguagem/framework específico
  • Apresenta o diagnóstico de que o abismo permanente entre especificação e implementação era difícil de resolver apenas com reforço documental ou de processo
  • Se especificações executáveis e planos de implementação geram o código, o abismo desaparece e resta apenas a transformação
• A IA torna possível interpretar especificações complexas e elaborar planos de implementação, mas como geração sem estrutura causa confusão, o SDD assegura qualidade com estrutura precisa e guardrails
• Manutenção é o ato de evoluir a especificação; a intenção de desenvolvimento é expressa por linguagem natural, ativos de design e princípios centrais, e o código ocupa a posição de última milha
• Depuração prioriza corrigir a especificação e o plano de implementação antes de corrigir código errado, e refatoração é redefinida como reconstrução de clareza

The SDD Workflow in Practice

• A ideia é refinada em um PRD por meio de interação conversacional com a IA, e a IA detalha perguntas, edge cases e critérios de aceitação
  • Converte requisitos e design em uma atividade contínua, apoiando trabalho de especificação baseado em branches em nível de equipe, além de revisão e versionamento
• Um agente de pesquisa explora compatibilidade de bibliotecas, desempenho, segurança e restrições organizacionais (padrões de DB, autenticação, políticas de deploy) e reflete isso automaticamente na especificação
• A partir do PRD, gera-se um plano de implementação que mapeia requisitos e decisões técnicas de forma rastreável, enquanto a IA valida continuamente contradições, ambiguidades e omissões
• Quando a especificação e o plano estão suficientemente estáveis, inicia-se a geração de código, mas no começo com geração exploratória para validar viabilidade
  • Conceitos de domínio se transformam em modelos de dados, user stories em endpoints de API e cenários de aceitação em testes
• Na fase operacional, métricas e incidentes atualizam a especificação e influenciam a próxima regeneração; gargalos de desempenho são promovidos a requisitos não funcionais, e vulnerabilidades a restrições globais

Why SDD Matters Now

• Ponto crítico da capacidade da IA: agora é possível gerar com confiabilidade código funcional a partir de especificações em linguagem natural, automatizando a parte mecânica da tradução da implementação e ampliando exploração e criatividade
• Explosão de complexidade: com muitos serviços, frameworks e dependências, fica difícil manter a coerência entre intenção e implementação, tornando necessário o alinhamento guiado por especificação do SDD
• Aceleração da mudança: em cenários de pivô frequente, o SDD lida com mudanças por meio de regeneração sistemática, em vez de propagação manual entre documento, design e código
  • Como exemplo, possibilita simulações what-if e implementações paralelas, oferecendo agilidade na tomada de decisão

Core Principles

• Especificação = linguagem comum: a especificação é um artefato de primeira classe, o código é a expressão de uma stack específica, e manutenção é a evolução da especificação
• Especificações executáveis: especificações em nível preciso, completo e não ambíguo geram sistemas funcionais
• Refinamento contínuo: realiza validação constante de consistência, e não um gate único
• Contexto baseado em pesquisa: coleta continuamente desempenho, segurança e restrições organizacionais, injetando isso na especificação
• Feedback bidirecional: a realidade operacional vira entrada para atualização da especificação
• Branching para exploração: a partir da mesma especificação, permite gerar múltiplas implementações conforme objetivos de otimização como desempenho, manutenibilidade, UX e custo

Implementation Approaches

• Na prática de hoje, o essencial é combinar ferramentas existentes com manutenção de disciplina, e isso pode ser implementado com os seguintes elementos
  • Assistente de IA para refinamento iterativo de especificações
  • Agente de pesquisa para coleta de contexto técnico
  • Ferramenta de geração de código para conversão de especificação → implementação
  • Controle de versão adaptado a um workflow spec-first
  • Verificação baseada em análise de consistência por IA dos documentos de especificação
• O princípio comum é tratar a especificação como fonte única da verdade e o código como artefato exigido pela especificação

Streamlining SDD with Commands

• /specify: converte a descrição da funcionalidade em uma especificação estruturada e automatiza numeração automática, criação de branch e configuração de diretórios baseados em template
• /plan: análise da especificação → revisão de conformidade com a constituição → tradução técnica → documentação de modelo de dados, contrato de API e cenários de teste → geração de validação de quickstart
• /tasks: lê plan.md e os designs relacionados para produzir uma lista de tarefas executável, além de indicar tarefas paralelizáveis e agrupamento seguro para paralelização
• Exemplo: funcionalidade de chat
  • Mostra um fluxo em que cerca de 12 horas de trabalho documental na abordagem tradicional são reduzidas para cerca de 15 minutos de configuração com automação de especificação, plano e tarefas
  • Entre os artefatos gerados estão especificação, plano de implementação e justificativas, contrato de API e modelo de dados, cenários de quickstart e tasks.md, tudo com versionamento na branch

The Power of Structured Automation

• Evita itens faltando: templates cobrem até requisitos não funcionais e tratamento de erros
• Rastreabilidade de decisões: toda escolha técnica fica ligada a requisitos concretos
• Documentação viva: como a especificação gera o código, fica mais fácil manter sincronização
• Iteração rápida: quando requisitos mudam, é possível responder em minutos ou horas com regeneração do plano

Template-Driven Quality

• Evita a infiltração prematura de detalhes de implementação: ao focar em WHAT/WHY e excluir HOW, induz a manutenção do nível de abstração
• Força marcação de incerteza: o marcador [NEEDS CLARIFICATION] induz proibição de suposições e perguntas explícitas
• Auto-revisão baseada em checklist: implementa um gate de qualidade ao verificar completude, clareza e critérios de aceitação mensuráveis
• Gate constitucional: aplica checks na fase prévia (-1), como gate de simplicidade (≤3 projetos), gate antiabstração (uso direto do framework) e gate de integração primeiro (contratos e testes de contrato primeiro)
• Gestão hierárquica de detalhes: código e detalhes excessivos são separados em implementation-details/ para manter a legibilidade
• Prioridade para testes: assegura testabilidade com regra de criação de arquivos e testes primeiro na ordem contrato → integração → E2E → unitário
• Contenção de premissas e funcionalidades especulativas: reforça o controle de escopo com proibição de funcionalidades especulativas e explicitação de pré-condições por etapa

The Constitutional Foundation

• Adota uma constituição de desenvolvimento em memory/constitution.md com princípios imutáveis para manter todas as implementações consistentes, simples e de alta qualidade
  • Article I: Library-First — toda funcionalidade começa como uma biblioteca independente, garantindo modularidade
  • Article II: CLI Mandate — toda biblioteca expõe uma interface CLI com suporte a entrada/saída em texto e JSON, garantindo observabilidade e facilidade de teste
  • Article III: Test-First — proíbe implementação antes da aprovação do teste e da confirmação da falha (red), aplicando o princípio de definir comportamento primeiro
  • Articles VII & VIII: simplicidade e antiabstração — reduzem sobre-engenharia com mínimo de projetos e confiança direta no framework
  • Article IX: Testes com integração primeiro — prefere testes próximos do ambiente real e força testes de contrato antes da implementação
• Os gates da Phase -1 dos templates transformam a conformidade constitucional em checklist, e exceções registram justificativas explícitas em Complexity Tracking
• Por meio de um processo de emenda, a forma de aplicar os princípios pode evoluir, mas a filosofia central é preservada

The Transformation

• O objetivo não é substituir desenvolvedores, mas ampliar a capacidade humana e manter a coerência entre intenção e implementação por meio da automação da tradução mecânica
• O SDD coloca a especificação para gerar o código, praticando uma transformação contínua em que especificação, pesquisa e código coevoluem em um loop de feedback apertado

[amoplan]

Com qual IA você organizou isso?

[xguru]

Foi feito com o GPT-5. Eu uso um prompt bem longo que organizei para fins de resumo.

[heycalmdown]

Concordei bastante com o conceito, então fiz alguns testes no fim de semana com um projeto novo, mas não funcionou tão bem quanto eu esperava. Acho que ainda precisa de muitas melhorias. Por enquanto, o fluxo geral parece ser mais ou menos o seguinte, como já foi apresentado várias vezes:
redigir a constituição → redigir a especificação → redigir as tarefas → implementar

O problema é que

• o arquivo constitution.md é o guia central sobre "como desenvolver", mas não contém "o que este app será no final"
• spec.md é um documento que descreve uma funcionalidade
• não existe um documento mestre sobre "o que é este app"
• lendo as discussões no GitHub, parece que a ideia é que a chain of specs acabe se tornando a source of truth. Fiquei meio desconfiado, mas deu para entender mais ou menos.
• os comandos /specify e /tasaks geram muitos documentos como resultado (que era o que eu queria), e por isso o contexto é consumido rapidamente (estou usando Claude Code)
• quando a implementação de fato começa, você acaba se afastando um pouco do Spec Kit e termina a implementação conversando com o Claude Code como de costume
• quando todo o contexto é consumido e acontece a compactação, ou quando você inicia uma nova sessão, ele esquece que os documentos gerados pelo Spec Kit existem
• ao executar as tarefas definidas em tasks.md, às vezes você sobrescreve algo que tinha feito corretamente antes, e no processo de corrigir bugs acaba criando novas funcionalidades, então vai se afastando cada vez mais do tasks.md. Não vejo muito sentido em manter tasks.md permanentemente.

Por enquanto, a conclusão a que cheguei é a seguinte:

• mesmo que o resultado saia diferente do que foi pensado no início, é melhor concluir a especificação primeiro e depois criar novas especificações para ir ajustando aos poucos
• a especificação inicial inevitavelmente vai ficar grande, então talvez seja melhor não explicar as funcionalidades do app e criar apenas o boilerplate
• ao fazer algo em nível de PoC, é melhor não usar o Spec Kit