// blog

PRD, ADR e SDD: o trio que tira o caos da engenharia (e dos agentes)

O que são Product Requirements Document, Architecture Decision Record e Spec-Driven Development — e como usá-los juntos para alinhar produto, arquitetura e agentes de IA.

engenhariaPRDADRSDDagentesprocesso

Por que isso importa

Em times de engenharia (e especialmente em times que usam agentes de IA), a confusão quase nunca é "falta de código". É falta de contrato compartilhado: o que vamos construir, por que decidimos assim e como vamos executar sem reinventar o processo a cada sprint.

Três artefatos resolvem a maior parte desse caos:

Artefato Pergunta que responde Horizonte
PRD O que vamos construir e por quê? Produto / feature
ADR Por que escolhemos esta solução técnica? Decisão arquitetural
SDD Como vamos planejar e executar com disciplina? Processo / entrega

Eles não são burocracia. São memória externa do time — legível por humanos e, cada vez mais, por agentes.

PRD — Product Requirements Document

O que é

O PRD descreve o produto ou a feature do ponto de vista do problema, do usuário e do resultado esperado. Não é um design de classes. Não é um ticket vago. É o documento que alinha produto, engenharia e (quando existir) design em torno do mesmo "porquê".

O que costuma entrar

  • Problema e contexto de negócio
  • Usuários e jobs-to-be-done
  • Objetivos e métricas de sucesso
  • Escopo (in / out)
  • Requisitos funcionais e não funcionais (latência, custo, segurança, multi-tenant…)
  • Fluxos principais e edge cases importantes
  • Critérios de aceite verificáveis
  • Riscos, dependências e open questions

O que um bom PRD não é

  • Lista infinita de "nice to have" sem prioridade
  • Spec de implementação disfarçada ("use Redis com TTL de 47s")
  • Documento que ninguém atualiza depois do kickoff

Por que uso no dia a dia com agentes

No PR Analyzer, a revisão de código fica muito melhor quando o agente tem o PRD da task como referência: ele deixa de comentar "estilo" genérico e passa a perguntar isso atende o critério de aceite? Diff sem PRD vira opinião. Diff + PRD vira evidência.

Regra prática: se o agente (ou o revisor humano) não consegue dizer se a PR está "pronta" só lendo o PRD + o diff, o PRD está incompleto.

ADR — Architecture Decision Record

O que é

Um ADR registra uma decisão arquitetural importante e o raciocínio por trás dela. Não documenta o sistema inteiro — documenta o porquê de uma escolha que será cara de reverter.

Formato clássico (inspirado em Michael Nygard e variantes leves):

  1. Título — decisão em uma linha
  2. Status — proposto / aceito / depreciado / substituído
  3. Contexto — forças, restrições, o que estava em jogo
  4. Decisão — o que escolhemos
  5. Consequências — trade-offs, o que ganhamos e o que perdemos

Exemplos do mundo real de agentes / backend

  • "Usar Qdrant com coleções/partições por tenant em vez de um único índice global"
  • "Orquestrar sub-agentes com LangGraph em vez de uma cadeia linear de prompts"
  • "Validar documento com visão computacional antes de OCR/LLM caro"
  • "Guardrails de entrada no edge da API, não só no prompt do modelo"

Por que ADR importa

Sem ADR, o time redebate a mesma decisão a cada trimestre — e o agente de coding inventa um "padrão novo" a cada branch. Com ADR, a decisão vira fonte de verdade versionada no repositório.

ADR bom é curto. Se precisar de 15 páginas, você está escrevendo design doc, não ADR.

SDD — Spec-Driven Development

O que é

Spec-Driven Development (desenvolvimento orientado a especificação) é um modo de trabalhar: especificar antes de implementar, com fases claras e verificação contínua — em vez de "codar e ver no que dá".

Na prática, o ciclo costuma se parecer com:

  1. Specify — requisitos e critérios de aceite (muitas vezes a partir do PRD)
  2. Design — desenho técnico, interfaces, ADRs necessários
  3. Tasks — quebra em unidades verificáveis
  4. Execute — implementar com testes e checagens alinhadas à spec

O ponto central: a spec é o contrato. Código que passa nos testes mas foge da spec não está "pronto". Código que implementa a spec e prova isso com evidência está.

SDD + agentes de IA

Agentes brilham quando o alvo é explícito:

  • PRD/spec → o agente sabe o quê
  • ADR → o agente respeita o como arquitetural
  • Tasks + testes → o agente (e o humano) sabem quando parar

Sem isso, multi-agent vira teatro: muito token, pouca entrega.

SDD não é waterfall

Você itera. Specs evoluem. ADRs podem ser substituídos. A diferença é que a mudança de direção fica registrada, e a verificação acompanha a intenção atual — não a intenção de três sprints atrás.

Como os três se encaixam

PRD  →  define valor e aceite (produto)
 │
 ├─► ADR(s)  →  travam decisões caras (arquitetura)
 │
 └─► SDD     →  transforma spec em execução verificável (processo)

Fluxo saudável:

  1. Escreve / atualiza o PRD (problema, escopo, aceite).
  2. Quando uma escolha estrutural aparece, grava um ADR.
  3. Quebra o trabalho em tasks e implementa em modo SDD (spec → design → tasks → execute + verify).
  4. No review (humano ou agente), o diff é julgado contra a spec e os ADRs, não contra o gosto do revisor.

Checklist rápido

Antes de codar uma feature

  • Existe PRD (ou equivalente) com critérios de aceite testáveis?
  • Decisões arquiteturais novas têm ADR (ou reutilizam um existente)?
  • As tasks batem com a spec — e dá para verificar cada uma?

Antes de mergear

  • O diff atende o PRD?
  • Não viola ADRs aceitos?
  • Há evidência (teste, trace, demo) de que a spec foi cumprida?

Conclusão

  • PRD alinha intenção de produto.
  • ADR preserva intenção arquitetural.
  • SDD impõe disciplina de entrega em cima da spec.

Juntos, eles transformam "vibe coding" em engenharia — inclusive quando quem digita o código é um agente.

Se você só puder adotar uma coisa amanhã: escreva critérios de aceite honestos no PRD e faça o review (seu ou do agente) ler esse documento antes do diff.

← Todos os posts