Spec-Driven Development: BMAD, OpenSpec e a Stack Agêntica

Este  artigo aborda a transição do “vibe coding” para a engenharia verificável  através do Desenvolvimento Orientado por Especificação (Spec-Driven  Development – SDD). (Traduzido com ajuda de IA, corrigido e ajustado por  Macoratti)

Da programação intuitiva (“vibe coding”) à construção verificável

O “vibe coding” é quando você interage com um agente, aceita qualquer código  gerado e o envia para produção simplesmente porque “parece bom“. Isso funciona  para protótipos e spikes individuais — até o instante em que você precisa  defender suas decisões técnicas em uma revisão de código, passar a demanda para  outro engenheiro ou executar o mesmo workflow duas vezes sem desvios de  consistência.

Este artigo pressupõe familiaridade com alguns conceitos básicos do desenvolvimento com agentes de IA:
• Letramento em IA: como a IA  opera, padrões fundamentais, agentes e conceitos.
• MCP (Model Context Protocol):  ferramentas (tools), recursos (resources) e prompts.
• Skills: instruções que fazem o agente seguir rigorosamente o seu manual de execução.
• Rules (regras): limites estritos dentro dos quais o agente opera.

A partir daí, vamos ver como transformar ideias conceituais em software robusto e  justificável diante da sua equipe técnica. É exatamente isso que propõe o Spec-Driven Development (SDD) — Desenvolvimento Orientado por  Especificação.

Neste artigo, vamos explorar:
• O que é o Desenvolvimento Orientado por  Especificação (SDD)
• O que uma boa especificação deve conter
• Por que o SDD é vital na era dos agentes  autônomos
• O loop de verificação contínua
• Ferramentas de código aberto↳Open source71 conteúdosComo o Open Source Está Liberando o Poder da Automação para TodosDev (Back & Front) · out 2025Código aberto: programadores criam software da NASA sem saberDev (Back & Front) · abr 2021N8N: O que é a ferramenta open source que está revolucionando a automação em TI?Dev (Back & Front) · dez 2025Ver tudo em Dev (Back & Front) →: Método BMAD e OpenSpec
• Como escolher entre BMAD, OpenSpec ou um  modelo híbrido
• Exemplo prático de fluxo ponta a ponta e  antipadrões a evitar

Vamos começar.

O que é Spec-Driven Development (SDD)?

O Spec-Driven Development significa que a especificação técnica é a fonte  única da verdade — não o histórico do chat com a IA, nem a memória do  desenvolvedor sênior, tampouco uma página desatualizada em uma wiki.

Uma boa especificação contém:
• Declaração do problema (problem statement):  quem é impactado, qual o tamanho da dor e por que resolver agora.
• Capacidades (capabilities):  o que o sistema obrigatoriamente deve fazer (itens testáveis e objetivos).
• Restrições (constraints):  tecnológicas, arquiteturais, de segurança, de desempenho e o que está fora do escopo.
• Critérios de aceite (acceptance criteria):  como saber de forma indiscutível que o trabalho está pronto.
• Rastreabilidade (traceability):  vínculos diretos com ADRs (Architecture Decision Records), tickets e manuais de  operação (runbooks).

Por que o SDD é crucial na era dos agentes de  IA?

Modelos de linguagem são extremamente rápidos — inclusive para cometer  erros com plena confiança.

O SDD é a disciplina necessária para escalar o desenvolvimento assistido por IA  além de iniciativas pontuais e isoladas.

O loop de verificação (não pule esta etapa)

O desenvolvimento orientado por especificação não se resume a “escrever a spec  uma vez e esquecê-la”. O ciclo de execução é composto por etapas contínuas:

• Implementação contra a spec:  agente + MCP + skills produzem os artefatos de código.
• Verificação: Revisão  humana ou scripts automatizados validam a conformidade entre a especificação e a  entrega gerada (arquivos persistidos em disco, chaves de tickets e cobertura dos  critérios de aceite).
• Ocorreu desvio (drift)?  Atualize primeiro a especificação, depois altere o código — nunca invente uma  narrativa depois de enviar o código.
• Aprovado (pass)? Envie  para produção, consolide a especificação atualizada como a nova referência do sistema e faça commit da spec e das skills associadas no Git.

O “Pronto” significa que os critérios de aceite foram atendidos em um artefato  verificável — e não que “o modelo disse que parece bom”.

Ferramentas de código aberto para SDD

1. Método BMAD (Breakthrough Method of Agile↳Agile11 conteúdosO antiágil: quais as práticas que te afastam do AgileGestão Dev & TI · ago 2020Adoção de metodologias ágeis em TI pode fazer a diferença em um mundo de rápidas mudançasGestão Dev & TI · mai 2023Webinar HostGator mostra como usar Metodologias Ágeis para tirar um projeto do papelGestão Dev & TI · mai 2019Ver tudo em Gestão Dev & TI → AI-Driven Development)

O BMAD é um ecossistema estruturado de skills e agentes para todo o fluxo de  entrega de software. Os nomes abaixo referem-se ao BMAD v6.9 ou superior; em instalações anteriores você encontrará nomes antigos como bmad-create-prd, bmad-create-architecture e bmad-quick-dev, que hoje funcionam apenas como atalhos de compatibilidade para os novo

Nota: BMAD significa “Método Revolucionário de Desenvolvimento Ágil Orientado por IA”. É um framework de código aberto, mantido no GitHub em https://github.com/bmad-code-org/bmad-method

A organização típica de saída no BMAD segue esta estrutura:

_bmad-output/
├── forge/<ideia>/              # ideia consolidada, decisões fechadas
├── planning-artifacts/         # PRD, UX e espinha da arquitetura (ARCHITECTURE-SPINE.md)
├── specs/spec-capacidade/      # SPEC.md da capacidade, derivado da espinha
└── implementation-artifacts/   # histórias e status da sprint

Princípio fundamental do BMAD: seres humanos aprovam nos pontos de controle (gates); os agentes escrevem o código.

2. OpenSpec

O OpenSpec é um fluxo de especificações baseado em arquivos — excelente para times que desejam versionar especificações dentro do repositório sem a sobrecarga de burocracias pesadas. Ele combina duas partes: a CLI openspec, executada no terminal (openspec init, openspec list, openspec archive), e os slash commands /opsx:*, digitados no chat do assistente de IA.

Estrutura típica de pastas no OpenSpec:

openspec/
├── config.yaml                     # configuração do projeto
├── specs/<capacidade>/spec.md      # verdade viva da capacidade no sistema
└── changes/
    ├── <nome-da-mudanca>/          # delta de alteração proposto
    ┃   ├── proposal.md
    ┃   ├── design.md
    ┃   ├── tasks.md
    ┃   └── specs/...
    └── archive/YYYY-MM-DD-<nome>/  # mudanças concluídas e arquivadas

O OpenSpec se destaca quando você precisa de evolução de specs  comparável via Git diff — cada modificação vive em uma pasta isolada,  passível de ser auditada em um Pull Request.

Skills do OpenSpec:

O ciclo de slash commands (digitados no chat do agente, não no terminal):

• /opsx:explore: mapeia o problema e examina a base de código (opcional).
• /opsx:propose: cria a mudança e rascunha proposal.md, specs/, design.md e tasks.md.
• /opsx:apply: executa a implementação técnica a partir das tarefas da spec.
• /opsx:sync: mescla os deltas nas specs principais; normalmente é oferecido automaticamente pelo archive.
• /opsx:archive: arquiva a mudança concluída após aprovação.

Esses cinco comandos formam o perfil padrão (core). Comandos como /opsx:verify, /opsx:new, /opsx:continue e /opsx:ff pertencem ao perfil expandido e precisam ser habilitados com openspec config profile seguido de openspec update. Dependendo da ferramenta, a sintaxe muda: o Claude Code usa /opsx:propose, enquanto Cursor, Windsurf e GitHub Copilot usam /opsx-propose.

Outros padrões relevantes no ecossistema:

• GitHub Spec Kit: toolkit de código aberto do GitHub com templates e comandos de especificação integrados ao repositório.
• Kiro (AWS↳AWS20 conteúdosE-mails de verificação com AWS SES + Lambda (Node.js) e Terraform: do zero ao envioDevSecOps · out 2025Codex na AWS: chegada do agente da OpenAI à nuvem da AmazonDevSecOps · abr 2026Salesforce e AWS ampliam colaboração em IA, CRM e marketplaceDevSecOps · nov 2023Ver tudo em DevSecOps →): IDE comercial com fluxos de trabalho orientados a especificações integrados nativamente.
• Pastas de ADR: registro histórico formal de decisões arquiteturais acompanhando as specs.

Como Escolher: BMAD vs. OpenSpec vs.  Abordagem Híbrida

As duas ferramentas resolvem camadas complementares da engenharia:

Exemplo de workflow: construindo uma  integração Jira via MCP

• 1. Consolide a ideia (bmad-forge-idea): feche as decisões cedo — os três pilares do MCP (ferramentas, recursos e prompts), permissão apenas de leitura e criação na v1  (sem delete) e envelopes estruturados para tratamento de erros em cada tool.

• 2. Defina a arquitetura (bmad-architecture): o ARCHITECTURE-SPINE.md estabelece o canal de transporte (stdio), a autenticação via tokens em variáveis de ambiente e a forma de carregamento do servidor no ambiente.

• 3. Derive a especificação (bmad-spec): a partir da espinha, o SPEC.md cataloga cada tool, URI de recurso, nomes de prompts, critérios de aceite e códigos formais de erro.

• 4. Implemente com rastreabilidade (bmad-build): as histórias vinculam-se aos IDs da especificação, e bmad-code-review revisa cada entrega. Estar pronto significa ter os critérios de aceite aprovados.

• 5. Crie uma skill para a equipe:  a skill release-test-plan, combinada com o runbook, forma um fluxo  repetível e auditável atrelado à spec.

• 6. Use o OpenSpec para mudanças contínuas:  ao acrescentar a capacidade jira_search_issues, execute o ciclo /opsx:propose add-jira-search-tool → /opsx:apply → verificação contra os critérios de aceite → /opsx:archive. A spec viva permanece sincronizada em openspec/specs/, e o  BMAD preserva o histórico de arquitetura.

Nota: O Jira é a ferramenta da Atlassian para rastreamento de tarefas e gestão de projetos. No exemplo, a ideia é construir um servidor MCP que expõe operações do Jira para o agente de IA.

A stack completa: Spec-Driven + MCP + Skills

O verdadeiro diferencial operacional surge da união desses pilares:
• A spec define formalmente as  prioridades e a estrutura de saída esperada.
• O MCP viabiliza a integração  transparente com sistemas externos (Jira, bancos de dados, arquivos).
• A skill impõe a ordem rígida de  passos e as regras de parada para o agente.
• O desenvolvedor valida se os  arquivos em disco e o comportamento do sistema atendem à  especificação.

Aplicado ao exemplo do Jira:

Esta é a linha que separa “conversei  com um assistente de IA” de “posso reproduzir esta mesma demonstração  técnica com precisão para minha equipe na próxima sprint”.

Antipadrões que devem ser evitados

Conclusão

A adoção do Spec-Driven Development transforma agentes autônomos de geradores  casuais de código em participantes de um processo de engenharia estruturado. Estabeleça  especificações claras, apoie-se em ferramentas modernas como BMAD e OpenSpec,  feche o loop com validações rigorosas e garanta previsibilidade e escalabilidade  para as suas soluções corporativas.