Cultura de engenharia frágil em um sistema acoplado¶

Demandas viram retrabalho porque uma correção em um ponto costuma causar impacto em outros, e hoje a gente não tem barreiras confiáveis para detectar isso antes de publicar.

O mais crucial para quebrar esse ciclo é ter três pilares funcionando juntos

testes automatizados, para detectar possíveis inconsistências antes de publicar
code review, para mapear riscos e compartilhar contexto antes da publicação
documentação, para deixar regra e conceito claros e reduzir dependência de conhecimento na cabeça de poucas pessoas

Contexto¶

Hoje o legado é um sistema muito acoplado. Na prática isso significa que partes diferentes do negócio ficam amarradas no mesmo conjunto de rotinas e dados. Uma mudança feita para resolver um contexto específico pode mexer em regras e comportamentos que também sustentam outros fluxos.

Quando somamos isso com ausência de testes automatizados, falta de documentação e pouca cultura de revisão de código, o resultado é previsível: a gente apaga um incêndio e inicia outros, sem perceber na hora.

O que é o problema, em linguagem simples¶

Este problema tem quatro peças que se reforçam

Acoplamento alto:
- Uma alteração feita para atender a área X pode afetar Y e Z, mesmo sem intenção.
Falta de testes automatizados
- O time fica sem segurança no que publica. O que deveria ser um ajuste pontual vira uma sequência de correções depois que já está em produção.
Falta de documentação
- Regras importantes ficam na cabeça das pessoas. Setores diferentes passam a acreditar em versões diferentes do mesmo processo, e a realidade do sistema não é transparente.
Falta de code review consistente
- Mudanças com risco e inconsistência passam despercebidas. Também fica mais difícil rastrear a origem de um defeito quando ele aparece.

Como isso acontece hoje¶

Um desenho típico do ciclo de retrabalho no legado é este

flowchart TD A[Demanda nasce para resolver um contexto X] --> B[Mudança em rotina acoplada] B --> C[Validação manual limitada] C --> D[Publicação] D --> E[Impacto colateral aparece em Y ou Z] E --> F[Correção urgente] F --> G[Nova publicação] G --> H[Outro impacto colateral]

Onde esse ciclo pesa mais¶

Demoras maiores do que o esperado para entregar, porque parte do tempo vira correção pós publicação
Aumento de risco operacional, porque o sistema continua funcionando, mas do jeito errado
Risco de segurança, porque controles frágeis e mudanças sem revisão podem manter vulnerabilidades por mais tempo
Piora de experiência para corretor, cliente e áreas internas quando um fluxo crítico fica inconsistente

Exemplos práticos¶

Preencher com exemplos de demandas

Exemplos¶

Mudança feita para X
Onde ela encostou no sistema
Qual efeito apareceu em Y ou Z
Como detectamos
Quanto tempo levou para corrigir
O que teria evitado, teste, revisão, documentação

Impactos no negócio¶

Tempo e retrabalho¶

Entrega vira duas etapas, fazer e depois consertar o que quebrou em paralelo
Prioridades mudam por urgência, e a fila normal fica travada

O que a API Nova muda para resolver ou reduzir o problema¶

A API Nova não resolve acoplamento de um dia para o outro, mas cria guardrails para reduzir impacto colateral e aumentar segurança do que entra em produção.

1. Testes desde o início¶

Na API Nova, a gente trata teste como parte do trabalho, não como um extra que entra só quando sobra tempo. Isso inclui teste unitário para regras e validações, e testes de integração mínimos nos fluxos mais críticos.

O objetivo é simples: se uma mudança quebra uma regra importante, a gente descobre antes de publicar.

2) Code review como filtro de qualidade e compartilhamento de conhecimento¶

Na API Nova, code review precisa deixar de ser opcional. A ideia não é burocracia, é reduzir risco. Uma segunda pessoa olhando a mudança costuma enxergar impacto em áreas que quem implementou não estava vendo, principalmente num cenário de legado acoplado.

Além de pegar problemas antes de publicar, revisão ajuda em três pontos práticos:

qualidade, porque erros e inconsistências são identificados cedo
rastreio, porque fica mais fácil entender de onde veio uma mudança quando aparece um bug
evolução do time, porque feedback técnico vira rotina e o conhecimento não fica preso em uma pessoa

Para desenvolvedores novos, isso acelera muito. Com revisão frequente, eles ganham orientação no próprio fluxo de trabalho, entendem padrões do time e evitam repetir erros comuns.

3) CI CD para reduzir variação humana e aumentar repetibilidade¶

Na API Nova, a publicação precisa seguir um caminho repetível. Build, testes e deploy por ambiente deixam de depender de passos manuais e de memória de quem está executando. Isso ajuda a garantir que o que foi validado é exatamente o que foi publicado.

4) Melhor rastreabilidade para reduzir tempo de diagnóstico¶

A padronização de correlation id, logs mínimos e tabelas de erro e auditoria melhora o tempo de entender o que aconteceu quando algo dá errado. Isso não evita o erro sozinho, mas reduz muito o custo de descobrir a causa e corrigir.

5) Documentação como parte do trabalho, não como extra¶

Hoje a gente perde tempo por dois motivos ao mesmo tempo primeiro porque cada setor entende as regras de um jeito, e segundo porque o sistema muitas vezes faz diferente do que todo mundo imagina. Sem uma fonte oficial, decisões e regras ficam na cabeça das pessoas, e qualquer mudança vira um jogo de adivinhação.

Na API Nova, a documentação entra como entregável junto com a mudança. Mudou uma regra, precisa estar explicado o que mudou, por que mudou, e quais partes do fluxo podem ser afetadas. Isso reduz retrabalho porque o time passa a enxergar impacto antes de publicar, e não só depois que alguém reclama.

Isso também resolve um problema que hoje trava o time processos críticos ficam concentrados em poucos desenvolvedores. Quando só uma pessoa entende uma parte do sistema, a demanda fica refém, o ajuste vira risco, e o time não consegue ganhar velocidade.

Para desenvolvedores novos, a diferença é enorme. Hoje a curva de aprendizado estagna no começo porque o conhecimento está espalhado e informal. Com documentação clara, o dev novo entende o que existe, o que é regra do negócio e o que é detalhe de implementação. Isso acelera onboarding, reduz erro bobo, e evita que cada pessoa tenha que descobrir tudo do zero na marra.

Na prática, a documentação que mais ajuda é simples um mapa do fluxo, contratos de entrada e saída, regras de validação, e pontos de impacto conhecidos. Não precisa virar um livro, precisa virar referência.