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: 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.

Sem especificações:
• Cada nova sessão reinventa a  arquitetura do zero.
• "Concluído" significa simplesmente  "o modelo disse que está pronto".
• Desvios técnicos (drift) acumulam-se  silenciosamente na base de código.

Com especificações:
• Os agentes implementam o código  estritamente contra o documento.
• Os revisores auditam a  correspondência direta: especificação ↔ código.
• Demonstrações e repasses apoiam-se  na spec, nunca em improvisações.

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 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
• Análise (Analysis):  skills como bmad-brainstorming (geração de ideias), bmad-forge-idea (submete a ideia a perguntas socráticas, uma de cada vez, até consolidá-la ou descartá-la) e bmad-product-brief
  para validação inicial do problema.

• Planejamento (Planning): bmad-prd (requisitos do produto) e bmad-ux (experiência do usuário) para delimitar o escopo.

• Solução (Solutioning): bmad-architecture cria a espinha dorsal arquitetural em ARCHITECTURE-SPINE.md,
que é a fonte da verdade; a partir dela, bmad-spec deriva o SPEC.md de cada capacidade. Em seguida vêm a
criação de épicos e histórias.

• Construção (Build):  a cadeia bmad-sprint-planning → bmad-build → bmad-code-review, executada por
unidade de trabalho.

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:

Skill Finalidade
openspec-explore Investiga o problema e a base de código, sem escrever código.
openspec-propose Cria uma nova mudança e rascunha todos os artefatos de planejamento a partir de uma ideia.
openspec-apply-change Implementa as tarefas técnicas da mudança contra a especificação proposta.
openspec-verify-change Confere se a implementação corresponde às specs antes do arquivamento (perfil expandido).
openspec-sync-specs Mescla os delta specs de uma mudança nas specs principais, sem arquivá-la.
openspec-archive-change Mescla os deltas aprovados na spec viva e move a mudança para o arquivo.

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): 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

Seu cenário Abordagem recomendada
Novo projeto ou recurso (greenfield), necessitando ideação, narrativa e skills agênticas BMAD
Produto existente, mudanças incrementais de capacidade e diffs avaliáveis em PRs OpenSpec
Novas features complexas que demandam refinamentos contínuos após a v1 Híbrido (bmad-forge-idea para ideação + um único dono canônico da spec)
Spikes individuais ou protótipos descartáveis Spec enxuta de 10 linhas em  Markdown — evite excesso de processo

As duas ferramentas resolvem camadas complementares da engenharia:

Critério BMAD OpenSpec
Unidade de trabalho Da ideia até a feature entregue em produção Proposta de alteração na especificação
Ponto forte Skills agênticas, personas e refinamento da  ideia (forge) Fluxo leve de propor, aplicar e arquivar, com rastreabilidade por diffs
no Git
Artefatos gerados _bmad-output/ (forge, planning-artifacts, specs) openspec/changes/ e openspec/specs/
Momento ideal Projetos greenfield e novos módulos completos Ajustes e incrementos em capacidades
vigentes

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:

Camada Artefato gerado O que impõe / garante
Spec SPEC.md O que deve existir; "concluído" = critérios de  aceite atendidos
Arquitetura ARCHITECTURE-SPINE.md Como o servidor MCP e o sistema são  construídos
MCP Servidor MCP do Jira Ferramentas invocáveis com respostas tipadas e estruturadas
Skill release-test-plan/SKILL.md Sequência rígida de etapas e pontos de  aprovação obrigatórios
Verificação test-plan.md e relatório de  validação Validação humana confirmando: especificação ↔  arquivos em disco

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

Antipadrão Por que falha
Spec criada depois do código Gera uma documentação fictícia retroativa.
Dois responsáveis concorrentes pela  spec Divergência (drift) técnica garantida entre  implementações.
Usar o chat da IA como especificação Informação não pesquisável e impossível de auditar.
Ignorar critérios de aceite O conceito de "pronto" torna-se puramente  subjetivo.
Não vincular runbooks à spec A passagem de conhecimento deteriora-se  rapidamente.

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.

E estamos conversados..

"Não estejais inquietos por coisa alguma; antes as  vossas petições sejam em tudo conhecidas diante de Deus pela oração e súplica,  com ação de graças."
Filipenses 4:6

Referências:

José  Carlos Macoratti