Remova constantes mágicas do código gerado por IA (com segurança)

Por que constantes mágicas atrapalham em código gerado por IA

Constantes mágicas são valores espalhados pelo código sem nome ou explicação. Parecem números fixos (como 7 ou 10000), URLs coladas (como um endpoint de API) ou strings que controlam comportamento silenciosamente (como "beta", "admin" ou "enabled"). Quando você as vê depois, não dá para saber por que o valor existe nem o que quebra se for alterado.

Protótipos gerados por IA pioram isso porque o código costuma ser produzido em pedaços pequenos e separados. Um componente recebe um timeout, outro recebe um timeout diferente, e um terceiro copia uma URL com um caminho levemente distinto. O app funciona bem o suficiente para demo, mas a mesma regra acaba implementada em vários lugares com pequenas diferenças.

Por isso remover constantes mágicas pode parecer arriscado. Um pedido simples como “aumentar limite de upload de 10MB para 25MB” vira uma caça por controllers, componentes de UI, helpers de validação e jobs em background. Se você perder um lugar, entrega um bug que só aparece em produção.

Você costuma ver os sintomas rápido:

• Comportamento inconsistente entre páginas (uma tela permite 25MB, outra bloqueia em 10MB)
• Correções que funcionam em um fluxo e falham em outro
• Testes difíceis de escrever porque as regras estão espalhadas
• Hotfixes que criam novos casos de borda conforme os valores divergem ao longo do tempo
• Relatos confusos de suporte (“às vezes funciona”) sem padrão claro

Um exemplo realista: seu app tem "https://api.example.com" codificado no fluxo de login, outro arquivo usa "https://api.example.com/" e um terceiro aponta para "https://staging-api.example.com" deixado de um prompt anterior. Você muda um, a autenticação ainda falha para alguns usuários, e agora está correndo atrás de fantasmas.

Este é um dos problemas mais comuns que vemos em apps quebrados gerados por IA na FixMyMess. O caminho mais rápido para mudanças seguras é tornar valores importantes entediantes: um nome, um lugar, uma fonte de verdade.

O que conta como constante mágica (e o que não conta)

Uma constante mágica é qualquer valor embutido no código cujo significado não é óbvio, e cujo ajuste posterior exige procurar por arquivos e adivinhar o que mais afeta. Em protótipos de IA, esse risco aumenta porque os mesmos valores costumam reaparecer em muitos arquivos.

O que é uma constante mágica?

Constantes mágicas aparecem como números mágicos, strings mágicas e URLs hardcoded. Frequentemente são “defaults importantes” que controlam comportamento silenciosamente.

Exemplos comuns:

• Timeouts como 3000 ou 30 (milissegundos ou segundos?)
• Tamanhos de paginação como 10, 20, 50
• Contagem de tentativas (retry) como 3 ou 5
• URLs base de API como https://api.example.com/v1
• Toggles de feature escondidos como strings "enableNewCheckout" = true

O problema não é que esses valores existam. O problema é que o código não explica o que significam. Seis semanas depois, 3000 parece um palpite, não uma decisão.

Por que “uma edição rápida” falha

Em protótipos gerados por IA, a mesma constante costuma ser copiada entre componentes, rotas e helpers. Você muda em um lugar, os testes passam, e então outra tela quebra porque estava usando uma cópia ligeiramente diferente.

Duplicatas ocultas são especialmente desagradáveis: timeout = 3000 em um arquivo, timeout = 3500 em outro, e timeoutMs = 3000 em outro lugar. A diferença pode ser intencional ou deriva acidental. De qualquer forma, agora você tem comportamento que depende de qual caminho o usuário acessa.

O que NÃO conta como constante mágica?

Nem todo literal precisa virar configuração. Alguns valores são aceitáveis inline porque são autoexplicativos e improváveis de mudar.

Bons exemplos não-mágicos:

• 0 ou 1 como contador simples de loop
• 404 ao retornar um status HTTP em um handler
• Um pequeno valor de espaçamento de UI claramente local a um componente

Uma regra útil: se mudar o valor deveria ser uma decisão deliberada de produto (limites, URLs, retries, gating), ele pertence a um lugar nomeado.

Uma forma simples de encontrar e priorizar o que consertar

A parte difícil não é a mudança em si. É escolher o que atacar primeiro para não criar novos bugs.

Comece com um inventário rápido. Use a busca do editor para procurar valores repetidos: a mesma URL, o mesmo timeout, o mesmo 10 ou 1000, a mesma string de status. Se um valor aparece em 5+ lugares, é um forte candidato. Se aparece em só 2 lugares mas toca em dinheiro ou login, também é candidato.

Foque no risco, não na perfeição. As constantes que mais prejudicam são as que podem quebrar produção ou criar problemas de segurança quando estão erradas.

Uma regra rápida de triagem

Separe o que você encontrou em “corrigir agora” e “corrigir depois”. “Corrigir agora” geralmente inclui:

• Autenticação e identidade: URLs OAuth, URLs de callback, tempo de vida de tokens, configurações de cookie
• Pagamentos e webhooks: endpoints de provedores, nomes de segredos de assinatura, atrasos de retry
• Rate limits e quotas: máximo de requisições, tamanho máximo de upload, tamanhos de paginação
• Timeouts e retries: valores de timeout de API, intervalos de jobs em background
• URLs externas base: qualquer coisa apontando para staging, localhost ou um servidor pessoal

Depois escolha um item e crie uma fonte única de verdade antes de mexer em vários arquivos. Código gerado por IA muitas vezes tem o mesmo valor em formas ligeiramente diferentes, e edições rápidas viram refatorações pela metade.

Nomeie para que qualquer pessoa entenda a intenção

Use nomes que expliquem a intenção. Evite CONST_1 ou DEFAULT_VALUE. Prefira AUTH_TOKEN_TTL_SECONDS ou PAYMENTS_WEBHOOK_BASE_URL. Coloque unidades no nome (segundos vs milissegundos) para que ninguém precise adivinhar.

Exemplo: se você encontra três URLs diferentes do Stripe e dois valores de timeout espalhados, crie PAYMENTS_WEBHOOK_URL e PAYMENTS_API_TIMEOUT_MS em um lugar só. Depois atualize os pontos de chamada um a um, verificando o comportamento a cada passo.

Se você herdou um protótipo quebrado de ferramentas como Bolt, v0, Cursor, Lovable ou Replit, este costuma ser o primeiro passo de limpeza que fazemos na FixMyMess: centralizar os valores arriscados e então fazer o resto das correções sobre algo estável.

Passo a passo: centralizar limites, URLs e timeouts

O objetivo é simples: colocar “coisas que mudam” em um só lugar com nomes claros, para que você possa atualizá-las sem caçar pelo codebase.

Uma maneira prática de fazer isso

Trate isto como uma série de pequenos edições seguras, não um grande rewrite.

1. Escolha uma casa óbvia para configuração. Crie um módulo único (ou arquivo) que todo o app importe, como config ou settings.

2. Adicione nomes legíveis e defaults. Prefira nomes que expliquem a intenção, não o tipo: API_BASE_URL, REQUEST_TIMEOUT_MS, MAX_UPLOAD_MB, PASSWORD_MIN_LENGTH. Use defaults seguros para que execuções locais não quebrem.

3. Substitua literais gradualmente. Escolha uma pasta ou feature, troque literais por valores de configuração, commit e continue. Passos pequenos são mais fáceis de revisar e desfazer.

4. Faça uma checagem leve após cada parte. Rode o app e navegue pelos pontos que tocou (login, upload, checkout). Se tiver testes, rode-os. O objetivo é feedback rápido.

5. Mantenha commits focados. Um commit para “centralizar timeouts”, outro para “centralizar URLs de API”. Isso facilita identificar erros unitários (segundos vs milissegundos).

Um exemplo mínimo que previne bugs futuros

Suponha que seu app chama https://api.example.com em cinco arquivos, e cada um usa um timeout diferente: 2000, 5000, 15_000. Depois de centralizar, você define API_BASE_URL e REQUEST_TIMEOUT_MS uma vez. Na próxima vez que trocar para um servidor de staging ou precisar de timeouts maiores no pico, você muda um arquivo, não cinco.

Onde guardar a configuração: env vars, arquivos de config e defaults

Depois de extrair valores do código, você precisa de um lar claro para eles. O objetivo: uma fonte de verdade fácil de mudar e segura para deploy.

O que vai em env vars vs defaults no código

Variáveis de ambiente são melhores para valores que mudam entre ambientes ou não deveriam viver no repositório. Defaults no código são bons para valores não sensíveis que tornam a configuração local simples.

Uma divisão prática:

• Variáveis de ambiente: chaves de API, segredos de autenticação, URLs de banco, endpoints privados de serviço, segredos de webhooks de terceiros
• Arquivos de configuração (no repo): configurações não-secretas como disponibilidade de features, URLs públicas conhecidas, defaults de paginação, contagens de retry
• Defaults no código: valores fallback que mantêm o app funcionando se uma configuração estiver faltando (nunca para segredos)

Se um valor pode quebrar produção ou expor dados, prefira env vars. Se for um default sensato (como PAGE_SIZE=20), um default em código é aceitável.

Lidar com local, staging e produção sem surpresas

Muitos protótipos gerados por IA acidentalmente hardcodam “o único ambiente” que o desenvolvedor testou. Em vez disso, torne a configuração dependente do ambiente: local usa variáveis do shell local (ou um arquivo .env local), staging usa suas próprias configurações de deploy, produção usa segredos mais fechados.

Mantenha regras previsíveis:

• Mesmas chaves de configuração em todos os lugares (só os valores mudam)
• Falhar rápido se segredos obrigatórios estiverem faltando em staging/produção
• Permitir defaults apenas para valores não sensíveis

Por exemplo, você pode permitir REQUEST_TIMEOUT_MS=8000 por default localmente, mas exigir DATABASE_URL e JWT_SECRET antes do app subir em staging ou produção.

Não misture carregamento de config com lógica do app

Um erro comum é espalhar leituras de process.env... pelo código. Isso transforma configuração em lógica oculta do app.

Em vez disso, carregue e valide a configuração uma vez na inicialização (num módulo só), e passe o config para as partes do app que precisam.

Toggles de feature que não viram bagunça

Toggles são switches simples on/off que permitem entregar código sem forçar todos os usuários a verem a novidade na mesma hora. Em código gerado por IA, toggles muitas vezes aparecem como booleanos aleatórios espalhados, que são outro tipo de constante mágica.

Um bom toggle responde a uma pergunta clara: “Os usuários devem ver X?” Para rollouts arriscados, isso é útil. Você pode liberar um novo fluxo de signup para uma fatia pequena de usuários, ou manter uma nova página de preços oculta até aprovação. O importante é que virar o toggle mude comportamento sem editar múltiplos arquivos sob pressão.

Nome e estrutura que continuam legíveis

Escolha um estilo de nome consistente e mantenha-o. Descritivo vence curto. enableNewSignupFlow é melhor que flag2 porque qualquer um pode adivinhar o que faz durante um hotfix.

Mantenha toggles em um só lugar (seu módulo de config ou arquivo de settings). Se o valor precisa variar por ambiente, mapeie para uma variável de ambiente, mas exponha pelo mesmo objeto de configuração para que o resto do app não se importe de onde veio.

Algumas regras para evitar proliferação de toggles:

• Prefira nomes enableX ou useX que descrevam o comportamento visível ao usuário
• Um toggle por feature, não por arquivo
• Adicione data de expiração ou nota de remoção para toggles temporários
• Default para “off” em mudanças arriscadas

Decida quem pode virar a chave

Toggles podem causar dano real se qualquer pessoa os mudar sem revisão. Defina quem pode alterá-los e como as mudanças são revisadas.

Exemplo: seu app gerado por IA tem uma nova página de checkout atrás de um toggle. Um stakeholder pede para desligar depois de um pico de tickets. Se o toggle estiver centralizado, você o inverte em um lugar e tem confiança de que não deixou uma cópia do mesmo boolean em outro arquivo.

Um exemplo realista: uma mudança, um lugar

Imagine uma startup que lançou um protótipo gerado por IA rápido. Funciona em demos, mas o código tem os mesmos valores copiados por todo lado: URLs de API, timeouts, limites e um switch “novo checkout”.

Antes: mudança pequena, muitas edições arriscadas

Você precisa apontar o app de uma API de staging para produção. Procura por https://api-staging... e encontra em seis arquivos: chamadas fetch do frontend, um cliente backend, um handler de webhook e um job em background. Você muda tudo, faz o deploy, e depois descobre que um arquivo ainda aponta para staging. Metade do app lê dados antigos silenciosamente.

Então o tráfego real chega. Seu rate limit precisa ir de 10 para 50 requisições por minuto, e um timeout precisa ir de 2s para 8s. Esses números estão espalhados, e um lugar usa milissegundos enquanto outro usa segundos. Um ajuste simples vira jogo de adivinhação.

Por fim, erros disparam em uma feature nova. O código de IA adicionou ENABLE_NEW_CHECKOUT = true em dois módulos diferentes. Você muda um para false, mas usuários ainda veem o caminho quebrado porque o outro constante ainda está true.

Assim costuma ser o padrão bagunçado:

// auth.js
const API_BASE_URL = "https://api-staging.example.com";

// orders.js
fetch("https://api-staging.example.com/orders", { timeout: 2000 });

// worker.js
const TIMEOUT_MS = 2000;
const RATE_LIMIT = 10;

// checkout.js
const ENABLE_NEW_CHECKOUT = true;

Depois: uma atualização, um lugar

Ao centralizar, o resto do app importa de um único módulo de config (e usa variáveis de ambiente quando faz sentido).

// config.js
export const config = {
  apiBaseUrl: process.env.API_BASE_URL ?? "https://api.example.com",
  timeoutMs: Number(process.env.TIMEOUT_MS ?? 8000),
  rateLimitPerMin: Number(process.env.RATE_LIMIT ?? 50),
  features: {
    newCheckout: process.env.FEATURE_NEW_CHECKOUT === "true",
  },
};

// orders.js
fetch(`${config.apiBaseUrl}/orders`, { timeout: config.timeoutMs });

Agora “mudar a API base” significa atualizar uma variável de ambiente, não editar metade do código. “Aumentar o timeout” é trocar um número com uma unidade clara. “Desabilitar a nova feature” é inverter um único flag quando algo quebra.

Erros comuns e armadilhas a evitar

O objetivo é segurança: menos edições arriscadas, menos surpresas, mudanças mais fáceis. A maioria dos problemas acontece quando a refatoração parece arrumada, mas o comportamento muda silenciosamente.

Uma escorregada comum é renomear uma constante e esquecer alguns usos. Isso aparece muito em projetos escritos por IA onde o mesmo valor está duplicado sob nomes ligeiramente diferentes. O app ainda compila, mas um limite, URL ou timeout fica inconsistente.

Múltiplos arquivos de config são outra armadilha. Começa como “um para servidor, um para cliente” e cresce para três ou quatro arquivos que divergem. Quando um valor muda, metade da equipe atualiza o arquivo A e esquece do arquivo B.

Também cuidado com defaults “úteis” que silenciosamente sobrescrevem variáveis de ambiente. Defaults são ok, mas só se óbvios e seguros. Se seu código faz “use ENV se presente, caso contrário use essa URL de produção hardcoded”, você pode fazer um build que fale com o backend errado.

Erros que mais mordem:

• Renomear constantes sem atualizar cada import/uso, deixando comportamento dividido
• Criar várias fontes de config (arquivos múltiplos, padrões diferentes) que se distanciam com o tempo
• Valores fallback hardcoded que silenciosamente vencem env vars, especialmente em builds de produção
• Tratar segredos como constantes normais (chaves de API em arquivos de constantes, cometer .env)
• Sobre-abstrair cedo com camadas de config que ninguém entende durante um incidente

Se você herdou um protótipo gerado por IA e não tem certeza se sua refatoração mudou comportamento, isso é exatamente o que a FixMyMess audita: duplicatas ocultas, defaults inseguros e segredos misturados em arquivos de constantes.

Checklist rápido antes de enviar a refatoração

Depois de centralizar constantes, o app pode parecer mais limpo mas ainda esconder falhas arriscadas. Use este check rápido antes de fazer merge.

Checagem de sanidade de configuração

Faça um teste de “mudança única”. Escolha um valor que você espera alterar no futuro (como a URL base da API), atualize-o uma vez e confirme que o app usa o novo valor em todo lugar. Se você ainda precisar caçar em vários arquivos, não centralizou de verdade.

Também confirme que segredos não estão misturados com configurações normais. Seu config pode incluir defaults seguros, mas qualquer coisa sensível (chaves de API, senhas de banco, segredos JWT) deve vir apenas de variáveis de ambiente. Se um segredo está no repo, assuma que vai vazar mais cedo ou mais tarde.

Um checklist pré-ship rápido:

• Mude uma configuração-chave (API base URL, webhook URL ou host CDN) em um lugar e verifique que todo o app segue essa mudança.
• Procure literais restantes que deveriam ser nomeados (timeouts como 30000, limites como 50, contagens de retry como 3).
• Confirme que limites e timeouts têm nomes claros e um comentário curto explicando (o que protege e por que esse número).
• Confirme que toggles de feature têm um responsável, default seguro e plano de remoção se forem temporários.
• Rode um smoke test: faça login, acesse as telas principais e dispare pelo menos um fluxo de erro (senha errada, registro ausente, modo offline).

Checagem final “quebrar vidro”

Durante o smoke test, olhe os logs ou o console. Se ver varável de ambiente faltando, uma URL de fallback inesperada ou um toggle no estado errado, corrija antes de enviar.

Se você herdou um protótipo frágil gerado por IA e não sabe o que mais está hardcoded ou inseguro, a FixMyMess (fixmymess.ai) pode começar com uma auditoria de código gratuita para apontar constantes arriscadas, segredos expostos e padrões de configuração que tendem a falhar em produção.

Próximos passos: manter isso limpo conforme o app cresce

A vitória real é impedir que constantes mágicas voltem a aparecer. Times pequenos se movem rápido, e “só mais um número hardcoded” é como você volta a ter edições espalhadas e arriscadas.

Um próximo passo prático é um sprint curto de limpeza focado nas constantes que realmente te prejudicam. Não tente consertar tudo. Escolha os 10–20 valores que mudam com frequência ou podem quebrar produção quando errados (timeouts, rate limits, URLs base, limites de preço, tamanhos de upload), centralize-os e envie em pequenos lotes.

Faça uma regra leve de time: novos valores importantes precisam de um nome e um lugar. Se não for claramente um caso único (como índice de loop), pertence ao seu módulo de config ou constants.

Se seu codebase foi gerado por IA e parece frágil, uma auditoria especializada antes de refatorações mais profundas pode economizar muito tempo. Esses projetos frequentemente escondem constantes arriscadas junto com problemas maiores como segredos expostos, fluxos de autenticação quebrados ou queries de banco inseguras.