Engenharia boa aparece no dia 90

Boas práticas de engenharia e arquitetura são aquelas que continuam úteis depois que o entusiasmo do primeiro deploy passa. Elas tornam o sistema mais fácil de mudar, diagnosticar, testar e operar sem depender da memória heroica de quem escreveu a primeira versão.

O sinal de uma arquitetura saudável não é parecer sofisticada em um diagrama. É permitir que uma pessoa nova entenda os limites do sistema em poucas horas, faça uma alteração pequena sem tocar em dez lugares e consiga investigar uma falha com logs, métricas e hipóteses claras.

O que separa prática de preferência?

Em engenharia, muita coisa é vendida como boa prática quando, na verdade, é preferência de time, moda de fornecedor ou trauma de projeto anterior. Uma prática merece esse nome quando melhora algum atributo mensurável: tempo de entrega, taxa de falhas, tempo de recuperação, custo de mudança, segurança ou previsibilidade operacional.

Um exemplo simples: usar TypeScript no front-end não é automaticamente arquitetura. Ele vira prática quando o time define fronteiras de tipos para APIs, impede any em contratos críticos e usa o compilador como barreira real contra regressão. Da mesma forma, microserviços não são maturidade por padrão. Se uma equipe de 5 pessoas transforma um monólito de 80 mil linhas em 14 serviços sem observabilidade distribuída, o resultado provável é mais latência e mais deploy coordenado.

• Prática boa tem contexto: vale para um tipo de problema, escala, time e ciclo de vida.
• Prática boa tem custo explícito: mais testes, camadas ou automação precisam pagar a própria conta.
• Prática boa é verificável: deve aparecer no build, no monitoramento, no review ou na operação.
• Prática boa sobrevive à pressa: se só funciona quando todo mundo está descansado, ainda é sorte.

Como registrar decisões sem criar burocracia?

Arquitetura costuma falhar menos por falta de inteligência e mais por perda de contexto. Seis meses depois, ninguém lembra por que o cache usa TTL de 300 segundos, por que um serviço não pode chamar outro diretamente ou por que a fila foi escolhida em vez de HTTP síncrono. Sem registro, a equipe reabre discussões antigas.

Um ADR, ou Architecture Decision Record, resolve boa parte disso com pouco peso. Não precisa virar documento de 20 páginas. Em muitos times, um arquivo Markdown com 5 seções já basta: contexto, decisão, alternativas, consequências e data.

adr-014-cache-de-produtos.md

Status: aceito
Data: 2026-09-27
Contexto: a listagem de produtos recebe picos de 1.200 req/min em campanhas.
Decisão: cachear respostas públicas por 300s no CDN e invalidar por tag no publish.
Alternativas: consulta direta ao banco; cache Redis por usuário; ISR por rota.
Consequências: publicação pode levar até 5 min para aparecer sem invalidação manual.

Esse nível de registro evita duas perdas caras: repetir debate e apagar trade-off. A decisão acima não diz que cache no CDN é sempre melhor. Ela diz que, naquele sistema, a equipe aceitou até 5 minutos de defasagem para reduzir carga no banco e melhorar latência.

Quais limites arquiteturais valem proteger?

Nem todo limite merece uma abstração. Mas alguns limites precisam ser defendidos com teste, lint, build ou revisão, porque quando eles quebram o sistema acumula dívida invisível. O primeiro é o contrato entre domínio e infraestrutura: regra de negócio não deveria depender diretamente de framework web, SDK de nuvem ou tabela específica do banco.

Um bom teste mental: se amanhã o endpoint REST virar uma fila, o cálculo principal continuaria igual? Se sim, há uma boa chance de o domínio estar razoavelmente isolado. Se não, talvez o sistema esteja confundindo transporte com regra.

Outro limite importante é o de dependência entre módulos. Em um monólito modular, billing pode conhecer contratos públicos de accounts, mas não deveria importar repositórios internos, schemas privados ou componentes de UI. Isso pode ser verificado com ESLint, ArchUnit no Java ou dependency-cruiser em Node.js.

Também vale proteger limites operacionais. Uma API pública precisa ter timeout, retry com limite, idempotência quando há escrita e resposta previsível para falhas. Em chamadas HTTP entre serviços, um padrão simples já evita dano: timeout entre 1 e 3 segundos, no máximo 2 tentativas, backoff com jitter e correlação por request ID.

Como saber se a arquitetura está melhorando?

Arquitetura boa precisa aparecer em indicadores. Quatro métricas úteis vêm do relatório DORA: frequência de deploy, lead time de mudança, taxa de falha em mudança e tempo médio de recuperação. Não é obrigatório copiar metas de big tech; o valor está em acompanhar tendência.

Para um produto pequeno, passar de deploy quinzenal manual para deploy diário com rollback simples já é um salto arquitetural. Para uma plataforma maior, reduzir o tempo de recuperação de 4 horas para 30 minutos pode valer mais que trocar framework.

Além das métricas DORA, três sinais práticos ajudam muito:

1. Tempo para fazer uma mudança pequena: alterar uma regra simples deveria envolver poucos arquivos e baixo risco.
2. Tempo para explicar uma falha: logs e métricas devem mostrar causa provável, não apenas sintomas soltos.
3. Quantidade de conhecimento privado: se só uma pessoa entende deploy, cache ou autenticação, a arquitetura ainda está frágil.

Boas práticas não eliminam escolhas difíceis. Elas deixam o custo das escolhas visível. Às vezes a decisão correta é manter um monólito, usar PostgreSQL sem fila, evitar Kubernetes ou adiar uma camada de abstração. Isso também é engenharia.

No fim, arquitetura é menos sobre prever o futuro inteiro e mais sobre não bloquear o futuro próximo. Um sistema bem projetado aceita mudança incremental, falha de forma observável e deixa rastros suficientes para que a próxima decisão seja melhor que a anterior.

Perguntas frequentes

O que são boas práticas de engenharia de software?

São decisões e hábitos que tornam o software mais confiável, testável, legível e fácil de operar. Elas incluem testes automatizados, revisão de código, observabilidade, documentação de decisões e limites claros entre módulos.

Como aplicar boas práticas de arquitetura em um projeto pequeno?

Comece pelo essencial: contratos bem definidos, testes nas regras críticas, deploy reproduzível, logs úteis e decisões registradas. Projeto pequeno não precisa de muitas camadas, mas precisa evitar dependência implícita.

ADR vale a pena em times pequenos?

Sim, desde que seja leve. Um ADR de 10 a 20 linhas pode economizar horas de reunião quando alguém precisar entender por que uma decisão técnica foi tomada.

Qual métrica mostra que a arquitetura está saudável?

Não existe uma métrica única, mas lead time de mudança, frequência de deploy, taxa de falha e tempo de recuperação formam um bom conjunto. Se mudanças pequenas ficam mais rápidas e incidentes ficam mais fáceis de explicar, a arquitetura está no caminho certo.