Herdei um sistema que ninguém documentou: as duas primeiras semanas

As duas primeiras semanas num código legado sem documentação: subir o sistema do zero, instrumentar produção e mapear os fluxos de receita. E por que reescrever no dia 4 dá ruim.

Herdar sistema sem documentação começa por entender o que já roda em produção

Você recebeu as chaves de um sistema que ninguém documentou. Nas duas primeiras semanas, não escreva feature nova e não refatore nada. Faça três coisas, nesta ordem: suba o sistema do zero na sua máquina anotando cada passo que faltava, instrumente o que já está em produção para enxergar erro, latência e volume de verdade, e desenhe os cinco ou seis caminhos por onde o dinheiro entra. O resto do código pode continuar feio até o dia 15.

A ordem importa mais que a lista. Estancar o sangramento é rápido. Diagnosticar a origem do sangramento demora mais. Tratar a doença é remédio de meses. Quem inverte isso anuncia reescrita no dia 4, some por um trimestre e volta com metade das regras de negócio perdidas no caminho.

A pergunta "herdei 200 mil linhas de código espaguete, e agora?" está no Stack Exchange desde 2012, passou de 200 mil visualizações e acumulou 463 votos em 19 respostas. Quase toda resposta discute qualidade de código. O problema das duas primeiras semanas é anterior a isso: você ainda não sabe o que o sistema faz, e nenhuma decisão boa sai da ignorância.

Se ninguém sobe o sistema do zero, comece por aí

O primeiro documento verdadeiro do projeto é a lista do que faltou para subir o sistema

Pegue uma máquina limpa, ou um container vazio, e tente rodar. Anote cada coisa que faltou: a variável de ambiente que só existia no notebook do dev que saiu, o dump de banco que alguém manda por WhatsApp, a versão de runtime travada em algo de três anos atrás, o serviço de terceiro que não tem sandbox e por isso ninguém testa localmente.

Esse arquivo de anotações é o primeiro documento verdadeiro do projeto. Em obra existe uma coisa chamada as-built: a planta do que foi construído de fato, e não a do que foi desenhado no escritório. É exatamente isso que você está fazendo.

Se levou dois dias e meio, tudo bem. O número que interessa é o tempo entre um dev novo receber o acesso e ver o primeiro request rodando local. Ele vira sua métrica de progresso pelos meses seguintes, e é o único indicador que o time inteiro entende sem explicação.

Deploy entra no mesmo balde. Um deploy de 50 minutos que qualquer pessoa consegue disparar é notícia melhor do que um deploy de 6 minutos que só o Fulano sabe fazer, e eu já escrevi sobre por que isso foi a melhor coisa que achei numa auditoria. Lento você otimiza. Dependente de uma pessoa você reza.

O dashboard verde e o /health que devolve 200

O exemplo de casca podre que mais aparece nos resgates: o sistema tem um endpoint /health, ele responde 200, existe um painel colorido em algum lugar, e nada daquilo mede o que realmente quebra. A métrica existe, a garantia não.

Instale o básico e pare por aí: log estruturado com identificador de requisição, agrupamento de erro em alguma ferramenta de captura, tempo de resposta por rota no ponto de entrada. Nada disso encosta em regra de negócio, então o risco é baixo e você consegue fazer na primeira semana.

Uma semana de dado real de produção ensina mais sobre o sistema do que um mês lendo código. Você descobre que três rotas concentram quase todo o tráfego. Que boa parte da lentidão, algo perto da metade nos casos que passaram por aqui, vem de meia dúzia de queries encadeadas dentro de um laço. E que aquele erro que "acontece de vez em quando" acontece umas 400 vezes por dia sem ninguém olhar.

Os cinco caminhos que pagam a conta

Dívida técnica só entra na pauta do board quando vira frase de negócio

Sistema legado não tem mapa, mas tem gente que sabe onde dói. Marque uma hora com o suporte, uma com o financeiro e uma com a pessoa mais antiga da operação. Pergunte o que o cliente liga reclamando, o que trava no fechamento do mês e qual planilha existe hoje para contornar o software.

Você quer sair dessas conversas com uma folha listando os fluxos que, se pararem agora, geram prejuízo hoje:

• o cadastro e o login, porque cliente que não entra não compra e a reclamação chega em minutos
• o checkout ou a emissão do pedido, com todas as integrações de pagamento que ele dispara por baixo
• o job noturno de faturamento, que costuma ser o script mais antigo e mais crítico da casa
• as integrações de saída com ERP, contabilidade ou marketplace, onde falha silenciosa vira divergência fiscal três meses depois
• o relatório que a diretoria abre toda segunda, porque é ele que define se o sistema tem fama de confiável

Cinco caminhos, cada um com um dono e com evidência de log, valem mais que 200 mil linhas mapeadas em diagrama. E a lista é sua régua de prioridade para todo o resto do ano.

"Isso aqui é impossível de manter, melhor reescrever"

Essa frase vai passar pela sua cabeça no dia 4. Eu quase nunca aprovo reescrever um sistema do zero, e o motivo é bem prático: aquele código horroroso é a única documentação viva das regras de negócio. O if estranho no meio do serviço de pedido costuma ser um contrato assinado com um cliente grande em 2019, e ninguém no time atual sabe disso. Reescrita joga fora a resposta junto com a pergunta.

Onde esse conselho falha, e ele falha: runtime sem suporte de segurança, dependência crítica que não recebe patch há anos, stack para a qual não existe mais gente disponível no mercado. Aí a conta vira, e mesmo assim o caminho é por pedaço, com o sistema antigo funcionando de referência ao lado. Também não sei se esse plano de duas semanas faz sentido para um sistema de 3 mil linhas com quarenta usuários. Para esse, uma tarde resolve.

O outro detalhe que derruba reescrita é que o negócio não congela enquanto você reconstrói. Software é vivo, o concorrente lança, a regra tributária muda, e você fica com dois sistemas para manter em vez de um.

A cobertura de 92% que não testa nada

Peça o número de cobertura de testes e desconfie dele na hora. Teste sem expect roda, passa, conta como linha coberta e não garante nada. Já escrevi sobre cobertura alta que esconde bug em produção, e o cenário se repete: suíte verde, deploy tranquilo, cliente ligando.

Rode mutation test em um módulo crítico, um só. Se quase todo mutante sobreviver, você tem teatro de qualidade, e agora tem prova disso para mostrar.

Não tente escrever a suíte inteira em duas semanas. Escreva teste de caracterização nos cinco caminhos de receita, fixando o comportamento atual do jeito que ele está hoje, inclusive quando está errado. É uma rede de proteção, e ainda não é qualidade. Qualidade vem depois, quando você já souber o que pode mexer sem derrubar faturamento.

O que você leva para a diretoria no dia 14

Não leve roadmap de refatoração. Leve quatro artefatos: o README que sobe o sistema do zero, o painel com erro e latência reais de produção, o mapa dos caminhos de receita com dono e a lista curta de riscos com prazo e dinheiro do lado de cada um.

Dívida técnica só entra na pauta do board quando vira frase de negócio. "O job de faturamento não tem reprocessamento, então uma falha de madrugada atrasa a emissão de um dia inteiro de nota" faz o CFO parar e ouvir. "Precisamos refatorar o módulo de pedidos" faz o CFO olhar o celular.

Se alguém no fundo da sala sugerir trocar o time inteiro, coloque na conta quanto custa recontratar e reonboardar sênior nas faixas praticadas hoje no Brasil. Costuma sair bem mais caro que o resgate, e o relógio de conhecimento perdido volta para o zero. Quando a fábrica que construiu o sistema virou as costas e não sobrou ninguém que conheça o código, é aí que entra squad sênior embarcado, que é o trabalho de resgate que a gente faz.

Abra o repositório agora e responda uma pergunta só: quanto tempo um dev novo leva para subir isso do zero sem perguntar nada para ninguém? Se você não sabe o número, seu dia 1 é hoje, e as duas semanas começam a contar.