O conhecimento do sistema antigo após a reescrita

As pessoas que entendem um sistema antigo não são um incômodo temporário no caminho para um código mais limpo. Elas fazem parte do modelo operacional atual do sistema. Uma reescrita que ignore o que sabem pode reproduzir cada tela visível e ainda falhar no primeiro reembolso incomum, ajuste de fechamento trimestral ou reinício de processamento em lote.

O objetivo útil não é «baixar» o cérebro de alguém antes da aposentadoria. É transformar afirmações sobre o comportamento em evidências que outra pessoa possa examinar: exemplos, testes, registros de decisões, procedimentos operacionais e incertezas nomeadas. Esse trabalho também dá aos especialistas um papel confiável após a virada. Trate-os como testemunhas e revisores, não como obstáculos nem como documentos humanos de especificação.

O sistema antigo também inclui as pessoas

O conhecimento de um sistema antigo vive em vários lugares ao mesmo tempo. Uma parte está no código-fonte e nas definições de jobs. Outra aparece nos dados de produção, manuais operacionais, histórico de chamados e planilhas de conciliação. O restante está nas pessoas que sabem que o status de cliente 7 significa algo diferente antes do fechamento do mês, ou que um lote com falha precisa recomeçar no terceiro checkpoint porque as duas primeiras etapas não são idempotentes.

Chamar tudo isso de «conhecimento tribal» é vago demais para ajudar. Eu o separo em quatro tipos porque cada um exige evidências diferentes:

• Regras de negócio: o resultado que a organização pretende para um caso específico.
• Comportamento observado: o que o sistema atual realmente faz, inclusive defeitos dos quais outros consumidores dependem.
• Prática operacional: como as pessoas agendam, recuperam, conciliam e sobrepõem decisões do sistema.
• Justificativa histórica: por que uma regra, tabela ou solução provisória existe e o que pode quebrar se ela desaparecer.

Essas categorias muitas vezes entram em conflito. Um especialista pode descrever a regra aprovada enquanto a produção segue uma exceção antiga. Um operador pode conhecer um procedimento seguro de recuperação que nenhum desenvolvedor conhece. Uma gerente financeira pode chamar uma diferença de arredondamento de defeito enquanto um relatório posterior depende dela. A equipe de reescrita precisa manter a distinção até que alguém tome uma decisão explícita.

Por isso, um organograma é um mapa ruim do conhecimento do sistema. A pessoa mais informada pode ser um analista de suporte que prevê qual entrada vai travar o job noturno, ou um antigo desenvolvedor que agora trabalha em operações. Comece pelos eventos do sistema, não pelos cargos: quem é chamado quando o faturamento falha, quem aprova a conciliação, quem entende os registros rejeitados e quem sabe por que uma exportação aparentemente sem uso ainda roda?

As pessoas também erram. A experiência merece respeito, mas memória não é prova. Quem conhece o sistema antigo fornece hipóteses, exemplos e contexto. Testes e registros transformam essas contribuições em algo no qual a migração pode confiar.

Entrevistas precisam de casos, não de passeios

A maneira mais rápida de desperdiçar o tempo de um especialista é perguntar: «Como o sistema funciona?». Você receberá um passeio pelos menus e pelo caminho ideal. Nenhum dos dois revela as condições que causaram os dez últimos incidentes de produção.

Conduza entrevistas em torno de casos concretos. Peça que a pessoa traga uma transação concluída, uma rejeitada, um ajuste manual, um reinício e uma saída que exigiu conciliação. Depois, faça com que ela reconte o que viu, o que esperava, o que alterou e como soube que o resultado era aceitável. Gravações de tela ajudam, mas o registro escrito deve capturar entradas e decisões, não só cliques.

Nessas sessões, uso um pequeno registro de afirmações. Cada linha tem uma afirmação, uma fonte, um exemplo representativo, uma verificação proposta, um responsável e um nível de confiança. Uma linha pode dizer: «Uma conta suspensa pode receber um crédito, mas não um débito», com a liderança de cobrança como fonte, dois IDs de transação e um teste de limite proposto. Outra pode registrar: «Os operadores reiniciam JOB17 em STEP30 após um timeout», com o operador noturno como fonte, o log de execução correspondente e um teste de recuperação ainda ausente.

O campo de confiança impede que uma conversa educada vire falsa certeza. Use rótulos simples, como confirmado pelo tráfego, confirmado por teste repetível, sustentado por duas pessoas, lembrança única e contestado. A confiança descreve a evidência, não a senioridade.

Faça perguntas incômodas. O que você faz fora do sistema? Em quais campos nunca confia? O que verifica antes de aprovar a saída? Qual mensagem de erro significa «tente novamente», embora pareça fatal? O que aconteceu na última mudança dessa regra? Quem discorda da sua versão? Essas perguntas revelam planilhas paralelas, aprovações por telefone e controles compensatórios que uma análise de código não enxerga.

Mantenha as sessões curtas o bastante para que os especialistas continuem precisos. Devolva as afirmações para correção em um ou dois dias, enquanto os exemplos ainda estão frescos. Uma transcrição é matéria-prima, não documentação. Alguém precisa esclarecer nomes, anexar evidências e separar afirmações compostas antes que a sessão produza materiais de migração.

Separe intenção de compatibilidade

Uma reescrita precisa distinguir a política pretendida do comportamento de compatibilidade, pois preservar qualquer um por acidente gera surpresas caras. As equipes costumam confundir «o negócio quer isto» com «o programa antigo faz isto». As afirmações podem apontar em direções opostas.

Para cada comportamento importante, registre três respostas: o que o sistema antigo faz, o que a organização quer depois da reescrita e o que consumidores ou relatórios existentes esperam. Depois, atribua uma decisão. Preservar significa que o sistema novo deve corresponder. Corrigir significa que ele será intencionalmente diferente e precisa de uma expectativa aprovada. Desativar significa que o comportamento e seus consumidores somem juntos. Desconhecido significa que a virada ainda não pode depender dele com segurança.

Considere um programa de faturamento que arredonda cada item antes de somar a fatura. A política escrita manda somar os itens sem arredondamento e arredondar o total. Clientes podem ter recebido faturas arredondadas por item durante anos, enquanto uma importação contábil espera os centavos resultantes. «Corrigir» o cálculo dentro da reescrita pode quebrar a conciliação, ainda que a nova resposta seja matematicamente preferível.

A decisão não pode ficar escondida no pull request de um desenvolvedor. A área financeira deve escolher entre preservar o resultado, ajustar a interface contábil ou introduzir a regra corrigida a partir de um limite declarado. A suíte de paridade então codifica o resultado escolhido. A documentação registra por que os resultados antigo e novo diferem. O suporte recebe um exemplo reconhecível.

Em Working Effectively with Legacy Code, Michael Feathers usa testes para colocar o comportamento existente sob controle antes de alterá-lo. A ideia vale além do código-fonte. Um teste de caracterização informa o que acontece agora. Ele não declara que o comportamento está correto. A governança da migração começa onde a caracterização termina: alguém com autoridade decide o que vira contrato.

Essa distinção também evita colocar uma responsabilidade injusta nos especialistas. A pessoa que lembra de uma solução provisória não deve decidir sozinha se ela sobrevive. Seu trabalho é revelar o comportamento e a consequência. Os responsáveis por negócio e engenharia decidem o futuro por escrito.

Transforme afirmações em exemplos executáveis

O conhecimento se torna durável quando uma afirmação pode reprovar em um teste. A prosa continua importante, mas sozinha permite que dois leitores imaginem condições de limite diferentes.

Escreva exemplos na fronteira do sistema sempre que possível. Capture a menor entrada que aciona a regra, o estado inicial relevante, as saídas esperadas e os efeitos colaterais permitidos. Evite testes que validem sequências de chamadas internas da implementação antiga. Eles preservam a estrutura em vez do comportamento e punem qualquer modernização verdadeira.

Um registro de comportamento pode ser simples o bastante para um especialista revisar:

{
  "case": "credit_on_suspended_account",
  "starting_state": {"status": "suspended", "balance": 12500},
  "input": {"type": "credit", "amount": 2500},
  "expected": {
    "accepted": true,
    "balance": 10000,
    "audit_code": "CR-SUSP"
  },
  "source": "collections_review_14"
}

Os valores precisam de unidade e significado. Se 12500 representa unidades monetárias menores, diga isso na convenção do fixture. Se as datas usam o dia útil local em vez de UTC, codifique essa condição. Muitas supostas falhas de paridade são fixtures ambíguos.

Crie famílias de testes em torno dos limites, não apenas um exemplo de referência. Para a regra da conta suspensa, teste um crédito, um débito, zero, o valor máximo aceito, uma mudança de status durante o processamento e a repetição da mesma solicitação. O especialista muitas vezes sabe quais casos já causaram problemas. O engenheiro sabe onde os limites da implementação podem vazar. As duas perspectivas pertencem à suíte.

Registre o resultado antigo e o aprovado separadamente quando forem diferentes. Um harness útil pode informar MATCH, APPROVED_DIFFERENCE, UNEXPLAINED_DIFFERENCE ou NOT_COMPARABLE. Um resultado binário de aprovação ou falha incentiva as equipes a aceitar mudanças inexplicadas só para deixar um painel verde.

A CodeHero usa um harness de paridade com tráfego de produção gravado enquanto moderniza a arquitetura, em vez de apenas transcrever o código antigo. A mesma disciplina deve orientar o conhecimento dos especialistas: cada lembrança importante precisa de um caso reproduzível, uma decisão aprovada ou um estado pendente visível.

O tráfego de produção tem pontos cegos

O tráfego de produção gravado é a fonte mais forte para o comportamento comum, mas não contém todas as regras que a reescrita precisa preservar. Ele mostra o que aconteceu durante o período de captura. Diz pouco sobre caminhos raros de fim de ano, recuperação de desastre, funções de emergência sem uso, entradas rejeitadas antes de chegar ou eventos que operadores corrigiram manualmente antes do registro.

Trate o tráfego e o depoimento dos especialistas como complementares. Comece reproduzindo solicitações capturadas nos sistemas antigo e novo e compare os resultados visíveis externamente. Agrupe diferenças por endpoint, tipo de transação, campo de saída e classe de erro. Depois, mostre grupos representativos às pessoas que operam ou respondem por esses fluxos. Elas identificam uma diferença inofensiva de timestamp, um defeito conhecido ou uma regra ausente muito mais rápido que uma equipe lendo diffs brutos.

O tráfego precisa de contexto para virar um corpus estável de testes. Oculte ou tokenize valores sensíveis preservando as relações. Fixe dados de referência que mudariam entre execuções. Registre pressupostos de relógio, localidade, regras de ordenação e respostas fornecidas por dependências. Mantenha o identificador original da captura para que uma investigação possa rastrear um caso com falha sem copiar dados de produção para um chamado.

Desconfie da amostragem. Um endpoint movimentado pode dominar o corpus enquanto uma transação rara e de grande consequência aparece uma vez. Crie visões de cobertura por evento de negócio e risco, não só por quantidade de solicitações. Pergunte aos especialistas quais eventos precisam aparecer mesmo que nenhuma captura recente os contenha. Depois, construa casos sintéticos a partir de um exemplo aprovado e execute-os no sistema antigo quando isso for seguro.

Não use a reprodução de tráfego como desculpa para evitar decidir quais saídas importam. Uma comparação byte a byte sinaliza IDs gerados, timestamps, ordem e formatação inofensiva. Normalização demais pode esconder um lançamento contábil ausente. Nomeie os campos observáveis e as tolerâncias para cada classe de transação. Um especialista deve explicar por que uma diferença é ignorada.

Por fim, mantenha uma quarentena para casos que ainda não podem ser comparados. Uma mensagem pode chamar um parceiro indisponível, depender de dados de referência vencidos ou acionar uma ação irreversível. Casos em quarentena precisam de responsável e motivo. Se a equipe simplesmente os apagar do corpus, a incerteza desaparece do relatório, mas continua no sistema.

A documentação precisa explicar decisões

Uma boa documentação de migração diz ao próximo engenheiro o que o sistema promete, onde essa promessa é testada e por que uma exceção existe. Um catálogo de telas e tabelas fica desatualizado antes da virada porque descreve a forma antiga, não o novo contrato.

Dê a cada comportamento importante um registro compacto. Inclua o evento de negócio, pré-condições, resultados aceitos e rejeitados, responsável oficial, identificadores de testes, resposta operacional e histórico de decisões. Ligações internas no repositório ou sistema de documentação podem conectar esses itens, mas o conteúdo deve continuar legível sem abrir outras cinco páginas.

Registros de decisão importam mais quando a paridade foi quebrada de propósito. Informe o comportamento antigo, o escolhido, consumidores afetados, aprovadores, condição de implantação e sinal de reversão. Evite entradas vagas como «corrigido problema de cálculo». Escreva a diferença exata: «A nova fatura arredonda o total uma vez; o adaptador contábil inclui uma linha de compensação nas faturas criadas antes da data da política».

Os manuais operacionais precisam do mesmo tratamento. Uma instrução como «reinicie o lote se ele travar» é perigosa. Defina como o operador detecta a trava, qual checkpoint é seguro, quais efeitos colaterais duplicados deve inspecionar, qual conciliação comprova a conclusão e quando escalar. Transforme pré-condições seguras em verificações automáticas quando possível. Deixe decisões de julgamento explícitas quando a automação apenas fingiria certeza.

A responsabilidade pela documentação precisa mudar junto com o sistema. Durante a migração, o especialista antigo pode verificar uma regra enquanto um engenheiro novo escreve o registro e o teste. Depois da virada, o responsável pelo serviço assume ambos. Essa autoria em dupla evita transformar o especialista em secretário permanente de uma plataforma que não opera mais.

A facilidade de busca importa, mas uma única base de conhecimento gigantesca não é a resposta. Mantenha o comportamento perto dos testes executáveis, os procedimentos perto do serviço e as decisões de política onde os responsáveis as revisam. Use IDs de caso consistentes nesses lugares. O ID é o fio condutor; a consolidação forçada costuma criar um cemitério.

Revise a documentação tentando executar uma tarefa. Dê um caso com falha a um engenheiro que não participou da migração e peça que explique o resultado esperado, localize o teste e encontre o caminho de recuperação. A confusão dele é um defeito de documentação com um exemplo reproduzível.

Especialistas não podem virar uma fila

Os especialistas do sistema antigo devem ter autoridade real na reescrita, mas fazer cada decisão esperar por uma pessoa troca conhecimento oculto por um gargalo visível. A resposta é um protocolo de revisão que gaste a atenção deles com ambiguidade e risco.

Atribua a cada especialista um papel limitado. Ele pode responder pelas afirmações de uma área, aprovar exemplos representativos, classificar diferenças de paridade ou verificar um manual. Declare quais decisões pode tomar e quais exigem um responsável de negócio, segurança ou serviço. Uma matriz RACI é opcional; um caminho claro de escalonamento não é.

Prepare o material antes de pedir revisão. Não convide um operador para assistir a milhares de resultados passando pela tela. Agrupe diferenças, remova o ruído conhecido, selecione exemplos e apresente a pergunta como decisão: preservar, corrigir, desativar ou investigar? Inclua o caso de origem e a consequência posterior. Dez minutos de julgamento especializado podem substituir horas vagando por logs.

Use cobertura de duas pessoas nas áreas de grande consequência. Coloque o especialista experiente ao lado de alguém que seguirá responsável após a virada. A segunda pessoa escreve o teste ou manual, demonstra e cuida da próxima questão relacionada. O especialista corrige o trabalho em vez de ditar cada frase. É assim que a transferência de conhecimento fica observável.

Proteja o tempo formalmente. Uma revisão de migração acrescentada a uma carga operacional cheia perderá para o próximo incidente, como deve acontecer. Gestores precisam remover outras tarefas, agendar janelas de decisão e acompanhar afirmações sem resposta como riscos de entrega. Não meça participação pela presença em reuniões. Meça afirmações resolvidas, exemplos aprovados, diferenças inexplicadas encerradas e procedimentos de recuperação demonstrados.

Observe o teatro da aprovação. Se os revisores recebem cem páginas na sexta e um pedido de assinatura na segunda, a assinatura não prova nada. Revisões pequenas e baseadas em casos criam uma trilha útil e deixam a discordância aparecer cedo.

Remunere as pessoas pelo papel exigido pelo projeto e torne concreto o caminho após a virada. Algumas se tornarão responsáveis de domínio, analistas de produto, operadores de serviço, projetistas de testes ou líderes de modernização. Outras talvez escolham sair. Tratamento respeitoso não garante retenção, mas o desprezo quase garante que os alertas mais úteis cheguem tarde ou nunca.

Discordância é um sinal de risco

Quando dois especialistas descrevem a mesma regra de maneiras diferentes, não tire a média nem deixe o cargo mais alto vencer. A discordância costuma apontar para uma condição escondida: grupos de clientes, datas, regiões, canais de entrada ou estados de recuperação diferentes.

Escreva as duas afirmações no registro e peça a cada pessoa um caso em que sua versão se aplique. Compare esses casos com caminhos do código, configuração, histórico de dados, chamados e tráfego. O objetivo é encontrar o predicado que torna as duas versões coerentes ou provar que o sistema se comporta de forma inconsistente.

Suponha que um operador diga que um pagamento rejeitado pode ser repetido com segurança e outro diga que a repetição cria duplicatas. Os procedimentos podem divergir porque uma fila atribui um token de idempotência e um canal antigo não. Um teste genérico de «tentativas repetidas são seguras» esconderia o limite exato que a reescrita precisa impor.

Algumas disputas são de política, não de fatos. Produto quer uma substituição favorável ao cliente; compliance quer rejeição total; operações aplica um acordo manual. Código não resolve esse conflito. Nomeie o responsável, mostre consequências concretas e registre a decisão ao lado dos testes que ela altera.

O silêncio também é evidência. Uma área sem responsável confiante, tráfego recente ou exemplo repetível merece mais análise, não menos. Equipes costumam marcá-la como sem uso porque a exclusão facilita o plano. Verifique agendadores, logs de acesso, arquivos gerados, importações posteriores e procedimentos de calendário antes de desativá-la. Se as evidências continuarem fracas, isole a função atrás de um controle de virada e monitore a demanda, em vez de fingir certeza.

Acompanhe as discordâncias pendentes nos critérios de entrada em produção. Cada uma precisa de responsável, escopo afetado, alternativa segura e prazo. Uma migração pode avançar com incerteza conhecida se o raio de impacto estiver limitado e a reversão for real. Não deve avançar porque a incerteza caiu da pauta de uma reunião.

A parte social importa. Especialistas que temem ser culpados por cada divergência vão suavizar contradições. Revise o sistema, não a memória da pessoa. Recompense quem apresenta um contraexemplo problemático, porque esse exemplo custa menos antes da virada do que depois.

A ausência de especialistas muda o método

Se a pessoa que conhecia o sistema já saiu, a reescrita ainda pode prosseguir, mas a equipe deve substituir a lembrança por uma busca mais deliberada de evidências. Não nomeie o funcionário mais próximo como especialista universal. Isso produz respostas confiantes de alguém que só viu parte do sistema.

Comece pelos rastros de decisões. Chamados de incidentes mostram quais falhas importaram e quem participou. Solicitações de mudança explicam por que uma condição apareceu. Logs de lote e calendários de agendamento revelam trabalho dependente do tempo. Arquivos de conciliação mostram o que outro departamento considerava oficial. Modelos do suporte revelam erros recorrentes. O histórico do código pode identificar quem revisou um módulo mesmo que o autor original tenha saído.

Monte um mapa de testemunhas a partir desses rastros. Uma testemunha pode conhecer um limite estreito: o contador que recebe uma exportação, a equipe parceira que envia um arquivo, o analista de suporte que reconhece casos duplicados ou o engenheiro de infraestrutura que restaurou a última execução com falha. Pergunte a cada pessoa apenas sobre eventos que ela tratou diretamente. Vários relatos restritos são mais seguros do que uma grande narrativa emprestada.

Use o sistema antigo como objeto experimental quando houver segurança. Clone um estado semelhante à produção em ambiente isolado, varie uma entrada de cada vez e registre saídas e efeitos colaterais. Comece com casos recuperados dos logs e depois investigue limites visíveis em ramificações, tabelas de validação e tratamento de erros. Nunca execute transações exploratórias em fluxos financeiros, industriais ou de clientes ativos só porque a documentação é escassa.

A análise estática pode encontrar regras candidatas, mas não diz se uma ramificação é política atual, código morto ou um defeito antigo esperado por um consumidor. Marque as regras extraídas como não confirmadas até que tráfego, execução repetível ou responsável oficial as sustente. A ausência de uma pessoa torna os rótulos de confiança mais importantes.

Defina os controles da virada conforme a incerteza restante. Um relatório mal compreendido pode rodar em paralelo para um conjunto definido de eventos. Uma transação rara e irreversível pode exigir aprovação manual e caminho de reversão. Uma exportação aparentemente sem uso pode permanecer isolada e monitorada até passar seu gatilho de calendário. Esses controles custam tempo, mas expõem o custo honestamente.

Às vezes, a evidência nunca fica forte o bastante. A resposta responsável é uma exceção limitada com proprietário, método de detecção e procedimento de recuperação. Inventar certeza produz um relatório mais limpo e um incidente mais sujo. A falta de um especialista eleva o ônus da prova; não o elimina.

Defina a evidência mínima exigida para cada classe de risco antes do início dos testes, para que a pressão de entrega não reduza o limite depois.

A virada muda o trabalho, não a necessidade de julgamento

Depois da reescrita, os especialistas do sistema antigo não devem continuar como as únicas pessoas capazes de manter o negócio funcionando. O julgamento deles ainda importa, mas deve operar por meio de testes, decisões e procedimentos com responsáveis, não por chamadas de emergência.

Defina a transição antes da virada. Liste cada responsabilidade recorrente: aprovar exceções, conciliar saídas, atualizar dados de referência, reiniciar trabalhos, explicar relatórios e classificar defeitos. Nomeie o novo responsável, o material de apoio, uma data de demonstração e a condição de saída do antigo especialista. «Conhecimento transferido» não é condição. «O novo responsável concluiu duas conciliações representativas e recuperou um lote com falha durante um ensaio» é.

Faça ensaios operacionais com falhas realistas. Desative uma dependência, introduza uma mensagem duplicada, expire dados de referência e force um lote parcial. Os novos responsáveis devem diagnosticar e recuperar usando a nova observabilidade e os manuais enquanto o especialista antigo observa. Cada dica sussurrada vira depois uma verificação ou instrução ausente.

Mantenha os especialistas em um ciclo limitado de revisão durante a operação inicial, com caminhos claros e data final. Eles devem examinar novas falhas de paridade e questões de política, não aprovar mudanças comuns para sempre. Se todo problema de produção ainda chega até eles, a migração moveu código sem mover responsabilidade.

Retenha o ambiente antigo e suas evidências conforme as regras legais, operacionais e de dados. A equipe pode precisar reproduzir uma saída contestada ou explicar uma transação histórica. Isso não significa deixar um sistema sem manutenção conectado indefinidamente. Defina acesso, isolamento, retenção de dados e autoridade para executá-lo.

O teste final é a ausência. Os novos responsáveis conseguem operar um fechamento, recuperar uma falha, responder a uma pergunta do suporte e alterar uma regra documentada enquanto o antigo especialista está indisponível? Se não, identifique a evidência ausente e ensaie novamente.

Uma reescrita tem sucesso quando a organização consegue explicar seu comportamento sem folclore e mudá-lo sem convocar uma pessoa específica. Quem sustentou o sistema antigo merece mais do que uma entrevista cerimonial. Dê casos precisos para essas pessoas julgarem, registre as discordâncias encontradas e torne o conhecimento executável. A nova equipe fica com evidências em vez de histórias, e os especialistas deixam algo melhor do que um plantão permanente.