Spec-Driven Development no Mobile: Spec Kit, BMAD, OpenSpec e o que eu uso no dia a dia

Se você já passou dez minutos estruturando um prompt antes de pedir código ao Cursor, Copilot ou Claude Code, parabéns: você já pratica Spec-Driven Development (SDD). Só talvez ainda não tenha dado nome ao processo.

Nos meus projetos pessoais, isso é rotina. Quando oriento squads em contextos enterprise (Super Apps com anos de código, onboarding regulado, convergência entre GenAI, Server-Driven UI e segurança mobile), a conversa muda de tom: o risco não é a IA errar sintaxe Swift ou Kotlin. O risco é duplicar módulos, ignorar contratos de SDK interno, quebrar isolamento de feature flags ou violar guidelines de segurança que levaram meses para amadurecer.

SDD formaliza o que times maduros já fazem de forma ad hoc. E hoje existem três frameworks open-source que materializam essa disciplina com abordagens distintas: GitHub Spec Kit, BMAD Method e OpenSpec. Cada um ocupa um lugar diferente no espectro que vai do leve ao completo, e escolher errado é usar martelo para quebrar noz, ou canivete para construir um shopping center.

*Observação: este é um post longo. Leia com calma. Escrevi pensando em devs mobile, tech leads e arquitetos que já usam IA no dia a dia, mas ainda não sabem quando formalizar specs, e qual ferramenta adotar em cada contexto.*

Este post também foi escrito em inglês, clique aqui para acessar a versão em inglês.

1. O problema que ninguém fala

A promessa da IA generativa no desenvolvimento mobile é sedutora: descreva o que quer e receba código. Na prática, em um Super App brownfield, o agente não conhece o histórico de decisões do seu monorepo. Ele não sabe que o módulo :feature-wallet já existe, que o AuthSDK é o único ponto de entrada para sessão, ou que o design system proíbe componentes fora do DSKit.

O resultado? Código que compila, mas que não pertence à arquitetura.

Spec-Driven Development propõe inverter a lógica: antes do código, alinhamos intenção, restrições e critérios de aceite em artefatos estruturados que vivem no repositório. Como diz o posicionamento do GitHub Spec Kit: manter software passa a significar evoluir especificações; o código vira last-mile.

Neste artigo, trago a visão dos três pilares que uso e recomendo, um roteiro prático para Super Apps brownfield, e uma matriz para decidir qual filosofia adotar conforme seu contexto: enterprise, greenfield ou brownfield.

2. O que é uma "spec" neste contexto

O termo "spec" ainda está em disputa no mercado. Birgitta Böckeler, Distinguished Engineer na Thoughtworks, propôs uma taxonomia útil em sua análise sobre Kiro, spec-kit e Tessl:

flowchart LR
  subgraph levels [NiveisSDD]
    SF[SpecFirst]
    SA[SpecAnchored]
    SS[SpecAsSource]
  end
  SF --> SA --> SS

• Spec-first: você escreve a spec antes do código para a tarefa em andamento.
• Spec-anchored: a spec permanece no repositório como fonte de verdade na evolução da feature.
• Spec-as-source: o humano edita apenas a spec; o código é gerado (ainda experimental).

Para mim, a distinção mais prática é outra: Memory Bank versus Spec de feature.

O Memory Bank são documentos que orientam todas as sessões de IA no projeto. A spec é relevante apenas para a funcionalidade que está sendo criada ou alterada.

Os três frameworks materializam artefatos SDD; a disciplina RPI (Research → Plan → Implement) governa quando o agente pode avançar de leitura para planejamento e de planejamento para código. Detalho isso na seção 8.

O conceito que mais mudou minha forma de trabalhar em brownfield veio do OpenSpec: em vez de reescrever a spec inteira, você produz deltas: diffs de requisitos com + e -, que mostram exatamente o que muda no sistema. O revisor entende a intenção sem reler quarenta páginas de markdown.

3. GitHub Spec Kit: o canivete suíço no IDE

O GitHub Spec Kit é uma CLI que instala templates, prompts e slash commands no workspace. Funciona com Cursor, Copilot, Claude Code e outros assistentes.

O workflow principal segue uma sequência clara:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement

Para features com ambiguidade relevante, o quickstart oficial recomenda gates adicionais: /speckit.checklist e /speckit.analyze antes da implementação.

Artefatos típicos por feature: spec.md, plan.md, tasks.md, research.md, data-model.md, contratos de API.

Por que funciona bem no mobile

• Constitution como contrato imutável: ideal para regras de plataforma. Exemplo que uso: *"nunca acessar Keychain fora do módulo SecurityCore"*.
• Tasks com IDs sequenciais, dependências explícitas e marcador [P] para tarefas paralelizáveis: útil quando iOS e Android evoluem o mesmo contrato de domínio em módulos separados.
• Integração Git: branch por spec, conversão de tasks em issues com /speckit.taskstoissues.
• Checklists como Definition of Done por fase: o agente (e você) sabe quando avançar.

Onde eu vejo limitações

Böckeler testou o Spec Kit em uma feature de 3–5 pontos em codebase existente e concluiu que o volume de markdown gerado foi desproporcional ao tamanho do problema. Em um bug pequeno, o workflow virou "martelo para quebrar noz": quatro user stories e dezesseis critérios de aceite para uma correção pontual.

Outros pontos que já vivi na prática:

• O agente pode ignorar notas de "código existente" no research.md e duplicar classes.
• Muitos arquivos para revisar em brownfield, e, honestamente, às vezes prefiro revisar código do que markdown repetitivo.
• O modelo ainda é mais spec-first do que spec-anchored de longo prazo (cada spec nasce em branch; a persistência pós-merge depende de disciplina do time).

O Technology Radar da Thoughtworks (Abr/2026) posiciona o Spec Kit como mais adequado a projetos greenfield, e concordo, com ressalvas para módulos novos dentro de monorepos maduros.

4. BMAD Method: o sistema operacional para enterprise

O BMAD Method (Build More Architect Dreams, ou, como traduzo para times brasileiros, Método de Avanço para Desenvolvimento Ágil Orientado por IA) é um framework open-source de ciclo de vida completo. A documentação está em docs.bmad-method.org.

Enquanto o Spec Kit foca no pipeline spec → implementação, o BMAD cobre desde brainstorming até deploy, com agentes especializados (PM, Architect, Developer, UX, Test Architect e outros).

flowchart TD
  idea[IdeaOuBug] --> analysis[AnalysisPhase]
  analysis --> planning[PlanningPRDArchitecture]
  planning --> solutioning[Solutioning]
  solutioning --> impl[Implementation]
  impl --> validate[TestArchitectTEA]

Por que adoto em contextos enterprise

• Established Projects: workflow pensado para brownfield, não só greenfield.
• Test Architect (TEA): estratégia de testes baseada em risco. Em apps financeiros, isso não é luxo.
• Party Mode: múltiplas personas de agente discutindo trade-offs. Útil quando modularização de Super App envolve PM, arquiteto e chapter lead.
• Web Bundles: planejamento (PRD, UX, pesquisa de mercado) no Gemini ou ChatGPT com assinatura flat-rate; artefatos refinados depois no IDE. Economia real em engajamentos longos.
• Constitution implícita via project context + ADRs: alinha diretamente com o que escrevi no guia de ADRs para IA generativa.

Onde eu vejo limitações

• Curva de instalação: npx bmad-method install, Node.js, Python, uv.
• Pode ser pesado para protótipo de fim de semana.
• Exige disciplina para não virar documentação infinita que ninguém lê.
• O Radar da Thoughtworks classifica workflows como o BMAD como mais rígidos que alternativas leves como o OpenSpec.

5. OpenSpec: o pilar brownfield e spec-anchored

O OpenSpec é um framework leve de SDD, destacado no Technology Radar da Thoughtworks (Abr/2026) na categoria Assess: vale explorar para entender o impacto no seu contexto enterprise.

O que me convenceu foi o posicionamento explícito: brownfield-first. A maioria das ferramentas SDD assume que você está começando do zero. OpenSpec assume que você está evoluindo um sistema que já existe, e isso descreve 90% do meu trabalho profissional.

Comparativo rápido dos três frameworks

Workflow

propose → apply → archive

Um comando típico no Cursor: /openspec:proposal. O agente busca specs existentes, lê o código relevante e gera uma pasta de mudança:

openspec/changes/add-wallet-overview/
├── proposal.md      ← o porquê da mudança
├── design.md        ← decisões técnicas
├── tasks.md         ← passos de implementação
└── specs/           ← deltas de requisitos
    └── wallet-session/
        └── spec.md  ← diff com novos cenários GIVEN/WHEN/THEN

A biblioteca de longo prazo vive em openspec/specs/, organizada por capability:

openspec/specs/
├── auth-login/spec.md
├── auth-session/spec.md
├── wallet-summary/spec.md
└── checkout-payment/spec.md

Cada spec usa cenários GIVEN/WHEN/THEN: alinhado com BDD e com o formato de acceptance criteria do Kiro.

Exemplo de delta que eu escreveria para um fluxo mobile:

### Requirement: Exibição de saldo offline
- O app DEVE exibir o último saldo cacheado quando offline.
#### Scenario: Usuário sem conectividade
- GIVEN o usuário autenticado com saldo cacheado há menos de 24h
- WHEN o dispositivo está offline
- THEN exibir saldo com indicador "última atualização"
+ AND desabilitar ações que exijam rede (transferência, PIX)

Por que OpenSpec virou meu default em brownfield

• Review de intenção, não só de código: o revisor lê o delta antes do PR de implementação.
• Troca de agente sem perder contexto: specs no Git sobrevivem à mudança de Cursor para Copilot.
• Archive mergeia o delta na spec viva: onboarding de dev novo no módulo feature-wallet fica trivial.
• Não é waterfall: o próprio OpenSpec diz: gaste dez minutos pensando, não três semanas planejando.

Limitações que preciso mencionar

• Workspaces para multi-repo ainda em desenvolvimento.
• Não substitui BMAD em discovery de produto complexo.
• Exige que alguém leia e pense nas specs: não é vibe coding automático.
• O Radar recomenda monitorar capacidades nativas dos agentes e reavaliar a necessidade de tooling SDD periodicamente.

6. Enterprise, Greenfield e Brownfield: qual filosofia adotar

Antes de escolher ferramenta, calibre o contexto do projeto. Essa é a seção que mais uso quando oriento profissionais na empresa.

6.1 Os três contextos

Nota importante: Enterprise não é oposto de brownfield. Na prática, enterprise é quase sempre brownfield. A distinção aqui é de maturidade organizacional: quantas squads, quanto compliance, quanto processo formal o negócio exige.

6.2 Três filosofias SDD

Antes da ferramenta, escolha a postura do time:

Os três frameworks mapeiam naturalmente:

• OpenSpec → spec-anchored (brownfield incremental)
• Spec Kit → spec-first com constitution (greenfield ou feature nova)
• BMAD → spec-governed (enterprise com discovery e TEA)

6.3 Matriz de adoção

flowchart TD
  start[QualContexto] --> gf{Greenfield}
  start --> bf{Brownfield}
  start --> ent{Enterprise}

  gf -->|appOuModuloNovo| sk[SpecKit_Constitution_Plan]
  gf -->|prototipoRapido| light[OpenSpec_Proposal_Leve]

  bf -->|evolucaoCapability| os[OpenSpec_Delta_Archive]
  bf -->|moduloNovoNoMonorepo| sk2[SpecKit_ComConstitutionMobile]
  bf -->|refactorGrande| bmad[BMAD_EstablishedProject]

  ent -->|epicoMultiSquad| bmad2[BMAD_Plus_TEA_Plus_ADR]
  ent -->|manutencaoRegulada| os2[OpenSpec_SpecsVivas]
  ent -->|featureIsoladaPorSquad| sk3[SpecKit_BranchPorSpec]

6.4 Como aplico em cada contexto

Greenfield: começar certo sem travar

Começo com constitution mobile via Spec Kit antes da primeira linha de código: min SDK, arquitetura de módulos, regras de segurança. Conforme capabilities nascem, vou criando specs OpenSpec: não tento documentar tudo upfront. BMAD só entra se o escopo crescer além de um dev.

Brownfield: evoluir sem quebrar o que funciona

Default: OpenSpec para qualquer mudança que toca comportamento existente. O agente deve ler openspec/specs/ e o código do módulo antes de propor. Spec Kit entra quando é módulo novo dentro do monorepo. BMAD quando o refactor atravessa boundaries de squad.

Enterprise: governança sem paralisia

Modelo híbrido que recomendo:

• BMAD para discovery, arquitetura e test strategy em iniciativas estratégicas.
• OpenSpec como camada de comportamento versionada: quando o auditor pergunta "o que o app deveria fazer?", a resposta está no Git.
• Spec Kit por squad em features delimitadas, com constitution alinhada ao chapter mobile.
• ADRs como ponte entre os três.

6.5 Tamanho do problema (matriz complementar)

6.6 Regras que repito para o time

Greenfield: invista 30 minutos na constitution. É o melhor ROI que você terá com IA.

Brownfield: nunca peça código antes de o agente ler o que já existe: spec delta ou research step são inegociáveis.

Enterprise: não escolha uma ferramenta: escolha um modelo híbrido. OpenSpec na esteira de manutenção, BMAD na esteira de inovação.

Regra de ouro: se a mudança cabe em um PR de um dev em um dia, OpenSpec ou nada. Se atravessa squads, BMAD.

flowchart LR
  subgraph spectrum [EspectroSDD]
    OS[OpenSpec_Leve_Brownfield]
    SK[SpecKit_Medio_Greenfield]
    BM[BMAD_Completo_Enterprise]
  end
  OS --> SK --> BM

Escolha em 30 segundos

7. Roteiro prático: Super App brownfield

Vou exemplificar com um cenário que vivo com frequência: adicionar um módulo de resumo de carteira (wallet overview) dentro de um Super App existente, com SDK interno de autenticação, feature flags, analytics e design system.

Fase 0: Memory Bank (todas as abordagens)

Antes de qualquer spec de feature:

• architecture.md: diagrama de módulos (host app, feature modules, shared kernels)
• mobile-constitution.md: min iOS/Android, offline, acessibilidade WCAG, ProGuard/R8, certificate pinning
• ADRs existentes referenciados
• Contratos: OpenAPI do BFF, schema de feature flags, eventos de analytics
• OpenSpec: openspec/specs/wallet-summary/spec.md se a capability já existir parcialmente

Caminho A: Spec Kit

1. /speckit.constitution: princípios mobile + *"não recriar classes do módulo CoreNetworking"*
2. /speckit.specify: user stories: usuário offline vê último saldo cacheado
3. /speckit.clarify: qual BFF? qual tela no grafo de navegação?
4. /speckit.plan: KMP ou Swift Package, integração SDUI
5. /speckit.tasks: waves paralelas com [P]
6. /speckit.implement: reviso código, não só markdown
7. /speckit.converge: gap analysis

Exemplo de task:

- [ ] T014 [P] [US2] Implementar WalletSummaryViewModel em feature-wallet/domain/
- [ ] T015 [US2] Integrar com AuthSDK.getSession() - NÃO criar novo client HTTP

Caminho B: BMAD

1. bmad-help: workflow Established Project
2. Analysis: dependências do módulo host (agente Architect)
3. Planning: PRD + diagrama de sequência (login → BFF → cache)
4. Solutioning: módulo dinâmico vs compile-time; impacto em CI por flavor
5. Implementation: Dev agent com contexto shardado
6. TEA: matriz de risco: P1 saldo, P2 empty states, P3 animações

Caminho C: OpenSpec

1. Research: /openspec:proposal com "Adicionar resumo de carteira com suporte offline e empty states"
2. Research: agente lê openspec/specs/auth-session/spec.md e código em feature-wallet/ (só fatos, sem propor solução ainda)
3. Plan: gera openspec/changes/add-wallet-overview/ com proposal, design, tasks e spec delta
4. Plan: revisão humana do delta: alinhamento com segurança mobile
5. Implement: Apply guiado por tasks.md
6. Implement + encerramento SDD: Archive mergeia o delta em openspec/specs/wallet-summary/spec.md

Comparativo no mesmo cenário

O que muda na prática mobile

• Modularização: specs citam boundaries (:feature-wallet, WalletKit)
• Plataforma dupla: tasks paralelizáveis com mesmo contrato de domínio
• SDUI + GenAI: spec descreve intent; design define renderer nativo vs servidor
• Segurança: threat modeling em fluxos financeiros, em qualquer framework
• CI/CD: PR inclui review de spec delta antes do code review

A regra que mantenho inegociável: a IA propõe, o especialista audita. Isso vale para código e para specs.

8. RPI: Research, Plan, Implement, a disciplina por trás do SDD

Ter constitution.md, spec delta ou research.md no repositório não impede o agente de ignorar tudo se a sessão começa com "implementa isso". SDD responde o que documentar e onde persistir. Falta a camada que responde em que ordem o agente age, e quando parar.

É aí que entra o RPI (Research → Plan → Implement), popularizado pelo ecossistema HumanLayer e documentado de forma acessível no guia da Kilo Path e no repositório comunitário patrob/rpi-strategy. RPI não é um quarto framework ao lado de Spec Kit, BMAD e OpenSpec. É a meta-disciplina que torna os três efetivos: separa leitura, planejamento e execução em fases com gates explícitos.

SDD define os artefatos; RPI define os gates entre fases da sessão.

flowchart TB
  subgraph sdd [CamadaSDD_Artefatos]
    MB[MemoryBank]
    Spec[SpecOuDelta]
    Tasks[TasksOuPlan]
  end
  subgraph rpi [CamadaRPI_Disciplina]
    R[Research_SoFatos]
    P[Plan_TasksAtomicas]
    I[Implement_Verificar]
  end
  R -->|"FAR gate"| P
  P -->|"FACTS gate"| I
  R -.-> MB
  P -.-> Spec
  P -.-> Tasks
  I -.->|"archive / converge"| Spec

As três fases

Como resume o guia da Kilo Path: planning without research leads to bad assumptions: planejar sem pesquisar gera suposições ruins. Em brownfield mobile, isso se traduz em duplicar AuthSDK, ignorar :feature-wallet ou violar a constitution sem perceber.

RPI nos três frameworks

O Spec Kit já embute RPI no pipeline: o research.md da seção 3 nunca tinha nome, mas é Research puro. O mapeamento fica assim:

Gates leves: FAR e FACTS

Não precisa virar burocracia. O patrob/rpi-strategy propõe duas escalas de validação: uso como checklist mental, não como planilha obrigatória:

• FAR (Research): Factual ≥4, Actionable ≥3, Relevant ≥3: o agente tem evidência no código ou está inventando?
• FACTS (Plan): média ≥3 em Feasible, Atomic, Clear, Testable, Scoped: cada task cabe em um PR pequeno e é verificável isoladamente?

Exemplo que substituo o prompt vago:

Em vez de: "Adiciona tela de carteira"

Research: *"Mapeie o que existe em :feature-wallet e AuthSDK. Evidência: paths, contratos, specs em openspec/specs/. Sem propor solução ainda. Valide FAR."*

Plan: "Quebre em tasks atômicas com paths Gradle/SPM. Valide FACTS: cada task < 4h e testável isoladamente."

Implement: "Execute T014; rode testes; marque checkbox."

O que mudo na prática

• Brownfield: Research inegociável: já repito isso na seção 6.6; com RPI, ganho vocabulário para o time.
• Contexto fresco entre fases: em tarefas de risco, prefiro sessão nova (ou /clear no Cursor) ao sair de Research para Plan, e de Plan para Implement. Contexto inchado degrada a qualidade do agente: insight que o ecossistema HumanLayer documentou ao escalar RPI em produção.
• Bug pontual (matriz 6.5): RPI colapsado: Research de cinco minutos + Implement direto, sem plano formal.

Nota: HumanLayer evoluiu o workflow original para CRISPY: mais estágios de alinhamento antes do código. Para brownfield mobile, SDD + RPI já cobrem a maior parte do ganho; CRISPY vale explorar quando o escopo atravessa squads e o custo de desalinhamento é alto.

9. Como penso, planejo e executo

Minha sequência em sete passos: os quatro primeiros escolhem filosofia e ferramenta SDD; os três últimos seguem o esqueleto RPI:

1. Identificar contexto: greenfield, brownfield ou enterprise
2. Escolher filosofia: spec-first, spec-anchored ou spec-governed
3. Calibrar: tamanho e clareza do problema
4. Escolher o pilar: OpenSpec (evolução), Spec Kit (feature nova), BMAD (épico)
5. Research: memory bank + ADRs + specs existentes + leitura do código relevante
6. Plan: spec ou delta + tasks; gates FAR/FACTS quando o risco justificar
7. Implement: executar mecanicamente, verificar em dispositivo, archive ou converge

Anti-patterns que vejo em empresas:

• Spec gigante sem constitution → IA inventa stack
• Pular leitura de specs existentes em brownfield → duplicação de código
• Tratar spec como prompt descartável → perde rastreabilidade em auditoria
• Usar BMAD completo para ajuste de padding
• Gerar todas as specs upfront no OpenSpec → contrário ao modelo incremental
• Sessão monolítica Research + Plan + Implement no mesmo prompt → o agente "alucina" arquitetura
• Plan sem Research em brownfield → suposições que viram PR descartável

10. Convergências com o que já evangelizo

ADRs são o memory bank de decisões. Specs referenciam ADR-00X; agentes entendem o porquê além do o quê.

Server-Driven UI encaixa naturalmente: a spec descreve o contrato do componente; o design define se o renderer é nativo ou servidor.

GenAI executa tasks; o humano valida em dispositivo real, com testes de contrato e SAST onde couber.

MobileOps beneficia de specs anchored, especialmente o archive do OpenSpec, como documentação viva para releases e rollback.

11. Conclusão

SDD não substitui julgamento humano. Formaliza disciplina.

• Greenfield → constitution primeiro (Spec Kit); specs OpenSpec nascem com o produto.
• Brownfield → OpenSpec como default; Spec Kit só para módulos novos.
• Enterprise → modelo híbrido: BMAD na inovação, OpenSpec no comportamento versionado, ADRs nas decisões.

Os três frameworks convergem no princípio spec-first. Divergem no peso, na persistência e na governança. RPI é a camada transversal que impede o agente de pular direto para código: SDD sem RPI vira documentação que o agente ignora; RPI sem SDD vira chat efêmero sem rastreabilidade.

Antes de instalar qualquer CLI, mapeie seu contexto na matriz da seção 6. A ferramenta é consequência da filosofia: não o contrário.

Experimente nos projetos pessoais. Calibre o processo. Depois escale para o enterprise com a confiança de quem já viu o que funciona, e o que vira documentação morta.

Referências

Spec-Driven Development (conceito e análise)

• Martin Fowler: Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl
• OpenSpec: What is Spec-Driven Development?
• Comprehensive Guide to Spec-Driven Development (Medium / Visrow)
• What is BMAD Method? A Simple Guide (Medium / Visrow)
• GitHub Spec Kit vs BMAD Method: Part 1 (Medium / Visrow)

Ferramentas

• GitHub Spec Kit
• BMAD Method: Documentação
• BMAD Method: Workflow Map (BMM)
• BMAD Method: Repositório GitHub
• OpenSpec: Site oficial
• OpenSpec: Repositório GitHub
• Kiro Specs: Documentação

Radar e avaliação independente

• Thoughtworks Technology Radar: OpenSpec (Abr/2026)

Agentic workflows

• Research, Plan, Implement (RPI): Kilo Path
• patrob/rpi-strategy: GitHub
• HumanLayer: evolução de RPI para CRISPY (ZenML)

Leitura complementar

• ADR: Guia Prático para Documentar Arquitetura e Potencializar IA Generativa