Spec-Driven Development

O que é Spec-Driven Development

Spec-Driven Development (SDD) é uma abordagem de desenvolvimento de software onde especificações detalhadas — documentos de requisitos, arquitetura, design de UX e épicos/histórias — são produzidas de forma estruturada antes de qualquer linha de código ser escrita. Diferente de metodologias tradicionais, no SDD essas especificações são criadas em colaboração com agentes de IA especializados, garantindo completude, consistência e profundidade técnica.

Na prática, o SDD inverte a dinâmica da vibe coding (onde o desenvolvedor pede ao agente que crie código livremente): em vez de gerar código diretamente a partir de prompts vagos, o desenvolvedor usa agentes especializados para construir uma base sólida de especificações que, só então, é consumida por agentes de codificação para implementação precisa e consistente.

O resultado é código de maior qualidade, com menos retrabalho e decisões de design tomadas de forma consciente — não improvisadas pelo agente no momento da geração.

BMAD Method

O BMAD Method (Build More Architect Dreams) é um framework de desenvolvimento ágil orientado por IA, 100% gratuito e open source, que implementa o conceito de Spec-Driven Development de forma prática e estruturada. É a recomendação oficial para uso com a plataforma Embrapa I/O.

Por que o BMAD Method?

Ferramentas tradicionais de IA fazem o trabalho de pensar por você, produzindo resultados medianos. Os agentes do BMAD atuam como colaboradores especialistas que guiam um processo estruturado para extrair o melhor do pensamento humano em parceria com a IA:

• Inteligência adaptativa — Ajusta automaticamente a profundidade do planejamento com base na complexidade do projeto;
• Workflows estruturados — Fundamentados em boas práticas ágeis: análise, planejamento, arquitetura e implementação;
• Agentes especializados — 12+ especialistas de domínio: PM, Arquiteto, Developer, UX, Scrum Master e outros;
• Party Mode — Múltiplos agentes em uma mesma sessão, colaborando e debatendo;
• Ciclo de vida completo — Do brainstorming ao deployment.

Instalação

Pré-requisito: Node.js v20+

npx bmad-method install

Siga as instruções do instalador e abra sua IDE de IA (Claude Code, Cursor, etc.) no diretório do projeto.

Dica! Não sabe o que fazer? Pergunte bmad-help — ele indica exatamente qual é o próximo passo e o que é opcional. Você pode fazer perguntas como bmad-help acabei de definir a arquitetura, o que faço agora?.

Módulos

O BMAD Method é extensível por meio de módulos oficiais:

Saiba mais na documentação oficial do BMAD Method.

Alice — Agente de Conformidade

A Alice é um módulo do BMAD Method específico para o Embrapa I/O. Trata-se de uma agente especialista em conformidade com a plataforma: ela analisa codebases, identifica desvios, gera relatórios detalhados com action items e implementa os ajustes necessários para que a aplicação esteja 100% aderente aos padrões da plataforma.

A Alice opera sobre as 4 Verdades Fundamentais da plataforma:

Workflows da Alice

A Alice possui 3 workflows que devem ser executados em sequência:

[VC] Verify Compliance → [IA] Implement Adjustments → [CR] Code Review
         ↓                         ↓                         ↓
  Gera relatório          Implementa ajustes         Valida implementação
  com action items        do relatório               (NOVA SESSÃO!)

[VC] Verificar Conformidade — Analisa completamente o codebase em 6 etapas (detecção de stack, validação do Docker Compose, variáveis de ambiente, settings.json, integrações Sentry/Matomo e geração do relatório). Produz o arquivo embrapa-io-compliance.md com action items detalhados e exemplos de código adaptados à stack do projeto.

[IA] Implementar Ajustes — Executa os action items do relatório, cria os arquivos .env, .env.io, bootstrap.sh, .embrapa/settings.json e LICENSE. Configura integrações com Sentry e Matomo.

[CR] Code Review — Verifica se todas as implementações estão corretas e emite veredicto: APPROVED ou REJECTED. Deve ser executado em uma nova sessão para garantir verificação imparcial.

Escopo da Alice

A Alice pode modificar:

• docker-compose.yaml, Dockerfile
• .env.example, .env.io.example, .env, .env.io
• .embrapa/settings.json
• LICENSE, bootstrap.sh, README.md
• Integrações Sentry e Matomo (configuração mínima)

A Alice não modifica:

• Código funcional da aplicação (exceto integrações Sentry/Matomo)
• Endpoints, rotas ou lógica de negócio
• Testes, CI/CD ou refatoração de código
• Docker Swarm (fora do escopo)

Menu da Alice

Instalação e Uso

1. Instalar o BMAD Method

No diretório do seu projeto:

npx bmad-method install

Siga as instruções do instalador. Selecione a ferramenta de IA que utiliza (Claude Code, Cursor, etc.).

2. Instalar o módulo da Alice

Clone o repositório do módulo dentro da pasta _bmad/:

git clone https://github.com/embrapa-io/bmad.git _bmad/embrapa-io

3. Invocar a Alice

Na sua IDE de IA, utilize o skill correspondente:

Claude Code:

/bmad-agent-embrapa-io-alice

Outras IDEs (Cursor, Windsurf, etc.): invoque o agente conforme a documentação do BMAD para a ferramenta.

4. Seguir o fluxo

1. A Alice se apresentará com um menu interativo;
2. Selecione [VC] para verificar a conformidade do codebase;
3. Revise o relatório gerado em docs/embrapa-io-compliance.md;
4. Selecione [IA] para implementar os ajustes;
5. Abra uma nova sessão e selecione [CR] para o code review final.

Configuração

O arquivo _bmad/embrapa-io/config.yaml permite personalizar:

user_name: Seu Nome
communication_language: Brazilian Portuguese
document_output_language: Brazilian Portuguese
output_folder: "{project-root}/docs"

Base de Conhecimento

O diretório _bmad/embrapa-io/knowledge/ contém 8 arquivos de referência que a Alice utiliza durante as análises: