Extensões do Spec Kit: presets, bundles e workflows
As extensões do Spec Kit são o conjunto de recursos que permite adaptar o fluxo de Spec Driven Development às regras de uma empresa sem criar um fork da ferramenta. Neste artigo, você vai entender como presets, extensions, bundles, workflows e catálogos se combinam para levar o SDD de um projeto isolado para dezenas de times.
O que são as extensões do Spec Kit
O GitHub Spec Kit é um toolkit open source que dá aos agentes de código processos estruturados, templates reutilizáveis e resultados documentados. Na prática, ele transforma uma ideia em uma cadeia rastreável de artefatos: constituição, especificação, plano, tarefas, código e testes.
Se você ainda não conhece a base do método, vale ler antes o nosso guia sobre spec driven development e como aplicar a prática. Aqui, o foco é o passo seguinte, ou seja, o que acontece quando esse fluxo precisa servir a uma organização inteira.
O artigo da Microsoft que inspirou este texto descreve as extensões do Spec Kit como quatro camadas complementares. Os presets mudam um comportamento que já existe, enquanto as extensions adicionam capacidades novas.
Além disso, os bundles empacotam combinações prontas e os workflows automatizam processos repetíveis. Por fim, os catálogos controlam de onde cada componente pode ser instalado.
Neste texto, usamos o termo extensões do Spec Kit para o ecossistema inteiro de extensibilidade. Quando o assunto for o componente específico chamado extension, ele aparece com esse nome em inglês, como na documentação oficial.
Essa distinção ajuda a ler o restante do texto sem confusão. Afinal, as extensões do Spec Kit incluem a extension, mas não se limitam a ela.
Por que o fork não escala nas empresas
Um fluxo compartilhado é só o começo. Cada time trabalha em um domínio diferente, usa uma stack diferente e responde a controles próprios de segurança, compliance e qualidade.
A saída mais intuitiva costuma ser copiar o repositório e editar os templates. No entanto, cada fork vira uma versão paralela que alguém precisa manter, e as atualizações do core passam a exigir merges manuais.
Com o tempo, a empresa acumula dez variações do mesmo processo e nenhuma delas recebe as correções da versão oficial. Por isso, o modelo recomendado é outro: um núcleo estável com pontos de extensão explícitos.
As extensões do Spec Kit seguem exatamente essa ideia. O core permanece intocado, e toda customização vive em componentes modulares, versionados e removíveis.
Na prática, isso significa que uma atualização do toolkit não apaga o trabalho do time de plataforma. Por isso, as extensões do Spec Kit funcionam como um contrato estável entre quem mantém o core e quem adapta o processo.
Presets: mudar o comportamento sem fork
Os presets são sobrescritas empilháveis e ordenadas por prioridade para templates, comandos e terminologia. Eles alteram os artefatos que o SDD gera, como specs, planos, tarefas, checklists e constituições, sem tocar no toolkit.
Por isso, presets combinam muito bem com padrões organizacionais. Um preset de segurança pode reforçar os prompts de modelagem de ameaças, por exemplo.
Da mesma forma, um preset de domínio pode trazer a terminologia de um setor e critérios de aceite obrigatórios. Já um preset de tecnologia pode ajustar a orientação de planejamento para uma plataforma como o .NET.
Entre todas as extensões do Spec Kit, o preset costuma ser o ponto de partida mais simples. Ele exige pouco código, porque quase todo o trabalho está em escrever bons templates em Markdown.
A instalação acontece pela CLI specify, sempre dentro de um projeto já inicializado:
# Busca presets nos catálogos ativos
specify preset search
# Instala com prioridade explícita (número menor vence)
specify preset add enterprise-baseline --priority 10
specify preset add healthcare-compliance --priority 5
# Mostra qual arquivo vence para um template
specify preset resolve spec-template
A prioridade padrão é 10, e o número menor sempre tem precedência. Assim, no exemplo acima, o preset de compliance vence o baseline para qualquer arquivo que os dois forneçam.
Quando o Spec Kit precisa de um template, ele percorre uma pilha de resolução. Primeiro olha as sobrescritas locais do projeto, depois os presets, em seguida as extensions e, por fim, os templates do core.
Composição de templates com estratégias
Por padrão, um preset substitui o arquivo inteiro. Contudo, o manifesto preset.yml aceita estratégias de composição que acrescentam conteúdo em vez de trocar tudo.
schema_version: "1.0"
preset:
id: "org-security"
name: "Org Security Baseline"
version: "1.0.0"
description: "Adds threat modeling and security criteria to specs"
author: "Platform Team"
requires:
speckit_version: ">=0.9.0"
provides:
templates:
# Acrescenta uma seção de segurança ao final do template de spec
- type: "template"
name: "spec-template"
file: "templates/security-addendum.md"
strategy: "append"
# Envolve o comando de plano com verificações extras
- type: "command"
name: "speckit.plan"
file: "commands/plan-wrapper.md"
strategy: "wrap"
A estratégia append coloca o conteúdo depois do template de prioridade menor, enquanto prepend coloca antes. Já wrap usa o marcador {CORE_TEMPLATE} para envolver o conteúdo original.
Esse recurso é valioso porque reduz o atrito na adoção das extensões do Spec Kit. O time não precisa copiar o template original inteiro só para acrescentar uma seção.
Com isso, vários presets se encadeiam. Um preset de segurança com prepend e outro de compliance com append geram cabeçalho, conteúdo do core e rodapé, nessa ordem.
Extensões do Spec Kit para novas capacidades
Enquanto o preset muda algo que já existe, a extension adiciona comportamento além do ciclo nativo. Ela pode trazer comandos de domínio, integrações, quality gates, templates, scripts e hooks.
Alguns exemplos citados pela Microsoft são um comando de revisão de segurança, um gate de acessibilidade e uma integração com o sistema interno de gestão de trabalho. O próprio Spec Kit usa esse modelo nas extensions oficiais bug e assess, que você instala sob demanda.
# Instala a extension oficial de correção de bugs
specify extension add bug
# Lista o que está instalado e habilitado
specify extension list
# Desabilita sem remover
specify extension disable bug
Cada extension declara seus comandos em um manifesto extension.yml. Os nomes seguem o padrão speckit.{extension-id}.{command-name}, o que evita colisões entre componentes.
schema_version: "1.0"
extension:
id: "security-review"
name: "Security Review"
version: "1.0.0"
description: "Adds a security review command to the SDD lifecycle"
author: "AppSec Team"
requires:
speckit_version: ">=0.9.0"
provides:
commands:
- name: "speckit.security-review.run"
file: "commands/run.md"
description: "Reviews plan and tasks against security rules"
Dessa forma, cada preocupação fica modular, versionada e mantida de forma independente. Se o time de segurança mudar a regra, ele publica uma nova versão da extension sem mexer no fluxo de ninguém.
Hooks que conectam a extension ao fluxo
O recurso mais poderoso das extensions são os hooks. Eles disparam comandos antes ou depois das etapas do SDD, como after_tasks ou before_implement.
hooks:
# Pergunta se o usuário quer rodar a revisão após gerar as tarefas
after_tasks:
command: "speckit.security-review.run"
optional: true
prompt: "Run the security review now?"
description: "Security review after task generation"
Quando optional é true, o agente apresenta o prompt e o usuário pode pular a etapa. Por outro lado, com false o hook entra como execução automática.
Em outras palavras, os hooks transformam uma capacidade isolada em uma etapa natural do ciclo. O desenvolvedor continua usando os mesmos comandos, mas o processo passa a incluir o controle que a empresa exige.
Bundles: um setup completo em um comando
Um bundle compõe extensions, presets, workflows e steps em uma única unidade versionada e instalável. Ele não adiciona comportamento novo, pois funciona apenas como camada de distribuição sobre os componentes que já existem.
Para o time de plataforma, isso reduz a variação de setup entre projetos. Para o time de produto, uma longa lista de instalação vira um único ponto de entrada governado.
O manifesto bundle.yml fixa as versões de cada componente:
schema_version: "1.0"
bundle:
id: "dotnet-developer"
name: ".NET Developer"
version: "1.0.0"
role: "developer"
description: "Org baseline, quality gates and bug workflow for .NET teams"
author: "Platform Team"
requires:
speckit_version: ">=0.9.0"
provides:
extensions:
- id: "security-review"
version: "1.0.0"
presets:
- id: "org-security"
version: "1.0.0"
priority: 5
strategy: "append"
workflows:
- id: "bugfix"
version: "1.0.0"
Antes de instalar, o comando info mostra o conjunto completo de componentes que o bundle vai aplicar. Em seguida, install executa o plano, e o rastreamento de proveniência permite atualizar ou remover tudo depois.
specify bundle info dotnet-developer
specify bundle install dotnet-developer
# Atualiza para as novas versões fixadas no manifesto
specify bundle update dotnet-developer
Entre as extensões do Spec Kit, o bundle é o que mais conversa com a área de plataforma. Ele permite oferecer um kit por papel, como desenvolvedor, analista de negócio ou pesquisador de segurança.
Vale um cuidado: a remoção de um bundle retira apenas os componentes que ele trouxe. Se outro bundle ainda depende de um componente, ele permanece no projeto.
Workflows para automatizar o SDD
Os workflows transformam capacidades isoladas em processos repetíveis. Eles encadeiam comandos, prompts, scripts de shell e checkpoints humanos, com suporte a condições, loops e fan-out.
Dentro das extensões do Spec Kit, o workflow é a camada que orquestra as demais. Ele chama comandos do core, comandos de extensions e scripts próprios em uma sequência previsível.
Isso faz muita diferença em processos nos quais a evidência importa tanto quanto a execução. Correção de bugs, prontidão para release e revisão de arquitetura são bons exemplos.
O Spec Kit já traz um workflow chamado speckit, que roda especificação, plano, tarefas e implementação com gates de revisão entre as etapas. Você pode estendê-lo com um overlay, sem editar o arquivo original:
id: "add-dotnet-tests"
extends: "speckit"
priority: 10
edits:
# Roda os testes logo depois da implementação
- insert_after: implement
step:
id: run-tests
type: shell
run: "dotnet test"
specify workflow overlay add add-dotnet-tests.yml --priority 10
specify workflow run speckit -i spec="Build an order tracking API"
# Retoma a execução depois de aprovar um gate
specify workflow resume <run_id>
Quando o workflow chega a um step do tipo gate, ele pausa e espera a decisão humana. O estado fica salvo em .specify/workflows/runs/, então a execução continua do ponto exato em que parou.
Além disso, o comando specify workflow resolve mostra a composição final, com a origem de cada step. Assim, fica fácil auditar o que cada overlay acrescentou ao processo.
O objetivo não é remover o julgamento humano. Na verdade, a ideia é deixar explícitos a sequência, os artefatos e os checkpoints esperados.
Porém, existe um alerta importante da documentação. Um step shell roda com os seus privilégios e não tem sandbox, por isso nunca interpole saída de agente ou entrada livre dentro de um campo run.
Catálogos das extensões do Spec Kit e segurança
A extensibilidade só gera valor quando os times conseguem descobrir componentes e confiar no que instalam. Os catálogos cumprem esse papel, mas a empresa precisa separar fontes de instalação governadas de descoberta aberta.
O modelo prático sugerido pela Microsoft usa duas camadas. O catálogo da organização fica sob controle interno, passa por revisão e recebe a maior prioridade de resolução.
Já o catálogo da comunidade serve para exploração e inspiração, mas funciona apenas como descoberta. Uma listagem confirma formato e metadados, não uma auditoria de segurança do código.
Essa separação forma uma fronteira de segurança. Os times navegam livremente, enquanto as instalações continuam ancoradas em fontes verificadas.
Para registrar o catálogo da empresa, basta um arquivo .specify/extension-catalogs.yml:
catalogs:
- name: "acme-catalog"
url: "https://specs.acme.dev/catalog.json"
priority: 5
install_allowed: true
description: "Approved extensions for Acme teams"
A propriedade install_allowed define se o catálogo aceita instalação ou serve só para busca. A documentação é clara: nunca marque um catálogo público e não revisado como instalável.
Se você encontrar algo útil na comunidade, existem dois caminhos seguros. Você pode revisar o pacote e instalar com --from, ou então incluir o componente no catálogo da organização depois da análise.
Além disso, presets, workflows e bundles possuem catálogos próprios com o mesmo modelo de confiança. Antes de instalar algo em um projeto desconhecido, rode specify extension catalog list e confira cada fonte marcada como instalável.
Constituição em camadas
O mesmo princípio de camadas também vale para a constituição do projeto. Em vez de obrigar cada time a escrever seus princípios do zero, a empresa define regras padrão que entram em todo projeto.
Dessa forma, as regras corporativas aparecem automaticamente sempre que um time redige uma nova constituição. Ao mesmo tempo, o time mantém liberdade para acrescentar ou ajustar diretrizes específicas.
A constituição final se compõe em três níveis:
- Baseline da organização, com expectativas de engenharia inegociáveis.
- Camada de domínio e tecnologia, com regras de um negócio, plataforma ou arquitetura.
- Customização do time, com exceções e adições bem delimitadas.
Na prática, o template da constituição segue a mesma pilha de presets. Cada execução de /speckit-constitution resolve o template composto e aplica os valores do projeto por cima.
Essa abordagem mostra como as extensões do Spec Kit chegam até o documento mais estratégico do projeto. A governança deixa de depender da memória de cada líder técnico.
Com isso, os agentes de IA recebem guardrails mais claros e duráveis. Isso funciona melhor do que repetir as mesmas instruções em cada prompt.
Exemplo prático das extensões do Spec Kit: consumo de tokens
A engenharia com IA traz uma preocupação operacional nova: entender quanto cada execução consome de tokens e quanto isso custa. O artigo da Microsoft usa esse cenário como exemplo concreto das extensões do Spec Kit.
Uma extension pode coletar o consumo depois de cada execução, mostrar tendências e sugerir otimizações quando um limite for ultrapassado. Como a capacidade é modular, o time adota o recurso sem alterar o ciclo do SDD.
Um esboço desse cenário ficaria assim:
extension:
id: "token-usage"
name: "Token Usage"
version: "1.0.0"
description: "Collects token usage and suggests optimizations"
provides:
commands:
- name: "speckit.token-usage.report"
file: "commands/report.md"
description: "Summarizes token usage and flags thresholds"
hooks:
# Gera o relatório automaticamente após a implementação
after_implement:
command: "speckit.token-usage.report"
optional: false
description: "Token usage report after implementation"
O mesmo padrão atende outras necessidades transversais. Checagens de acessibilidade, revisões de desenvolvimento seguro, governança de dependências e qualidade de documentação seguem a mesma lógica.
O ponto central é que as extensões do Spec Kit permitem tratar custo e qualidade como parte do processo. Assim, o time enxerga o impacto de cada mudança antes que ele apareça na fatura.
Como adotar as extensões do Spec Kit com responsabilidade
A recomendação geral é começar pequeno e priorizar a confiança. Seguir uma ordem clara evita que a customização vire um problema maior do que o fork que ela substitui.
- Defina a baseline, ou seja, a constituição da organização e os controles de todo projeto.
- Prefira presets para política e terminologia, porque eles adaptam o que já existe.
- Use extensions para capacidades novas, sempre focadas, documentadas e versionadas.
- Monte um catálogo da organização e revise dono, origem, permissões, prompts e scripts.
- Empacote combinações aprovadas em bundles, para que o caminho correto seja também o mais fácil.
- Automatize só o que você entende, criando workflows depois que o processo estiver claro.
A regra de ouro é manter a customização modular e o core intocado. Assim, você preserva a capacidade de atualizar, deixa a proveniência visível e impede que melhorias locais virem forks eternos.
Em projetos .NET, por exemplo, um bom primeiro passo é um preset que exija testes com xUnit no template de tarefas. Depois, uma extension pode verificar a cobertura, e um bundle junta tudo para os novos repositórios.
Por fim, meça o resultado antes de ampliar o uso das extensões do Spec Kit. Acompanhe o tempo de setup, a taxa de retrabalho e a quantidade de exceções que cada time precisa pedir.
Conclusão sobre as extensões do Spec Kit
O SDD começa com uma ideia simples: deixar a intenção explícita antes de pedir que a IA execute. As extensões do Spec Kit levam essa ideia para a realidade de uma empresa.
Com elas, a organização codifica seus padrões uma única vez e aplica tudo de forma consistente. Além disso, ela adiciona capacidades de domínio e automatiza fluxos que produzem evidência.
Para quem trabalha com .NET, o caminho natural é começar com um preset de baseline e evoluir aos poucos. Dessa forma, as extensões do Spec Kit crescem junto com a maturidade do time.
O resultado vai além de um toolkit customizável. Trata-se de um modelo operacional para engenharia com IA, que combina core estável, blocos governados e flexibilidade suficiente para cada time.
FAQ
Qual a diferença entre preset e extension no Spec Kit?
O preset altera templates e comandos que já existem, enquanto a extension adiciona comandos, integrações e hooks novos. Em resumo, um muda como o processo funciona e o outro amplia o que ele faz.
Preciso criar um fork do Spec Kit para padronizar minha empresa?
Não. Presets, extensions, bundles e catálogos existem justamente para customizar sem alterar o core e sem perder as atualizações.
Posso instalar qualquer extension do catálogo da comunidade?
O catálogo da comunidade serve apenas para descoberta. Para instalar, revise o pacote e use --from ou adicione o componente ao catálogo aprovado da sua organização.
Como saber qual preset está vencendo para um template?
Use o comando specify preset resolve com o nome do template. Ele percorre a pilha de resolução e mostra qual arquivo será usado.
Workflows substituem a revisão humana?
Não. Os steps do tipo gate pausam a execução e esperam aprovação, então o workflow apenas deixa os checkpoints explícitos.