Builds reprodutíveis para bases de código herdadas: pare a deriva

Por que projetos herdados continuam quebrando entre máquinas

Bases de código herdadas costumam falhar da forma mais irritante: de modo inconsistente. Um desenvolvedor roda o app normalmente, outro recebe um erro críptico. O CI passa de manhã e falha à tarde. Uma pequena mudança que parece inofensiva é enviada e a produção se comporta diferente.

Essa deriva do tipo "funciona na minha máquina" significa que o código não é a única coisa que decide se o build vai ter sucesso. Diferenças escondidas entre notebooks, runners de CI e servidores de produção mudam o que é instalado, como roda e o que acaba sendo deployado.

A pior parte é a aleatoriedade. Você deixa de confiar nos testes porque eles ficam instáveis. Perde tempo perseguindo bugs que não consegue reproduzir. E começa a aplicar remendos arriscados (como travar uma dependência manualmente) só para destravar, o que pode gerar novas surpresas depois.

A maioria das causas é simples e consertável:

• Diferentes versões do Node.js (até diferenças de versão menor podem quebrar módulos nativos ou ferramentas)
• Lockfiles ausentes ou ignorados, fazendo com que as instalações puxem árvores de dependência ligeiramente diferentes
• Ferramentas globais (npm, yarn, pnpm, TypeScript, ESLint) diferentes por máquina
• Scripts de postinstall que se comportam diferente entre SOs ou shells
• Cache de CI que esconde problemas que um install limpo revelaria

O objetivo é direto: as mesmas entradas devem produzir a mesma saída em todo lugar. Mesma versão do Node, mesmo gerenciador de pacotes, mesma árvore de dependências, mesmas etapas de build, mesmos artefatos.

Quando você elimina a deriva, as falhas deixam de ser aleatórias. Quando algo quebra, quebra para todo mundo, no mesmo lugar, com o mesmo erro. É aí que um projeto herdado volta a ser mantível.

O que significa um build reprodutível em projetos Node

Um build reprodutível significa que você pode pegar o mesmo código, rodar os mesmos comandos e obter o mesmo resultado toda vez. Em projetos Node, esse "resultado" não é só "funciona no meu laptop" — deve se comportar igual para qualquer membro da equipe, no CI e em produção.

Se uma máquina usa Node 18 e outra Node 20, ou se uma instalação puxa pacotes mais novos que outra, você não tem realmente o mesmo projeto.

Num repositório Node saudável, isto deve ser consistente:

• Instalação: um clone limpo instala sem correções manuais
• Output do build: as mesmas fontes produzem artefatos funcionalmente idênticos
• Testes: a mesma execução de testes passa ou falha pelos mesmos motivos
• Scripts: npm run build (ou similar) se comporta igual em todo lugar
• Erros: quando algo quebra, quebra da mesma forma, não aleatoriamente

Algumas coisas não serão idênticas por design. Timestamps em bundles, caminhos específicos de máquina, variáveis de ambiente e chamadas a serviços externos podem introduzir ruído. A solução não é fingir que isso não existe. É tornar dependências, versões de ferramentas e passos de build determinísticos, e manter a configuração de runtime separada.

Geralmente você percebe que falta reprodutibilidade quando uma instalação limpa falha, ou quando o CI falha mas os laptops passam. Outro sinal forte é quando deletar node_modules muda o comportamento, ou quando dois colegas recebem versões diferentes da mesma dependência após rodar install.

Se você não consegue clonar o repositório em uma máquina nova e chegar a um build passando com um pequeno conjunto documentado de comandos, a deriva já começou.

Escolha uma única fonte de verdade para versões e scripts

Projetos herdados quebram porque as regras vivem na cabeça das pessoas. Um dev usa Node 18, o CI usa Node 20, a produção ainda está no 16, e ninguém percebe até uma dependência mudar de comportamento. Escolha um lugar no repositório onde a verdade esteja escrita e seja aplicada.

Comece decidindo onde as versões serão declaradas. Coloque em arquivos que viajam com o código, não em uma linha do README que vai virar obsoleta. Escolhas comuns são um arquivo de versão Node gerenciado pelo repositório, uma configuração do gerenciador de pacotes e (se usar containers) uma tag de imagem base que não seja flutuante.

Em seguida, concordem sobre os pontos de entrada do build. Todo mundo deve rodar os mesmos comandos para instalar, buildar e testar. Se houver múltiplas formas de build (scripts customizados, flags ad-hoc, pastas diferentes), a deriva volta.

Uma regra que funciona bem: se o CI não consegue rodar a partir de um checkout limpo usando os scripts do projeto, isso não faz parte do build.

Antes de mudar qualquer coisa, capture uma linha de base a partir de um estado limpo e documente: comando usado, versão do Node, gerenciador de pacotes e se os testes passam. Isso dá uma referência quando algo quebrar após você apertar as regras.

Trave versões do Node e do gerenciador de pacotes

A maioria dos bugs "funciona na minha máquina" começa antes do seu código rodar. Se uma pessoa está em Node 18, o CI em Node 20 e a produção em Node 16, você está testando três apps diferentes.

Trave o Node num lugar que os desenvolvedores realmente sigam. Um simples .nvmrc ou .node-version no repositório torna a versão esperada visível assim que alguém abre o projeto. Faça um backup em package.json para que ferramentas possam avisar (ou falhar) quando a versão estiver errada.

Depois, trave a versão do gerenciador de pacotes. Confiar no que estiver instalado globalmente (npm/yarn/pnpm) convida mudanças silenciosas na resolução de dependências. Trave isso no projeto para que todos instalem do mesmo jeito, em todo ambiente.

{
  "engines": {
    "node": ">=20 <21"
  },
  "packageManager": "[email protected]"
}

Adicione uma verificação rápida de versão que rode antes de installs ou testes. Ela deve falhar com uma mensagem clara, não um erro misterioso 10 minutos depois. Mantenha-a estrita:

• Verifique que node -v bate com a major version fixada
• Verifique que a versão do gerenciador de pacotes bate com packageManager
• Faça o CI falhar imediatamente se algum estiver errado

Aplique lockfiles e instalações determinísticas

Lockfiles são a diferença entre "nós todos instalamos dependências" e "nós todos instalamos as mesmas dependências." Essa mesmaidade é o que impede que quebras aleatórias aconteçam quando uma dependência transitiva lança um patch.

Primeiro, escolha um gerenciador de pacotes e comprometa-se com ele. Ferramentas mistas criam deriva silenciosa: uma pessoa roda npm, outra roda Yarn, o CI roda pnpm, e você acaba com árvores de dependência diferentes mesmo se package.json não mudou.

Limpe o repositório para que exista apenas um lockfile que corresponda à sua ferramenta escolhida (package-lock.json, yarn.lock ou pnpm-lock.yaml). Se vir mais de um, trate isso como bug, não preferência.

Use comandos de instalação que recusem surpresas

Instalações determinísticas falham rápido quando o lockfile e o package.json discordam. Isso é o que você quer.

# npm
npm ci

# Yarn (Berry)
yarn install --immutable

# pnpm
pnpm install --frozen-lockfile

Se a instalação falhar, corrija o lockfile corretamente em vez de afrouxar regras. O objetivo é parar mudanças ocultas.

Torne o lockfile obrigatório

Trate mudanças no lockfile como mudanças de código: revise-as e bloqueie merges que as esqueçam.

• O CI falha se package.json mudou mas o lockfile não
• O CI falha se o repositório contiver múltiplos lockfiles
• Revisores rejeitam "rodei install e ele atualizou um monte de coisas" sem motivo claro
• Atualizações de dependência são agrupadas e explicadas, não misturadas em PRs de feature

Faça o CI se comportar como uma máquina limpa

Muita deriva sobrevive porque laptops carregam estado escondido. O CI deve ser o oposto: uma máquina fresca, sempre, usando exatamente os mesmos passos de instalação e build que a equipe usa localmente.

Trate cada execução do CI como um checkout novo. Não confie em node_modules residuais, arquivos gerados ou ferramentas globais. Se o build só passa quando algo já existe, não é um build verdadeiro.

Mantenha um script como fonte de verdade. Se desenvolvedores rodam npm run build, o CI deve rodar exatamente esse script, não uma cadeia de comandos customizados.

Uma abordagem prática de CI:

• Fazer checkout em um workspace limpo a cada execução
• Instalar a partir do lockfile apenas (sem instalações "best effort")
• Rodar os mesmos scripts locais: lint, test, build
• Falhar quando algo importante estiver fora (conflitos de peer dependency, variáveis de ambiente faltando, erros de tipo)
• Salvar artefatos apenas depois do build bem-sucedido

Cache pode ajudar, mas também pode esconder problemas. Cacheie apenas o que é seguro reutilizar e invalide quando dependências mudarem.

• Cacheie o cache de download do gerenciador de pacotes (não node_modules)
• Use o hash do lockfile como chave do cache
• Estoure o cache quando a versão do Node.js ou do gerenciador de pacotes mudar

Alinhe a produção com o que o CI realmente buildou

Muitos bugs "funciona na minha máquina" aparecem após o deploy porque a produção não está rodando a mesma coisa que o CI testou. Trate o CI como onde a realidade é decidida e faça a produção casar com isso.

Primeiro, escolha onde os builds acontecem e mantenha essa escolha:

• Buildar no CI e fazer deploy do artefato/container pronto, ou
• Buildar na produção, mas então a produção deve usar exatamente o mesmo Node, gerenciador de pacotes e comandos de instalação que o CI

Misturar esses dois modos é como você obtém mudanças-surpresa nas dependências.

Se usar Docker, fixe a tag da imagem base em vez de usar uma tag flutuante. Uma pequena mudança na imagem base pode alterar Node, OpenSSL ou bibliotecas sistema e criar um "mesmo código, comportamento diferente" no deploy. Atualize a imagem base de propósito e deixe o CI testá-la.

Mantenha variáveis de ambiente separadas do output do build. Segredos e valores específicos do ambiente devem ser injetados em runtime, não incorporados em bundles compilados ou commitados em arquivos de config. Isso é tanto uma questão de segurança quanto de reprodutibilidade.

Por fim, verifique que o runtime em produção realmente bate com o que você travou. Se o CI usa Node 20, a produção não deve rodar silenciosamente Node 18.

Passo a passo: remover a deriva sem travar a equipe

A deriva normalmente começa pequena: alguém atualiza o Node, outro deleta o lockfile, o CI usa um comando diferente de instalação, e a produção puxa uma árvore de dependência ligeiramente diferente. Corrija em fases para não bloquear o trabalho diário.

Comece com uma linha de base, depois aperte as regras gradualmente:

• Capture a realidade atual: versão do Node, gerenciador de pacotes, comando de instalação e se há um lockfile e ele é de fato usado
• Escolha e trave versões esperadas: adicione um arquivo de versão do Node e trave a versão do gerenciador de pacotes para que todos usem as mesmas ferramentas
• Torne instalações determinísticas em todo lugar: atualize o CI para usar installs limpos e buildar a partir de um workspace limpo a cada execução
• Prove que funciona do zero: faça um teste de "fresh clone" em uma máquina nova ou pasta limpa e então build usando configurações parecidas com produção
• Aplique regras depois da validação: adicione checagens que falhem rápido (Node fora de versão, mudanças no lockfile ausentes) e proteja o lockfile contra edições casuais

Um padrão comum em protótipos herdados gerados por IA é que travar o Node e forçar installs congelados transforma uma falha aleatória em uma falha consistente e legível (dependência faltando, requisito de engine incompatível ou um script que só funcionava na máquina de uma pessoa). Uma vez consistente, é consertável.

Erros comuns que recriam o "funciona na minha máquina"

A maioria das equipes começa com boas intenções, depois pequenos atalhos trazem a deriva de volta. O objetivo é simples: o mesmo código deve buildar do mesmo jeito no laptop, no CI e na produção.

Uma armadilha comum é usar uma instalação "best effort" no CI. npm install pode atualizar o lockfile, puxar árvores de dependência ligeiramente diferentes ou se comportar diferente entre versões do npm. Assim você obtém um build verde localmente e um build vermelho no CI no dia seguinte.

Outro erro é tratar node_modules como parte do projeto. Comitar, cachear agressivamente ou assumir que já está presente esconde problemas reais de dependência. Então uma máquina limpa (ou um runner de CI limpo) vira o primeiro lugar onde os problemas aparecem.

Também: escolha um gerenciador de pacotes. Quando um repositório mistura artefatos de npm, Yarn e pnpm, pessoas vão "corrigir" um problema mudando comandos. Isso costuma funcionar uma vez, depois altera silenciosamente a árvore de dependências.

Os criadores de deriva que reaparecem sempre:

• CI usa uma instalação não determinística (por exemplo, atualizando o lockfile durante o build)
• O repositório depende de node_modules existente em vez de um install limpo
• Vários gerenciadores de pacotes são usados no mesmo repositório, com múltiplos lockfiles
• Builds dependem de CLIs globais (instalados na máquina de alguém, faltando no CI)
• Imagens Docker ou runtime não estão fixadas (por exemplo, usando latest)

Checklist rápido antes de confiar no build

Antes de gastar outro dia "consertando o CI", prove que o projeto consegue buildar do zero em uma máquina limpa. Se falhar lá, vai falhar em produção mais cedo ou mais tarde.

As 5 checagens que pegam a maior parte da deriva

Comece com um teste de fresh clone. Em um laptop novo ou numa pasta temporária limpa (sem node_modules antigos), rode install, build e testes exatamente como escrito no repositório. Se precisar de passos extras não documentados, você ainda não tem um build confiável.

Confirme versões. A versão do Node.js e do gerenciador de pacotes deve corresponder ao que o repositório espera, não ao que está instalado globalmente.

Cheque o lockfile. Deve haver exatamente um lockfile, ele deve estar commitado e só deve mudar quando você atualizar dependências intencionalmente.

Assegure que o CI instala de forma determinística. O CI deve usar o comando de clean-install da sua ferramenta (por exemplo npm ci em vez de npm install) para não reescrever silenciosamente o lockfile ou puxar pacotes transitivos mais novos.

Verifique que a produção corresponde ao que o CI buildou. A versão do Node em runtime na produção deve bater com a versão travada, e seu deploy deve enviar o mesmo output que o CI criou (não rebuildar do zero com um ambiente diferente).

Exemplo: estabilizando um protótipo herdado gerado por IA

Um fundador herda um app Node gerado por uma ferramenta de IA. Ele roda no laptop do desenvolvedor original, mas o CI falha com erros vagos como "Cannot find module", "Unsupported engine" ou testes que passam localmente e falham no CI.

Após uma checagem rápida, o padrão é familiar:

• Dev local está no Node 20, CI no Node 18 e produção ainda no Node 16
• Não há lockfile (ou ele está ignorado), então cada instalação puxa versões de dependências ligeiramente diferentes
• CI restaura dependências em cache, então nunca se comporta como uma máquina limpa

A correção não é sofisticada. É tornar o build determinístico e forçar todos os ambientes a segui-lo.

Trave Node.js (e o gerenciador de pacotes), adicione ou restaure o lockfile, mude o CI para modo estrito de instalação e rode ao menos um install frio localmente (delete node_modules, instale do zero) para provar que seu laptop não está mascarando problemas.

O resultado que você quer é chato: o mesmo commit produz a mesma árvore de dependência e o mesmo resultado de build em todo lugar.

Próximos passos se seu build herdado ainda estiver instável

Se você ainda vê bugs "funciona na minha máquina" após o básico, pare de mudar cinco coisas ao mesmo tempo. Padronize em uma ordem estrita: versões primeiro, lockfiles em segundo, depois regras de CI. Cada passo deve remover variáveis.

Escreva o que você vai tratar como verdade para este repositório: a versão do Node.js, o gerenciador de pacotes e sua versão, e o único comando de instalação que todos devem usar. Mantenha as regras pequenas e visíveis.

Se a base de código em si estiver bagunçada (especialmente protótipos gerados por IA), builds reprodutíveis são a primeira tarefa de reparo, não um item opcional. Até que os builds sejam previsíveis, todo outro conserto fica mais difícil de verificar.

Se precisar de ajuda rápida, FixMyMess (fixmymess.ai) se concentra em pegar apps gerados por IA quebrados e torná-los prontos para produção. Uma auditoria de código gratuita pode apontar de onde vem a deriva (versões, lockfiles, scripts ocultos) e então a equipe pode consertar o build e os problemas subjacentes em um único passo.