Design antes do código: Product Brief, HLD, LLD e ADR

Aula 17

Do vibe coding ao spec-driven development

Quando alguém pede "faça um sistema de agendamento" a um agente, o agente precisa inventar o que falta: quem são os usuários, quais regras valem, que banco usar, como dividir os módulos. Cada decisão inventada é um ponto em que o resultado pode divergir do que se queria, e essas divergências só aparecem depois que o código existe. O spec-driven development (SDD, desenvolvimento guiado por especificação) inverte a ordem: a especificação vem antes do código e passa a ser a fonte da verdade para a pessoa e para o agente.

Birgitta Böckeler, analisando as ferramentas Kiro, Spec Kit e Tessl, separa três níveis de rigor, que o artigo de Deepak Babu Piskala no arXiv também adota:

Böckeler faz uma distinção importante: especificações são diferentes dos arquivos de "memória" como AGENTS.md. O AGENTS.md vale para toda sessão. A especificação vale para a tarefa que muda aquela funcionalidade. O Thoughtworks Technology Radar colocou o SDD no anel "Avaliar" em novembro de 2025 e registrou ressalvas: as ferramentas são elaboradas e opinativas, e geram arquivos longos difíceis de revisar.

Fontes desta aula: Böckeler: Understanding Spec-Driven-Development · Piskala: Spec-Driven Development (arXiv) · Thoughtworks Radar: Spec-driven development

Aula 18

Product Brief: o problema antes da solução

O primeiro documento do fluxo responde o que e por que, sem falar de tecnologia. No Spec Kit do GitHub, essa etapa se chama Specify. No Kiro, gera o arquivo requirements.md. No fluxo com skills, costuma virar docs/product-brief.md. O guia de design docs do Google, escrito por Malte Ubl, dá a estrutura das primeiras seções, que valem também aqui: contexto e escopo, objetivos e, principalmente, não-objetivos, o que o projeto explicitamente não vai fazer.

• Problema: qual dor existe hoje e para quem.
• Público: quem usa, em que situação.
• Objetivos e não-objetivos: o que entra e o que fica de fora desta versão.
• Critérios de aceite: frases verificáveis que dizem quando está pronto. São o que mais tarde vira teste.
• Restrições: prazo, orçamento, regras legais, integrações obrigatórias.

Os critérios de aceite são o elo entre o brief e os sensores do módulo 6. Um critério como "o usuário recebe confirmação por e-mail em até 1 minuto" pode virar teste automatizado. Um critério como "a experiência deve ser agradável" não pode, e o agente não tem como saber quando parou de cumpri-lo.

Fontes desta aula: GitHub: Spec-driven development with AI · Malte Ubl: Design Docs at Google · Kiro: Specs

Aula 19

HLD: High Level Design

O HLD (High Level Design, design de alto nível) descreve a arquitetura do sistema inteiro: os componentes principais, as interfaces entre eles e uma visão de como tudo se encaixa. Na definição clássica, é escrito em linguagem pouco técnica ou moderadamente técnica e costuma incluir um diagrama de arquitetura (camadas de aplicação, banco de dados, fluxos, segurança e tecnologias), além de dependências, riscos, premissas e usuários finais.

Para um agente, o HLD responde às perguntas que ele mais costuma inventar: em que serviço este código mora, que banco de dados é usado, como os componentes conversam, o que é síncrono e o que é assíncrono. Um HLD típico para trabalho com agentes tem:

• Visão geral e diagrama dos componentes.
• Responsabilidade de cada componente e o que ele não faz.
• Fluxos de dados principais, do pedido do usuário até a resposta.
• Escolhas de tecnologia com a justificativa de cada uma.
• Preocupações transversais: segurança, privacidade, observabilidade e desempenho.
• Alternativas consideradas e por que foram descartadas.
• Riscos e premissas.

O guia do Google insiste em dois pontos que valem para o HLD. Primeiro, o valor de um design doc está nos trade-offs: um documento que só descreve a implementação, sem discutir alternativas, não vale o esforço. Segundo, o documento não deve copiar definições de API ou esquemas de banco, que envelhecem rápido. Isso é trabalho do LLD.

Fontes desta aula: Wikipedia: High-level design · Malte Ubl: Design Docs at Google

Aula 20

LLD: Low Level Design

O LLD (Low Level Design, design de baixo nível) refina o HLD componente por componente. Na definição clássica, traz as estruturas de dados, os diagramas de classes com métodos e relações e as especificações de cada módulo, com detalhe suficiente para que alguém escreva o código diretamente a partir dele. Para um agente, esse "alguém" é o próprio agente.

Um LLD útil para agentes cobre, para cada módulo que será criado ou alterado:

• Arquivos e pastas que serão criados ou modificados.
• Contratos: assinaturas de funções, endpoints, payloads e códigos de erro.
• Modelos de dados e migrações.
• Tratamento de erros e casos de borda.
• Estratégia de testes: quais testes provam cada critério de aceite.
• A lista de tarefas em ordem, pequenas o suficiente para caber numa sessão cada.

É aqui que o fluxo de spec-driven development se encontra com HLD e LLD. No Spec Kit, depois do Specify vêm o Plan (stack, arquitetura e restrições, que pode incluir os documentos internos de arquitetura do time) e o Tasks. No Kiro, cada especificação gera três arquivos: requirements.md, design.md (arquitetura, diagramas de sequência, fluxo de dados, tratamento de erros e estratégia de testes) e tasks.md, com tarefas executadas em ondas segundo um grafo de dependências. Os nomes mudam, mas a estrutura é a mesma:

Fontes desta aula: Wikipedia: Low-level design · GitHub: Spec-driven development with AI · GitHub Spec Kit · Kiro: Specs

Aula 21

ADRs: decisões que o agente não deve desfazer

Um problema recorrente com agentes é a amnésia de decisões: o time escolheu uma biblioteca por um motivo, e meses depois o agente sugere trocá-la porque não sabe do motivo. O ADR (Architecture Decision Record, registro de decisão de arquitetura), proposto por Michael Nygard em 2011, resolve isso com um arquivo curto e numerado por decisão, guardado no repositório, por exemplo em docs/adr/0007-usar-postgres.md.

# 7. Usar PostgreSQL como banco principal

Status: aceito (substitui o ADR 3)

## Contexto
Precisamos de transações e consultas relacionais entre pedidos e estoque.

## Decisão
Usaremos PostgreSQL 16 gerenciado. SQLite fica restrito aos testes.

## Consequências
Migrações passam a ser obrigatórias em todo PR que mude o esquema.

As seções propostas por Nygard são título, contexto, decisão, status e consequências. Decisões substituídas não são apagadas, mas marcadas como substituídas, o que preserva o histórico. O argumento de Nygard é que documentos pequenos e modulares têm mais chance de continuar atualizados do que especificações grandes, e que registrar a motivação evita que o time aceite ou reverta decisões antigas às cegas. Para um agente, um ADR é uma guia perfeita: curta, versionada e ligada a uma pergunta específica. Basta o AGENTS.md dizer "antes de trocar uma dependência ou padrão, leia docs/adr/".

Fontes desta aula: Michael Nygard: Documenting Architecture Decisions · ADR GitHub Organization

Aula 22

Prática: HLD e LLD como skills do harness

O formato que mais aparece em times que usam Claude Code é empacotar cada etapa como uma skill em .claude/skills/: uma para o brief, uma para o HLD e uma para o LLD. Cada skill traz o passo a passo no SKILL.md, o modelo do documento em assets/ e exemplos aprovados em references/. O resultado de cada uma é um arquivo em docs/, revisado por uma pessoa antes da etapa seguinte.

.claude/skills/
  product-brief/SKILL.md
  hld/
    SKILL.md
    assets/hld-template.md
    references/exemplo-hld.md
  lld/
    SKILL.md
    assets/lld-template.md
    references/exemplo-lld.md
docs/
  product-brief.md
  hld.md
  lld.md
  adr/

---
name: hld
description: Gera o High Level Design (docs/hld.md) a partir de docs/product-brief.md.
  Use quando o usuário pedir arquitetura, HLD ou design de alto nível de uma feature.
---
1. Leia docs/product-brief.md e os ADRs em docs/adr/. Se o brief não existir, pare e peça.
2. Explore o código para entender os componentes atuais. Não escreva código.
3. Preencha assets/hld-template.md: componentes, fluxos, tecnologias com justificativa,
   segurança, observabilidade, alternativas descartadas, riscos e premissas.
4. Liste as perguntas em aberto no fim do documento em vez de inventar respostas.
5. Salve em docs/hld.md e peça revisão antes de qualquer LLD.

Três detalhes fazem esse fluxo funcionar. A descrição da skill diz claramente quando usá-la, porque é ela que decide a ativação. O passo "liste as perguntas em aberto em vez de inventar" transforma lacunas em perguntas para a pessoa. E a revisão humana entre etapas é o ponto de controle: revisar um HLD de duas páginas leva minutos, e corrigir uma arquitetura errada depois de mil linhas de código leva dias. O GitHub descreve o mesmo princípio no Spec Kit: cada fase tem um ponto de verificação humana antes da próxima.

Por fim, a skill de LLD deve terminar com a lista de tarefas, e o agente que implementa deve trabalhar uma tarefa por vez, rodando os testes que o próprio LLD definiu. Assim o design vira guia e os testes viram sensores, fechando o ciclo do harness.

Fontes desta aula: Anthropic: Equipping agents with Agent Skills · GitHub: Spec-driven development with AI · GitHub Spec Kit · Kiro: Specs

Aula 23

Quando o processo vira burocracia

Spec-driven development tem custo, e as fontes mais sérias falam disso abertamente. Böckeler observa que os fluxos mais pesados são exagerados para tarefas pequenas, geram muito Markdown tedioso de revisar e nem sempre são seguidos pelo agente. O Radar da Thoughtworks registra que os arquivos de especificação ficam longos e difíceis de revisar e sugere que escrever regras detalhadas à mão para a IA pode não escalar. Tomas Vesely, do GitHub, que escreveu um aplicativo inteiro como especificação em Markdown, admite que os arquivos de instrução são fáceis de esquecer de atualizar e lembra que testes continuam essenciais, porque a especificação descreve a intenção e os testes verificam se ela foi cumprida.

A regra prática é proporcionalidade. A documentação do Claude Code sugere pular o plano quando a mudança cabe numa frase. Para uma feature média, um brief curto e um LLD com tarefas costumam bastar. O HLD completo e os ADRs pagam o custo quando a mudança cria um componente novo, altera fronteiras entre serviços ou toma uma decisão difícil de reverter. Outro cuidado é manter os documentos vivos: um HLD desatualizado é pior que nenhum, porque o agente confia nele. O guia do Google recomenda atualizar ou anexar emendas ao design doc sempre que a implementação revelar problemas.

Fontes desta aula: Böckeler: Understanding Spec-Driven-Development · Thoughtworks Radar: Spec-driven development · GitHub: Markdown as a programming language · Claude Code: Best practices

Erros comuns

• Deixar o agente escrever o HLD sem revisão. O documento parece completo, mas carrega as mesmas suposições que o código carregaria. A revisão humana é o ponto de valor.
• HLD que é um LLD disfarçado. Esquemas de banco e assinaturas de função num documento de arquitetura envelhecem rápido e escondem as decisões importantes.
• Critérios de aceite não verificáveis. Se não pode virar teste, o agente não sabe quando terminou.
• Documentos que ninguém atualiza. O agente confia no que está escrito. Design desatualizado leva a código errado com confiança.
• Processo completo para toda mudança. Correções pequenas não precisam de brief, HLD e LLD.

Aplicação prática

1. Escolha a próxima feature média do seu backlog e escreva um Product Brief de uma página com critérios de aceite verificáveis.
2. Crie as skills hld e lld com modelos em assets/ e peça ao agente que gere os dois documentos, revisando cada um antes de seguir.
3. Registre a decisão técnica mais importante da feature como ADR em docs/adr/ e aponte a pasta no AGENTS.md.
4. Implemente a feature tarefa por tarefa a partir do LLD e compare o retrabalho com a última feature feita sem design prévio.

Siglas usadas neste módulo

HLD:

High Level Design, design de alto nível: arquitetura e componentes do sistema inteiro.

LLD:

Low Level Design, design de baixo nível: detalhe de cada componente, contratos e tarefas.

ADR:

Architecture Decision Record, registro de decisão de arquitetura.

SDD:

Spec-Driven Development, desenvolvimento guiado por especificação.

API:

Application Programming Interface, interface de programação de aplicações.

PR:

Pull Request, pedido de integração de mudanças no repositório.