No artigo anterior eu expliquei o que é o Spec-Driven Development e por que ele faz sentido em times que já trabalham com agentes. Agora entra a parte mais importante: como transformar isso em operação de verdade.
Quando a conversa sai do conceito e chega no projeto real, os problemas quase sempre aparecem nos mesmos pontos: stories vagas, critérios ambíguos, testes incompletos, review superficial e commits que passam sem garantia suficiente. É exatamente aí que SDD precisa ser mais concreto.
Neste post eu vou organizar essa parte prática em cinco blocos: como escrever requisitos obrigatórios sem ambiguidade, o que uma story precisa ter antes de começar, o que precisa ser verdade antes de considerar que ela terminou, quais gates seguram qualidade no caminho e quais templates ajudam a manter o processo repetível.
Antes dos Checklists: Requisitos Obrigatórios Claros#
Antes de entrar em DoR, DoD e quality gates, vale acertar uma base importante: como escrever os requisitos obrigatórios. Se essa camada já nasce ambígua, todo o resto degrada junto, incluindo planning, implementação, review e testes.
Uma forma simples de resolver isso é usar EARS (Easy Approach to Requirements Syntax). Ele não é um framework de IA, nem substitui PRD, story ou ADR. É só um formato enxuto para escrever requisitos obrigatórios de um jeito claro, testável e difícil de interpretar errado.
Isso ajuda muito quando o trabalho passa por múltiplos agentes ou múltiplas mãos. Se o requisito está ambíguo, cada pessoa ou agente completa as lacunas do seu próprio jeito. Quando ele está escrito nesse formato, fica mais fácil revisar, testar e automatizar validação.
A ideia é simples: usar a palavra-chave SHALL pra indicar requisitos obrigatórios. Em português, o equivalente mais natural é DEVE. Isso elimina ambiguidade e facilita validação automática:
The system SHALL [mandatory action] WHEN [condition]
Exemplos em português:
- “O sistema DEVE retornar 403 quando um usuário sem permissão acessar um recurso protegido”
- “O sistema DEVE validar input do usuário antes de processar qualquer requisição”
- “A story DEVE ter todos os ACs em formato Given/When/Then antes de ser implementada”
Quando você lê um requisito com DEVE/SHALL, fica claro: é obrigatório, é testável, e não tem muita margem pra interpretação. Nos checklists a seguir, vou usar esse padrão justamente pra deixar explícito o que é inegociável.
Definition of Ready (DoR)#
Antes de implementar qualquer story, ela precisa estar pronta. Parece óbvio, mas é aqui que a maioria dos problemas com IA começa: a story chega vaga, sem critérios claros, e o agente faz o que acha melhor.
Uma story DEVE ser considerada pronta quando:
- ACs verificáveis — cada critério de aceite DEVE estar em formato Given/When/Then com resultados mensuráveis
- Tasks sequenciadas — as tarefas DEVEM ter dependências identificadas e ordem de execução
- Arquivos-alvo identificados — os locais de mudança DEVEM estar listados
- Specs consistentes — a story DEVE estar alinhada com PRD, arquitetura e UX
- Tipos de teste definidos — cada AC DEVE ter seu tipo de teste: unit, integration, E2E
- Cenários de erro identificados — casos como not-found, forbidden e invalid-input DEVEM estar mapeados
- Pesquisa completada — docs oficiais DEVEM ter sido consultados, não apenas a memória do agente
- Impacto de segurança avaliado — auth, autorização e validação de input DEVEM estar avaliados
O agente Arquiteto valida o DoR antes da implementação começar. Se falhar, corrige a story e revalida.
Definition of Done (DoD)#
Se o DoR evita começar mal, o DoD evita terminar cedo demais. Em projetos com agentes isso importa ainda mais, porque “funcionou uma vez” não significa “está realmente pronto”.
Do outro lado, uma story DEVE ser considerada feita quando passar por todas essas camadas:
Qualidade do Código#
- Code review adversarial DEVE ter sido completado, com todos os findings corrigidos
- Princípios SOLID e Clean Code DEVEM ter sido verificados
- Zero código morto, zero TODO/FIXME pendente
Testes#
- Todos os testes DEVEM passar — test suite completa do projeto, não só o que mudou
- TDD por AC — cada critério de aceite DEVE ter passado pelo ciclo RED -> GREEN -> REFACTOR
- Mapeamento AC -> teste — cada AC DEVE ter no mínimo 1 teste documentado
- Cenários de erro testados — not-found, forbidden, invalid-input
- Isolamento de dados — Usuário A NÃO DEVE conseguir acessar dados do Usuário B (quando aplicável)
Build & Types#
- Build completo DEVE passar sem erros
- Type-check DEVE passar sem erros (se a linguagem suportar)
- Lint DEVE passar sem violações
UI (quando aplicável)#
- Validação no browser: renderização, zero erros no console, dark + light mode
- Responsivo: testado em mobile, tablet e desktop
- Acessibilidade: ARIA labels, navegação por teclado, contraste
Como diz o pessoal do Scrum.org: “IA é probabilística, rode o mesmo prompt 100 vezes e você pode ter 95 respostas corretas e 5 alucinações. Se sua DoD depende apenas de checks binários Pass/Fail, você não tá testando seus agentes, tá apostando.”
Perceba como o formato EARS torna cada item do DoR e DoD inequívoco: se tem DEVE (ou SHALL no original em inglês), é obrigatório e pode ser validado. Sem essa marcação, é recomendação.
Quality Gates#
Com DoR e DoD definidos, falta a parte que faz isso deixar de ser só intenção: gates que realmente travam o fluxo quando algo importante falha.
Essa é provavelmente a prática mais importante de todo o SDD: ter verificações que precisam passar antes de cada commit. A ideia é criar camadas que peguem problemas antes que eles cheguem ao repositório.
A ordem sugerida é:
| # | Gate | O que pega |
|---|---|---|
| 1 | Code Review | Erros de lógica, violações de arquitetura, segurança |
| 2 | Testes | Regressões, contratos quebrados |
| 3 | Build | Erros de compilação, imports quebrados |
| 4 | Type-check | Violações de tipagem |
| 5 | Auditoria de deps | Vulnerabilidades em dependências |
A maioria dessas verificações pode ser automatizada com git hooks (pre-commit, pre-push) e pipelines de CI. O importante é que sejam tratadas como inegociáveis — se um gate falha, o commit não acontece.
Estratégia de Testes#
Quality gate sem estratégia de teste vira só checklist burocrático. Para funcionar de verdade, você precisa saber que tipo de teste cobre cada tipo de risco.
Que tipo de teste usar?#
TDD por Critério de Aceite#
O fluxo pra cada AC é:
1. Escrever teste que falha (RED) — Teste captura o comportamento do AC
2. Implementar código mínimo (GREEN) — Fazer o teste passar, nada mais
3. Refatorar (REFACTOR) — Limpar sem mudar comportamento
4. Repetir pro próximo AC
O que mockar e o que não mockar#
Essa tabela evita uma das armadilhas mais comuns em projetos com IA:
| Camada | Mockar? | Por quê |
|---|---|---|
| Lógica de negócio / domínio | NUNCA | É o que você tá testando |
| Banco de dados (em testes de integração) | NUNCA | Use DB real com fixtures |
| APIs HTTP externas | SIM | Instáveis, lentas, podem custar dinheiro |
| File system / storage | SIM | Side effects, cleanup |
| Tempo / datas | SIM | Testes determinísticos |
| Internals do framework | NUNCA | Confie no framework |
Anti-pattern: Testes que só usam mocks são perigosos. Eles testam seus mocks, não seu código.
Protocolo de Bug Fix#
Outro ponto que vale padronizar cedo é o tratamento de bug. Se cada correção entra de um jeito, o sistema vai acumulando remendos sem memória do que já quebrou.
Todo fix de bug segue essa sequência:
- Escreva um teste de regressão que reproduz o bug
- Corrija o bug
- Verifique que o teste passa
- Commit do teste + fix juntos
Code Review: Multi-Perspectiva#
Depois de testes e gates, entra a camada que pega o que script nenhum enxerga bem sozinho: trade-off ruim, acoplamento desnecessário, risco arquitetural e falha de raciocínio.
Code review no SDD não é uma olhada rápida. É uma análise adversarial de múltiplas perspectivas:
| Perspectiva | O que pega | Severidade |
|---|---|---|
| Arquitetura | Limites de módulos, acoplamento, abstrações faltando | HIGH |
| Segurança | Injection, bypass de auth, leak de dados sensíveis | CRITICAL |
| Lógica | Edge cases, race conditions, off-by-one, null handling | HIGH |
| Performance | N+1 queries, índices faltando, operações desnecessárias | MEDIUM |
| Estilo | Naming, tamanho de função, complexidade, código morto | LOW |
| Testes | Coverage faltando, mock errado, testes frágeis | MEDIUM |
O review tem três possíveis vereditos:
- Ready to Merge: Zero findings CRITICAL/HIGH
- Needs Attention: Apenas findings MEDIUM
- Needs Work: Findings HIGH ou CRITICAL, corrigir tudo e re-review
Camadas de Enforcement#
Uma coisa boa do SDD é que ele não depende de um único checkpoint mágico. As verificações se empilham em camadas, e cada uma pega um tipo diferente de problema:
Não precisa implementar todas de uma vez. Comece pela camada 2 (pre-commit hooks) e vá subindo.
Templates Essenciais#
Quando esse processo começa a funcionar, surge outro problema: cada história, ADR ou checklist passa a ser escrito de um jeito. Template bom não engessa o trabalho; ele reduz atrito e mantém consistência.
Template de Story#
# Story [Epic]-[Story]: [Título]
## Story Statement
COMO [papel], EU QUERO [ação] PARA QUE [valor]
## Status: ready-for-dev | in-progress | review | done
## Critérios de Aceite
### AC-1: [Nome]
- DADO [precondição]
- QUANDO [ação]
- ENTÃO [resultado esperado]
- **Tipo de teste:** unit | integration | E2E
### AC-2: [Nome]
...
## Tasks
- [ ] Task 1: [Descrição] (AC-1)
- [ ] Task 2: [Descrição] (AC-2)
- [ ] Task 3: Escrever testes (AC-1, AC-2)
- [ ] Task 4: Code review
- [ ] Task 5: Atualizar artefatos
Template de ADR#
## ADR-[ID]: [Título]
**Status:** Proposed | Accepted | Deprecated
**Data:** YYYY-MM-DD
### Contexto
[Qual é o problema? Por que uma decisão precisa ser tomada?]
### Opções Consideradas
1. **Opção A:** [Descrição] — Prós: [x, y]. Contras: [a, b].
2. **Opção B:** [Descrição] — Prós: [x, y]. Contras: [a, b].
### Decisão
[Qual opção foi escolhida e por quê]
### Consequências
- [O que muda como resultado]
- [Que novas restrições são introduzidas]
Checklist: Configurando SDD num Novo Projeto#
Fase 0: Fundação#
- Repositório inicializado com Git e .gitignore
- Constituição do projeto (
AGENTS.md,CLAUDE.mdou equivalente) criada com overview, comandos e regras de ouro - Estrutura de regras por escopo criada para testes, coding e quality gates
- Linter e formatter configurados
- Type checker configurado (se a linguagem suportar)
- Framework de testes configurado
- Git hooks instalados: pre-commit com lint + format + secret scan
- Pipeline CI criado: testes + build + security scan
Fase 1-3: Análise, Planejamento e Solucionamento#
- Product Brief criado com visão, personas, métricas
- PRD criado com FRs em formato Given/When/Then
- Arquitetura documentada com ADRs pras decisões-chave
- Stories criadas com ACs e tasks
- Validação de Implementation Readiness
Ongoing#
- Pipeline decisão-para-regra ativo: novos patterns viram regras
- Pipeline bug-para-regra ativo: classes de bugs viram regras de prevenção
- Specs vivas: artefatos atualizados com aprendizados da implementação
Considerações finais#
Implementar SDD não precisa ser tudo ou nada. Se eu pudesse recomendar por onde começar:
- Crie a constituição do projeto (
AGENTS.md,CLAUDE.mdou equivalente) com overview do projeto, comandos e 5-10 regras de ouro - Configure quality gates básicos: testes + build passando antes de cada commit
- Adote Given/When/Then pros critérios de aceite das suas stories
- Comece a documentar ADRs pras decisões técnicas importantes
Com o tempo, vá adicionando as outras camadas: code review multi-perspectiva, progressive disclosure de regras, sync de artefatos, formato EARS nos requisitos.
O mais importante é entender que a IA é uma ferramenta poderosa, mas sem um contrato claro de specs ela produz código plausível mas errado. SDD é esse contrato.
Repositório oficial do BMAD Method.
Comentários
Os comentários usam Disqus e só são carregados se você clicar no botão abaixo.