Feature flags para protótipos quebrados: entregar correções sem caos

Por que protótipos quebram quando você tenta enviar correções

Um “protótipo quebrado” raramente é um único bug. É uma pilha de pequenas suposições que nunca foram testadas em conjunto: valores codificados, telas meio prontas, tratamento de erro faltando e atalhos “temporários” que silenciosamente viraram produto.

Na prática, fica assim: o app funciona no laptop do criador, mas falha após um deploy. Um usuário consegue entrar, outro fica preso. Pagamentos funcionam no sandbox, mas não em produção. Uma pequena mudança em um lugar derruba algo aparentemente não relacionado.

Correções em grande escala continuam falhando porque mudam tudo de uma vez. Ao reescrever um fluxo de ponta a ponta, você também reescreve todos os efeitos colaterais desconhecidos. Se a base de código estiver bagunçada, não há um lugar seguro para ficar enquanto você faz a alteração.

Os incidentes geralmente vêm de caminhos de código arriscados que você não percebe até que usuários reais os atinjam. Exemplos incluem:

• Um ramo de “fallback” que roda apenas quando um serviço de terceiros está lento
• Uma função de usuário raramente usada (admin, convidado) com permissões diferentes
• Uma tela só para mobile com chamada de API diferente
• Um job em segundo plano que tenta de novo e duplica ações
• Uma dependência oculta em variáveis de ambiente ou segredos

“Estabilizar primeiro” significa tornar o app previsível antes de adicionar novas funcionalidades. O objetivo é mudanças menores e controladas, menos surpresas e recuperação mais rápida quando algo dá errado. É aí que feature flags para protótipos quebrados começam a importar: você pode isolar as partes arriscadas, enviar correções parciais com segurança e evitar reverter todo o lançamento.

Se você herdou um protótipo gerado por IA (Lovable, Bolt, v0, Cursor, Replit) e cada correção parece uma aposta, a FixMyMess pode rodar uma auditoria de código gratuita para mapear os caminhos de maior risco antes de você começar a alterá‑los.

Feature flags, explicadas sem jargão

Uma feature flag é um simples interruptor on/off ao redor de um pedaço do código. Você envia o código, mas decide quem pode usá‑lo (ou se alguém pode usar ainda). Isso permite avançar mesmo quando o protótipo é instável, porque você isola caminhos arriscados em vez de apostar todo o app em uma única mudança.

Para protótipos quebrados, pense nas flags como trilhos de segurança. Elas ajudam a liberar correções parciais, testar em produção com um grupo pequeno e reverter rápido se algo der errado.

Flags protegem de alguns problemas, mas não de todos. São ótimas quando uma mudança pode quebrar um fluxo, sobrecarregar o banco de dados ou acionar casos de borda ruins. Elas não consertam bugs sozinhas e não substituem bom monitoramento ou testes.

Aqui estão tipos comuns de flag que você ouvirá falar:

• Flags de release: escondem uma nova funcionalidade até você estar pronto para disponibilizá‑la.
• Flags de ops: mudam comportamento por estabilidade (limites de taxa, cache, tentativas).
• Kill switches: desligam uma funcionalidade que está falhando instantaneamente, sem rollback completo.

Também ajuda saber o que flags não são. Elas são diferentes de configuração, branches e hotfixes rápidos.

• Config define valores estáveis (como timeouts). Uma flag é um interruptor temporário enquanto você aprende.
• Branches mantêm código fora da produção. Flags deixam você enviar código com segurança e controlar exposição.
• Hotfixes corrigem produção rápido. Um kill switch pode te dar tempo enquanto você constrói a correção real.

Um exemplo simples: sua página de login às vezes entra em loop após redefinição de senha. Você pode adicionar uma flag que mantém o fluxo antigo de reset para a maioria dos usuários, enquanto um pequeno grupo interno testa o novo fluxo. Times como a FixMyMess costumam usar essa abordagem ao reparar protótipos gerados por IA, porque reduz deploys arriscados do tipo tudo-ou-nada.

Decida o que colocar atrás de uma flag primeiro

O ponto de uma flag não é esconder trabalho inacabado. É reduzir a área de impacto quando você mexe em um protótipo frágil. Se você flagar a coisa certa, pode enviar uma build mais segura mesmo quando só parte da correção está pronta.

Comece circulando as áreas onde um pequeno bug causa uma grande bagunça. Na maioria dos protótipos, isso é autenticação, pagamentos, qualquer coisa que escreva no banco de dados e qualquer mudança de formato de dados (como migrations). Esses caminhos podem bloquear usuários, cobrar errado ou corromper registros.

Escolha o limite que corresponde ao risco

Um erro comum é flagar uma funcionalidade inteira quando só um ramo é perigoso. Se o problema é uma nova regra de preços, não flague toda a página de checkout. Flageie o cálculo de preço ou a chamada final de “cobrar”. Limites menores são mais fáceis de entender e remover depois.

Use este filtro rápido para decidir o que merece uma flag:

• Afeta login, acesso, cobrança ou gravações permanentes de dados
• É difícil reverter limpo depois que roda (migrations, jobs em background)
• Você precisa enviar correções parciais enquanto continua investigando
• Uma falha seria visível para muitos usuários ao mesmo tempo
• Você não tem confiança de testar todos os casos de borda hoje

Esconder ou degradar graciosamente

Algumas coisas devem ficar totalmente escondidas até estarem seguras (por exemplo, um novo fluxo de pagamento). Outras podem degradar sem drama. Um bom padrão é “novo caminho se habilitado, caso contrário use o caminho antigo”, com um fallback claro se o novo caminho falhar.

Exemplo: você está consertando um login instável. Pode flagar apenas a nova lógica de refresh de token. Se ela falhar, os usuários ainda entram pelo método antigo, e você continua coletando erros sem quebrar todo mundo.

Times que usam feature flags para protótipos quebrados frequentemente descobrem que o problema real é mais profundo do que um bug. Quando a FixMyMess audita código gerado por IA, geralmente flagamos primeiro os caminhos de auth ou gravação de dados de maior risco para que as correções possam ser enviadas com segurança enquanto a limpeza mais profunda acontece.

Um jeito simples passo a passo para adicionar sua primeira flag

Quando um protótipo está instável, sua primeira flag deve ter um trabalho claro. Escolha o maior risco que você pode reduzir hoje: parar crashes, evitar gravações ruins no banco ou evitar vazamento de dados. Se tentar “flagrar tudo”, você perde o controle rápido.

Comece pequeno e trate a flag como um interruptor de segurança que você pode acionar sem drama. Essa é a ideia central: enviar uma correção parcial, manter o app utilizável e evitar rollbacks de emergência.

Fluxo da primeira flag

Escreva o nome da flag para que qualquer um adivinhe o que ela faz e acrescente uma nota de uma frase dizendo por que ela existe e o que significa “seguro”.

• Escolha um comportamento arriscado para controlar (exemplo: “novo caminho de gravação do checkout”).
• Nomeie a flag claramente (exemplo: checkout_write_v2_enabled) e adicione uma intenção de uma linha: “Evita cobranças duplicadas mantendo v1 como padrão.”
• Envolva um ponto de entrada primeiro (uma rota, clique de botão, handler de API ou job em background), não um helper interno profundo.
• Faça “flag off” a opção mais segura, mesmo que seja mais lenta ou menos elegante.
• Adicione uma forma rápida de desligá‑la imediatamente (config, toggle admin, env var) e confirme que funciona.

Onde as pessoas emperram

A maioria das equipes coloca a flag muito profundamente no código. Aí você perde metade das chamadas e o caminho arriscado continua rodando. Se envolver o ponto de entrada, você controla todo o fluxo com um único interruptor.

Exemplo simples: seu job “Import CSV” às vezes grava linhas vazias. Coloque a flag no início do job. Se a flag estiver off, execute a importação antiga ou bloqueie imports com uma mensagem clara. Esse padrão pode parecer rígido, mas previne dados ruins.

Se você herdou código gerado por IA que se comporta de forma imprevisível, a FixMyMess costuma começar adicionando um pequeno conjunto de flags de segurança nesses pontos de entrada para que você possa enviar correções sem quebrar produção novamente.

Padrões de rollout que evitam surpresas

A maioria dos rollouts falha pela mesma razão: você muda demais, para muitas pessoas, rápido demais. Com feature flags para protótipos quebrados, o objetivo é o oposto. Faça uma pequena mudança, exponha‑a a um grupo minúsculo e mantenha uma saída instantânea.

Default-off vs default-on

Use default‑off quando o novo caminho pode crashar, afetar dinheiro ou tocar auth, billing ou gravações de dados. Isso permite enviar o código em segurança e escolher quando ligar.

Use default‑on quando o caminho antigo é o arriscado e você precisa de uma linha de base mais segura imediatamente. Nesse caso, mantenha o comportamento antigo atrás de uma flag para poder reverter temporariamente se aparecer uma dependência oculta.

Alguns padrões de rollout que reduzem surpresas:

• Envie default‑off, então habilite somente para seu time (ou um pequeno grupo interno) por um dia.
• Expanda para uma pequena fatia de usuários reais primeiro, como 1 a 5 por cento, e acompanhe mensagens de suporte e logs de erro.
• Aumente a exposição em etapas (5 → 20 → 50 → 100%) somente depois do app se manter estável por um ciclo de negócio completo.
• Use regras de segmentação: só novos usuários, só um tipo de conta ou só uma região, para limitar a área de impacto.
• Mantenha um kill switch que desliga o novo código imediatamente sem redeploy.

O kill switch importa mais quando você conserta código bagunçado gerado por IA. Se uma mudança toca login ou pagamentos, ter uma via rápida de rollback pode ser a diferença entre uma hora ruim e uma semana perdida.

Exemplo realista: você reconstrói uma etapa de validação de checkout instável. Habilite para contas de teste internas, então para 2% dos usuários. Se a taxa de erro ou falhas de cobrança subir, você aciona o kill switch e volta ao fluxo antigo em segundos, não depois de um hotfix desesperado.

Times que trabalham com a FixMyMess geralmente juntam isso com uma auditoria rápida dos caminhos de risco antes de começar a flagar, para saber por onde começar.

Adicione o monitoramento certo para que flags realmente reduzam rollbacks

Uma feature flag só ajuda se você puder responder rápido a uma pergunta: ligar a flag melhorou ou piorou as coisas? Sem isso, você acaba chutando e revertendo o release inteiro.

Comece registrando cada vez que o app avalia uma flag. Mantenha isso simples e seguro. Queremos contexto suficiente para depurar, mas nada que exponha usuários ou segredos.

Registre o mesmo conjunto pequeno de campos sempre:

• Nome da flag e variante (on/off, ou qual opção)
• Um ID de requisição ou sessão (não um e‑mail, não um perfil completo)
• A rota ou ação (por exemplo, /login, create-invoice)
• Códigos de resultado e tempo (status, timeout, duração)
• Uma tag curta de erro (como "db_timeout"), não a stack trace completa no cliente

Então divida suas métricas pelo estado da flag. Acompanhe taxa de erro, requisições falhas e timeouts com a flag on vs off. Se erros subirem só quando a flag está on, você tem prova e pode desligá‑la em minutos em vez de reverter todo o deploy.

Adicione sinais de saúde simples para os fluxos que mais doem quando quebram. Para login, isso pode ser: tentativas de login, logins bem‑sucedidos e tempo até a primeira página após login. Para checkout: tentativas de pagamento, pagamentos bem‑sucedidos e abandonos na confirmação.

Decida sua regra de “desligar” antes de habilitar a flag. Exemplo: “Se a taxa de sucesso de login cair 2% por 10 minutos, ou se os timeouts dobraram, desabilite a flag e investigue.” Decidir isso antes remove debates durante um incidente.

Isso é especialmente útil com protótipos quebrados onde correções tocam áreas frágeis como auth ou chamadas ao banco. Se você trouxer um projeto para a FixMyMess, este é um dos primeiros trilhos de segurança que adicionamos para que correções parciais possam ser enviadas com segurança enquanto a limpeza contínua acontece.

Testando ambos os caminhos sem dobrar sua carga de trabalho

Quando você adiciona flags, cria dois comportamentos: flag off (baseline segura) e flag on (a nova correção). O objetivo não é dobrar todos os testes. É garantir que nenhum dos caminhos apodreça silenciosamente.

Para protótipos quebrados, comece decidindo qual caminho é o “contrato”. A maioria trata flag off como o contrato até o rollout estar completo. Isso significa que seus testes principais devem passar sempre com a flag off, mesmo semanas depois.

Uma divisão prática de testes que se mantém pequena

Mantenha uma suíte principal no estado padrão (geralmente flag off) a cada push, então adicione um conjunto enxuto de testes que rodem com a flag on. Foque os testes com flag on apenas onde o comportamento muda.

Um approach simples que funciona bem:

• Rode sua suíte completa de smoke com a flag off em todo push.
• Adicione 3 a 5 testes focados com a flag on, cobrindo telas ou chamadas de API alteradas.
• Adicione um teste “guard” que falha se a flag estiver faltando ou renomeada (previne drift silencioso).
• Torne o valor da flag explícito nos testes (configure‑o no setup do teste), nunca “o que quer que meu laptop tenha”.

Esse último ponto importa. Muitos testes ficam instáveis porque um dev alternou uma flag localmente, esqueceu, e o teste passou a depender desse estado escondido.

Prevenir flag drift (o caminho esquecido)

Flag drift é quando ninguém lembra do caminho off, então ele quebra e você não pode reverter com segurança. Uma solução rápida é rodar um cheque agendado (diário ou antes do release) que inicia o app com a flag off e faz uma verificação de sanidade curta: login, um fluxo chave e logout.

Exemplo: se você conserta um login instável, mantenha um teste automatizado que verifica o login antigo com a flag off e outro que verifica o novo login com a flag on. Quando a FixMyMess audita uma base de código e encontra auth quebrado, esse cheque de “duas vias” costuma ser a forma mais rápida de parar rollbacks de emergência enquanto o problema raiz é corrigido.

Erros comuns que fazem feature flags sabotarem você

Feature flags podem acalmar um release bagunçado, mas também adicionar outra camada de caos. A maioria dos problemas vem de tratar flags como solução permanente em vez de um interruptor temporário.

A primeira armadilha é dívida de flag: você envia uma flag, as coisas estabilizam e ninguém a remove. Semanas depois você tem duas versões do mesmo comportamento e toda nova mudança precisa funcionar nos dois caminhos. A base de código vira um labirinto.

Outro problema comum é colocar flags muito profundas no código. Quando cada função checa uma flag, a lógica fica difícil de ler e fácil de quebrar. Um padrão melhor é fazer a guarda em um limite claro (rota, controller, ponto de entrada do serviço) para manter o restante do código limpo.

Flags também são usadas indevidamente para mascarar trabalho arriscado com dados. Uma flag serve para comportamento de leitura, UI ou lógica alternativa. É uma má bandagem para migrations quebradas, gravações inseguras ou “vamos consertar o banco depois”. Se ambos os caminhos gravam dados de forma diferente, reverter pode deixar o estado misto e confuso.

Erros a detectar cedo ao usar feature flags em protótipos quebrados:

• Deixar flags para sempre, tornando a complexidade permanente
• Espalhar lógica em ramos pequenos e com flags por muitos arquivos
• Flagrar gravações e migrations sem um plano seguro de rollback
• Esquecer um dono e uma data para remover a flag
• Armazenar flags de forma que exponha segredos ou controle admin inseguro

Como manter flags seguras

Mantenha controles de flag no lado do servidor, restrinja quem pode mudá‑las e nunca mande toggles “admin” no cliente. Se seu protótipo veio de ferramentas de IA e já tem chaves expostas ou auth frágil, trate o gerenciamento de flags como acesso de produção.

Uma regra prática: toda flag deve vir com um plano de saída (quando será deletada) e um plano de verificação (qual sinal prova que está seguro). Times como a FixMyMess costumam estabilizar o caminho com flag primeiro e depois remover o caminho antigo totalmente para que a correção realmente fixe o problema.

Checklist rápido antes de ligar uma flag

Antes de acionar uma feature flag, trate isso como trocar um fusível numa casa bagunçada. Você quer um interruptor, um circuito claro e um fallback seguro se algo faíscar.

Use este checklist curto para pegar os problemas que normalmente causam rollbacks noturnos ao usar feature flags para protótipos quebrados.

• Um ponto de entrada: A mudança arriscada deve ficar atrás de uma decisão única e óbvia (por exemplo, um controller ou método de serviço). Se o novo código vazar para helpers aleatórios, você não saberá o que está realmente ativo.
• Padrão seguro: Quando a flag estiver off, o app deve se comportar de forma previsível e conhecida. Se o “off” ainda chama código novo ou retorna formatos meio‑novos, você não criou uma rede de segurança real.
• Desligamento rápido: Garanta que pode desabilitar a flag sem redeploy. Se a única forma de desligar é um novo build, não é um freio de emergência.
• Verificação end‑to‑end para ambos os caminhos: Rode um fluxo real com a flag off e outro com a flag on (login, checkout, o que importa). Testes unitários ajudam, mas não pegam redirects quebrados, variáveis de ambiente faltando ou respostas de API incompatíveis.
• Propriedade clara e auditoria: Decida quem pode mudar a flag, onde isso é feito e como fica logado. Se qualquer um pode flipar a partir de uma tela admin escondida, espere surpresas.

Exemplo: se você troca de provedor de auth, mantenha a decisão no handler “start login”, padrão para o provedor antigo e verifique o ciclo completo de sign‑in e logout em ambos os modos.

Se seu protótipo já é imprevisível, uma revisão externa curta pode economizar tempo. A FixMyMess costuma ver flags adicionadas em três lugares sem padrão de segurança, o que torna as falhas mais difíceis de desfazer do que o bug original.

Exemplo realista: estabilizando um login instável

Você tem um protótipo onde o login parece OK em dev, mas usuários em produção têm falhas aleatórias. Às vezes o cookie de sessão não persiste. Às vezes o callback bate na URL errada. Mensagens de suporte se acumulam porque as pessoas não conseguem entrar, e cada “correção rápida” arrisca quebrar tudo para todo mundo.

Em vez de substituir todo o sistema de auth de uma vez, você adiciona uma feature flag que controla qual caminho roda: fluxo atual (old) ou fluxo novo (new). O caminho antigo fica como fallback enquanto você testa o novo com segurança. Esse é o lado prático de feature flags para protótipos quebrados: você entrega progresso sem apostar tudo em um único deploy.

Como o rollout aparece

Primeiro, você conecta a flag em um ponto de decisão (por exemplo, antes do app trocar um auth code por uma sessão). Se a flag estiver OFF, usa o código de troca antigo. Se ON, usa o novo.

Depois, você libera em passos pequenos:

• Usuários internos apenas (seu time, contas de teste ou allowlist escondida)
• 5% dos usuários reais
• 25% dos usuários reais
• 100% quando estiver chato e estável

Se você ver um pico de erros de login, desliga o kill switch OFF. Isso força todo mundo de volta ao caminho antigo sem rollback ou corrida por hotfix.

Quando está “pronto”

Uma flag não está pronta quando chega a 100%. Está pronta quando você pode deletá‑la.

Você termina quando:

• A taxa de sucesso de login se mantém estável por dias (não horas)
• Logs de erro não mostram picos novos relacionados a auth após as etapas do rollout
• Tickets de suporte sobre login caem a quase zero
• O caminho antigo é removido e o código da flag é deletado

Times frequentemente param em “agora funciona” e mantêm os dois caminhos para sempre. Se você herdou uma base gerada por IA (o tipo que a FixMyMess vê muito), marque um prazo para remover o fallback. Assim você evita transformar uma ferramenta de segurança em complexidade permanente.

Próximos passos: estabilize, depois limpe e envie com confiança

Se quiser que feature flags para protótipos quebrados realmente comprem tempo, mantenha‑as focalizadas. Escolha os poucos pontos onde falhas doem mais e deixe esses mais seguros primeiro.

Comece anotando seus três principais fluxos de usuário de risco. Pense no que causa pings de suporte e rollbacks de emergência: login, checkout, salvar configurações ou qualquer coisa que toque cobrança. Adicione flags só ao redor das partes arriscadas desses fluxos, não em páginas inteiras ou serviços completos.

Depois trate cada flag como um gesso temporário, não uma funcionalidade permanente. Dê a cada uma uma data clara de remoção e um responsável. Quando a correção estiver estável e totalmente implantada, delete a flag e o código do caminho antigo. Deixar flags para sempre é como protótipos viram sistemas confusos e frágeis.

Se seu protótipo foi gerado por IA, faça uma auditoria rápida de risco antes de expandir o rollout. Os problemas frequentemente ficam ocultos até que usuários reais apareçam.

Aqui está um checklist simples que você pode copiar para suas notas:

• Identificar os 3 fluxos mais propensos a gerar rollback
• Adicionar uma flag apenas no ponto de decisão que separa lógica antiga vs nova
• Definir data de remoção e atribuir um dono
• Auditar por lacunas de auth, segredos expostos e riscos de injeção SQL
• Se rollbacks continuam acontecendo, faça uma revisão de especialista antes do próximo release

Exemplo: sua nova correção de login funciona para a maioria, mas quebra contas criadas com social sign‑in. Mantenha o novo caminho atrás de uma flag, habilite para usuários internos primeiro e depois para uma pequena fatia do tráfego, enquanto corrige o caso de social sign‑in.

Se você lida com rollbacks frequentes e código gerado por IA bagunçado, a FixMyMess pode ajudar com uma auditoria gratuita de código, seguida de reparos direcionados e preparação para deploy em 48–72 horas, para que você envie com segurança e apague as flags mais rápido.