Herdou um sistema sem documentação? Por onde começar

O fornecedor encerrou o contrato, o desenvolvedor que fez tudo sozinho mudou de emprego ou a empresa que mantinha o sistema simplesmente parou de responder. O software continua rodando, a operação depende dele e ninguém sabe exatamente onde ele está hospedado, como se publica uma correção ou o que acontece se o servidor reiniciar.

Esse cenário é mais comum do que parece, e a reação instintiva costuma estar errada. A vontade é chamar alguém para "dar uma olhada no código" e já começar a corrigir o que incomoda. A ordem certa é outra: primeiro controle, depois conhecimento, depois estabilidade, só então evolução. Este texto é um roteiro para esses primeiros passos.

O primeiro risco não é técnico, é de acesso

Antes de qualquer linha de código, responda a uma pergunta: se o sistema cair hoje, a empresa consegue colocá-lo no ar de novo sem depender de ninguém de fora?

Na maioria das vezes, a resposta honesta é não. O código está no computador ou na conta pessoal de alguém. O servidor está numa conta de nuvem aberta com o cartão do antigo fornecedor. O domínio está registrado no CPF de um ex-funcionário. A senha do banco está num arquivo que ninguém sabe onde fica.

Nesse estado, a empresa não tem um sistema. Ela tem um sistema emprestado, que funciona enquanto nada der errado. O primeiro trabalho, portanto, é recuperar e consolidar o controle. É um trabalho menos glamoroso que refatorar, e muito mais urgente.

Se a transição com o fornecedor antigo ainda está em andamento, vale saber o que o contrato garante. O post sobre propriedade do código-fonte no contrato explica o que deveria estar escrito e o que exigir na saída.

Código-fonte, credenciais, domínios e contas de nuvem

Monte um inventário de ativos, item por item, e coloque cada um sob controle da empresa:

• Código-fonte. O repositório precisa estar numa conta da organização, com histórico completo. Confirme que a versão no repositório é a mesma que está rodando em produção. Não é raro descobrir que as últimas correções foram feitas direto no servidor.
• Contas de nuvem e hospedagem. Titularidade, forma de pagamento e usuários administradores no nome da empresa. Acessos de terceiros que não participam mais do projeto são revogados.
• Domínios e DNS. Registro no CNPJ da empresa, com o contato técnico atualizado. Um domínio que expira sem ninguém perceber derruba o sistema e o e-mail.
• Banco de dados. Usuário administrador, senhas e localização física dos dados.
• Serviços de terceiros. Gateway de pagamento, envio de e-mail, SMS, APIs fiscais, mapas, certificados digitais. Cada um tem conta, chave e contrato, e muitos estão vinculados a um e-mail pessoal.
• Certificados e chaves. Certificado digital para emissão fiscal, certificados SSL, chaves de criptografia e de assinatura de aplicativo nas lojas.
• Lojas de aplicativo. Se há app, a conta de desenvolvedor precisa ser da empresa, ou a publicação de uma simples correção fica impossível.

Tudo isso vai para um cofre de senhas corporativo, com acesso por pessoa e registro de uso. Senhas compartilhadas trocam de valor assim que o controle for assumido.

Backup testado antes de qualquer mudança

Antes de mexer em qualquer coisa, confirme que existe backup e, mais importante, que ele volta. Isso significa:

1. Descobrir o que está sendo copiado: banco, arquivos enviados pelos usuários, configurações.
2. Verificar com que frequência e para onde. Backup no mesmo servidor não protege contra quase nada.
3. Restaurar de fato numa máquina separada e conferir se o sistema sobe com aqueles dados.

Se o backup nunca foi restaurado, você não sabe se ele existe. Este é o momento de corrigir isso, antes que a primeira alteração crie um problema que precise ser desfeito. O raciocínio completo sobre RPO, RTO e cópias protegidas está em plano de recuperação de desastres.

Reproduzindo o ambiente fora de produção

Um sistema que só existe em produção não pode ser corrigido com segurança. O próximo passo é conseguir rodar uma cópia completa em outro lugar.

Na prática, isso revela tudo o que ninguém documentou: a versão exata da linguagem e do framework, bibliotecas que só funcionam numa versão antiga, variáveis de ambiente, tarefas agendadas no servidor, pastas com permissões específicas, serviços que precisam estar rodando.

Cada descoberta é registrada. O objetivo é chegar a uma receita reproduzível, idealmente automatizada com contêineres e scripts de infraestrutura, que monta o ambiente do zero. Com ela você ganha três coisas:

• Um ambiente de homologação para testar correções antes de publicar.
• Um caminho de recuperação caso o servidor de produção se perca.
• A primeira peça real de documentação, escrita em forma que o computador executa e não fica desatualizada.

Os dados usados fora de produção precisam de cuidado: se contêm dados pessoais, devem ser mascarados ou anonimizados antes de circular entre desenvolvedores.

Mapeando o que é crítico e o que ninguém usa

Com o ambiente reproduzido, é hora de entender o sistema pelo uso, não pelo código. Algumas fontes úteis:

• Logs de acesso mostram quais telas e rotas são usadas, por quem e com que frequência.
• O banco de dados revela quais tabelas recebem dados novos e quais estão paradas há muito tempo.
• Entrevistas curtas com cada setor apontam o que é indispensável e o que dá mais problema.
• Tarefas agendadas e integrações mostram o que acontece sem ninguém clicar: arquivos para o banco, sincronização com o ERP, envio de e-mails.

O resultado é um mapa com três colunas: o que é crítico (se parar, a operação para), o que é usado mas tolerante a falhas curtas e o que ninguém usa. Funcionalidades mortas são candidatas a desligamento, o que reduz a superfície de risco e o trabalho futuro.

Nesse mapa entram também os riscos técnicos mais evidentes: dependências sem suporte de segurança, senhas no código, falta de HTTPS, bibliotecas com vulnerabilidades conhecidas. Cada risco recebe uma avaliação simples de impacto e urgência.

Testes de caracterização: documentar o comportamento atual

Sistemas herdados raramente têm testes. E sem testes, qualquer mudança é aposta. A técnica mais útil aqui tem nome: testes de caracterização.

A ideia é não testar o que o sistema deveria fazer, e sim registrar o que ele faz hoje. Você fornece uma entrada, anota a saída atual e transforma isso num teste automatizado. Se o cálculo de frete devolve determinado valor para determinado pedido, o teste garante que continuará devolvendo depois da mudança.

Às vezes o comportamento registrado parece errado. Não corrija na hora. Anote, pergunte ao negócio e decida conscientemente. Muitas "falhas" são regras que alguém pediu anos atrás.

Os testes de caracterização começam pelas partes críticas do mapa: cálculos financeiros e fiscais, regras de preço, integrações. Eles viram a rede de segurança que permite, mais adiante, refatorar sem medo.

Estabilizar primeiro, evoluir depois

Com controle, backup, ambiente e testes nas partes críticas, vem a fase de estabilização. Ela tem objetivos claros:

• Monitoramento básico: saber quando o sistema cai ou fica lento antes do usuário ligar.
• Pipeline de publicação: toda mudança passa pelo repositório e pela homologação antes de produção. Nada mais é editado direto no servidor.
• Correção dos riscos urgentes: atualizações de segurança, credenciais expostas, certificados perto de vencer.
• Documentação mínima viva: como rodar, como publicar, como restaurar, quem chamar.

Só depois disso faz sentido discutir o futuro: evoluir o sistema como está, refatorar partes ou substituí-lo. Essa decisão, com os critérios para cada caminho, está em reescrever ou refatorar um sistema legado. E o acúmulo de problemas que você vai encontrar pelo caminho tem nome e forma de gestão, explicados em dívida técnica para gestores.

O que evitar nos primeiros passos

• Reescrever por impulso, antes de entender o que o sistema faz.
• Atualizar tudo de uma vez: linguagem, framework, banco e servidor no mesmo movimento.
• Corrigir direto em produção para ganhar tempo.
• Confiar na memória de quem usa em vez de observar o uso real.
• Adiar a recuperação de acessos porque "o sistema está funcionando".

Quem conduz a transição

Uma dúvida frequente é se a própria empresa consegue fazer esse trabalho internamente. Depende de quem está disponível. Recuperar contas, domínios e titularidade de serviços é uma tarefa administrativa que o gestor pode e deve liderar, porque envolve contratos, cadastros e decisões que só a empresa toma.

Já reproduzir o ambiente, ler código sem documentação e escrever testes de caracterização exige experiência com sistemas de gerações diferentes. Quem assume precisa ter visto de tudo: framework abandonado, banco com gatilhos, publicação feita por cópia de arquivos. O mais importante, qualquer que seja a escolha, é que o conhecimento produzido fique com a empresa: no repositório, no cofre de senhas e na documentação, e não na cabeça do próximo fornecedor. Caso contrário, o problema se repete na próxima troca.

Checklist dos primeiros passos

• Código-fonte num repositório da empresa, igual ao que roda em produção.
• Contas de nuvem, domínios e serviços de terceiros no nome da empresa.
• Credenciais num cofre, com acessos antigos revogados.
• Backup restaurado com sucesso em ambiente separado.
• Ambiente reproduzível fora de produção.
• Mapa do que é crítico, do que é tolerante e do que ninguém usa.
• Testes de caracterização nas regras críticas.
• Monitoramento e pipeline de publicação funcionando.

Sistema herdado, controle devolvido

Na Pervian Tech, assumir um sistema sem documentação é um trabalho de arquitetura de software antes de ser de programação: recuperar acessos, garantir backup que volta, reproduzir o ambiente e mapear riscos, para só então estabilizar e planejar a evolução. Cada legado é diferente, então o plano é sob medida.

O investimento é definido sob consulta, depois de um diagnóstico inicial gratuito que mostra em que estado o sistema e os acessos realmente estão. Se você herdou um software e não sabe por onde começar, conte o que ficou para trás.