Feature Flags na prática: como liberar funcionalidades sem medo de deploy

Todo time de desenvolvimento já viveu este cenário: a funcionalidade nova está pronta, foi testada, vai ao ar na sexta-feira à tarde e, meia hora depois, o suporte começa a receber reclamação. A única saída é reverter o deploy inteiro, derrubando junto outras correções que estavam no mesmo pacote.

Feature Flags existem para evitar exatamente isso. Elas separam duas coisas que parecem uma só: colocar o código em produção e liberar a funcionalidade para os usuários. Com essa separação, você pode publicar o código com segurança, ligar a funcionalidade para poucos clientes, observar o comportamento e só então ampliar, ou desligar tudo em segundos se algo der errado, sem novo deploy.

Este guia explica o que são Feature Flags, quais tipos existem, como implementar (com código), quais ferramentas usar, quais são as boas práticas e, principalmente, os riscos que quase ninguém conta no começo.

Neste artigo

Feature Flags em uma frase
As peças de uma Feature Flag
O que você ganha ao adotar Feature Flags
Quatro tipos de flag, quatro ciclos de vida
Para quem ligar e como ampliar
Caso prático: uma agenda online para um único cliente
Da variável de ambiente à plataforma: três níveis de implementação
Ferramentas para gerenciar flags
Dez hábitos que mantêm as flags sob controle
O lado ruim: riscos e dívida técnica
Situações em que a flag atrapalha
Perguntas frequentes

Feature Flags em uma frase

Uma Feature Flag (também conhecida como feature toggle ou feature switch) é uma condição no código que decide se determinada funcionalidade está ativa ou não para um contexto específico.

Na forma mais simples, é um valor verdadeiro ou falso consultado antes de executar um trecho de código:

if (flags.isEnabled("agenda-online", contexto)) {
  mostrarAgendaNova();
} else {
  mostrarAgendaAntiga();
}

O “contexto” é o que torna a ideia poderosa. Ele pode ser o cliente, o usuário, o ambiente, o país, o plano contratado ou qualquer outro dado. A mesma funcionalidade pode estar ligada para um cliente e desligada para outro, no mesmo código e no mesmo servidor.

Uma imagem útil: pense no disjuntor de uma casa. Ele não muda a instalação elétrica, apenas decide se aquele circuito recebe energia. A Feature Flag faz o mesmo com um trecho do sistema.

As peças de uma Feature Flag

Toda implementação, da mais simples à mais sofisticada, tem as mesmas peças:

Peça	Função
Definição da flag	Nome, descrição, valor padrão e regras de quando fica ativa
Armazenamento	Onde as regras ficam guardadas: arquivo, variável de ambiente, banco de dados ou serviço externo
Avaliação	O código que, dado um contexto, devolve ligado ou desligado
Ponto de uso	O `if` no sistema que muda o comportamento conforme o resultado
Controle e auditoria	Quem alterou, quando e por quê

O fluxo é sempre o mesmo: o sistema recebe uma requisição, monta o contexto (quem é o usuário, qual o cliente), pergunta à flag se a funcionalidade está liberada e executa o caminho correspondente.

O que você ganha ao adotar Feature Flags

Deploys mais seguros. O código vai para produção “desligado”. Se o deploy em si causar problema, o risco é menor, porque a funcionalidade nova ainda não está exposta.
Reversão instantânea. Desligar uma flag leva segundos. Reverter um deploy pode levar minutos ou horas e arrasta outras mudanças junto.
Liberação gradual. Dá para liberar para 1% dos usuários, depois 10%, depois todos, observando erros e métricas a cada etapa.
Entregas sob medida. Em sistemas usados por vários clientes, é possível liberar um recurso só para quem pediu ou pagou por ele, sem manter versões separadas do código. É comum em produtos SaaS.
Menos branches longas. Em vez de manter uma ramificação de código aberta por semanas, o time integra cedo e mantém o recurso oculto atrás da flag.
Testes em produção, com controle. Equipe interna ou clientes-piloto validam a funcionalidade real antes do lançamento geral.
Experimentos. Permite comparar versões diferentes de uma tela ou fluxo, base de qualquer teste A/B.

Em resumo, Feature Flags tiram o medo do deploy e transformam o lançamento em uma decisão de negócio, e não em um evento técnico.

Quatro tipos de flag, quatro ciclos de vida

Nem toda flag serve ao mesmo propósito, e tratar todas igual é a origem da maioria dos problemas. Uma classificação muito usada na engenharia de software, popularizada por Pete Hodgson no artigo publicado no site de Martin Fowler, separa as flags por tempo de vida e dinamismo:

Tipo	Para que serve
Release toggle	Esconde uma funcionalidade ainda incompleta ou não liberada. Vida curta: some quando o recurso é lançado para todos
Experiment toggle	Divide usuários em grupos para comparar versões e medir resultado. Vive enquanto durar o experimento
Ops toggle	Controla comportamento operacional, como desligar um recurso pesado em horário de pico. Pode viver bastante tempo
Permission toggle	Libera recursos por plano, perfil ou cliente (por exemplo, recurso premium). Costuma ser permanente

Repare na diferença de vida útil. Um release toggle deve ser removido em dias ou semanas. Um permission toggle pode existir por anos, e nesse caso nem é bem uma flag: é uma regra de negócio, e vale tratá-la como tal.

Existe ainda a kill switch (interruptor de emergência), que é uma ops toggle criada para desligar rapidamente algo que está causando problema, como uma integração externa instável.

Para quem ligar e como ampliar

Ter a flag é o primeiro passo. A segunda parte é decidir para quem ligar e como ampliar.

Estratégia	Como funciona
Por cliente ou domínio	Libera para clientes específicos, como o que pediu a funcionalidade ou um parceiro-piloto
Por porcentagem	Libera para uma fatia dos usuários (1%, 10%, 50%) e vai aumentando
Por grupo ou perfil	Libera primeiro para equipe interna, depois para testadores, depois para o público
Por ambiente	Ligada em homologação e desligada em produção, até estar validada
Canary release	Uma pequena parte do tráfego usa a versão nova, com monitoramento próximo para detectar problemas cedo
Dark launch	O código novo roda em produção em paralelo, sem afetar o usuário, apenas para observar desempenho e resultados

Combinar estratégias é normal: equipe interna primeiro, depois um cliente-piloto, depois 10% dos usuários, depois todos.

Caso prático: uma agenda online para um único cliente

Imagine um sistema de gestão usado por várias clínicas, todas rodando sobre o mesmo código. Uma delas pediu o agendamento online pelo paciente. A funcionalidade está na primeira versão e o time não quer expô-la às demais.

Sem Feature Flag, restariam duas escolhas ruins: manter uma cópia do código só para essa clínica ou segurar a entrega até o recurso ficar perfeito para todo mundo.

Com Feature Flag, o fluxo fica assim:

O código da agenda online vai para produção junto com o restante, protegido pela flag agenda-online, desligada por padrão.
A flag é ativada só para a clínica que pediu.
O time acompanha erros, desempenho e feedback dessa clínica.
Ajustes saem em deploys normais. A clínica-piloto já vê as melhorias, e as demais não percebem nada.
Com o recurso estável, a flag é ligada para mais clientes, em etapas.
Quando todos usam, a flag é removida do código e a agenda passa a fazer parte do sistema.

O passo 6 é o que mais se esquece, e voltamos a ele nos riscos.

Da variável de ambiente à plataforma: três níveis de implementação

Você não precisa de uma plataforma cara para começar. Escolha o nível conforme o tamanho e a necessidade do seu sistema.

Nível 1: configuração simples

Para sistemas pequenos, uma variável de ambiente ou um arquivo de configuração já resolve:

const flags = {
  "agenda-online": process.env.FF_AGENDA_ONLINE === "true",
};

if (flags["agenda-online"]) {
  // código novo
}

Vantagem: zero dependência. Limitação: para mudar o valor, normalmente é preciso reiniciar ou republicar a aplicação, e não há regra por cliente.

Nível 2: flags no banco de dados

Para liberar por cliente e alterar sem deploy, guarde as flags em uma tabela:

CREATE TABLE feature_flags (
  id            INT PRIMARY KEY AUTO_INCREMENT,
  nome          VARCHAR(100) NOT NULL,
  cliente_id    INT NULL,          -- NULL significa regra global
  ativa         BOOLEAN NOT NULL DEFAULT FALSE,
  percentual    TINYINT NOT NULL DEFAULT 100,
  criada_em     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  atualizada_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uq_flag_cliente (nome, cliente_id)
);

E uma função de avaliação que considera a regra do cliente, a regra global e o percentual. Para o percentual funcionar de forma estável (o mesmo usuário sempre cai no mesmo grupo), use um hash em vez de sorteio:

import { createHash } from "node:crypto";

function faixa(flag, usuarioId) {
  const hash = createHash("sha256").update(`${flag}:${usuarioId}`).digest();
  return hash.readUInt32BE(0) % 100; // número de 0 a 99
}

function estaAtiva(flag, { clienteId, usuarioId }) {
  const regra =
    buscarRegra(flag, clienteId) ?? buscarRegra(flag, null) ?? { ativa: false, percentual: 0 };

  if (!regra.ativa) return false;
  return faixa(flag, usuarioId) < regra.percentual;
}

Esse nível atende muita gente por muito tempo. Os pontos de atenção são cache (para não consultar o banco a cada requisição), uma tela administrativa para operar as flags e registro de quem alterou o quê.

Nível 3: ferramenta dedicada

Quando há muitas flags, vários times, regras complexas, experimentos e necessidade de auditoria, vale adotar uma plataforma pronta, que traz painel, regras avançadas, histórico e integração com métricas. É a próxima seção.

Ferramentas para gerenciar flags

Ferramenta	Perfil
LaunchDarkly	Plataforma comercial completa, muito usada em empresas com várias equipes
Unleash	Código aberto, pode ser hospedado por você, com versão em nuvem
GrowthBook	Código aberto, forte em experimentos e testes A/B
Flagsmith	Código aberto, com opção de hospedagem própria ou em nuvem
OpenFeature	Não é uma ferramenta, e sim um padrão aberto de API para flags, que evita ficar preso a um fornecedor
Solução própria	Tabela no banco e painel simples, suficiente para muitos produtos menores

Ao escolher, compare: se precisa de regras por porcentagem e por atributo, se há exigência de auditoria, onde as flags serão avaliadas (servidor ou navegador), qual o custo e se quer ou não hospedar sozinho. Adotar um padrão como o OpenFeature desde o início facilita trocar de ferramenta depois.

Dez hábitos que mantêm as flags sob controle

Nomeie com clareza. agenda-online diz mais que flag_12 ou novo_teste. Padronize o formato.
O valor padrão deve ser “desligado”. Se a ferramenta de flags falhar, o sistema deve cair no comportamento antigo e estável.
Defina dono e prazo. Toda flag de lançamento precisa de um responsável e de uma data prevista de remoção.
Teste os dois caminhos. Se a flag existe, existem dois comportamentos. Ambos precisam de teste automatizado. Veja como isso se encaixa em QA na prática.
Avalie no servidor, não no navegador. Regras de permissão avaliadas só no front-end podem ser burladas por quem sabe mexer no código do navegador.
Evite flags aninhadas. Uma flag dentro de outra dentro de outra multiplica as combinações e torna o comportamento imprevisível.
Registre alterações. Saber quem ligou o quê, e quando, economiza horas durante um incidente.
Monitore ao liberar. Ligar uma flag sem acompanhar erros, desempenho e métricas de negócio é só trocar um risco por outro. Veja o que é monitoramento e logs.
Separe flags de configuração. Flag é para decidir entre comportamentos. Valores como limite de upload ou texto de um botão são configuração.
Mantenha um inventário. Uma lista simples de flags existentes, com dono, tipo e data de criação.

O lado ruim: riscos e dívida técnica

Feature Flags resolvem problemas, mas criam outros se forem tratadas como “grátis”.

Risco	Consequência
Flags esquecidas	O código acumula ramificações mortas que ninguém entende nem tem coragem de apagar
Explosão de combinações	Com muitas flags ativas, o número de estados possíveis cresce e o sistema fica impossível de testar por completo
Código duplicado	Manter o caminho antigo e o novo por muito tempo dobra a manutenção
Flag mal configurada em produção	Um valor errado pode desligar uma funcionalidade crítica ou expor um recurso incompleto
Dependência do serviço de flags	Se a avaliação depende de um serviço externo e ele cai, o sistema precisa ter um padrão seguro
Falsa sensação de segurança	Código ruim atrás de uma flag continua sendo código ruim, só que escondido

O antídoto é disciplina: toda flag de lançamento nasce com data de morte. Quando a funcionalidade está liberada para todos e estável, apague a flag e o código antigo. Isso faz parte do trabalho de manter a qualidade de software e a estabilidade no longo prazo.

Situações em que a flag atrapalha

Em mudanças triviais. Corrigir um texto ou ajustar uma cor não precisa de flag.
Em alterações de banco de dados incompatíveis. Uma flag não resolve uma migração que quebra a estrutura antiga. Nesse caso, o caminho é planejar a migração em etapas compatíveis. Veja versionamento e migrações sem quebrar.
Em projetos muito pequenos e sem múltiplos clientes. Se existe um único ambiente e um único público, o custo de manter flags pode superar o benefício.
Como substituto de teste. Flag reduz o impacto de um erro, mas não o evita.

Feature Flags, CI/CD e entrega contínua

As flags brilham quando combinadas com CI/CD. Com integração e deploy frequentes, o time publica código pequeno várias vezes ao dia. As flags garantem que isso aconteça sem expor funcionalidades incompletas. Para o lado do versionamento, o artigo planeje deploys seguros com versionamento semântico complementa bem.

Checklist antes de criar uma Feature Flag

Qual problema essa flag resolve: lançamento, experimento, operação ou permissão?
Qual é o valor padrão e o que acontece se a avaliação falhar?
Quem é o responsável e quando ela será removida?
Os dois caminhos de código estão testados?
Existe como desligar rápido e como saber que algo deu errado?
A avaliação acontece no servidor?
A flag está registrada no inventário?

Dúvidas comuns sobre Feature Flags

O que é uma Feature Flag?

É uma condição no código que liga ou desliga uma funcionalidade para um contexto específico, como um cliente, um usuário ou um ambiente, sem exigir um novo deploy. Também é chamada de feature toggle.

Feature Flag e Feature Toggle são a mesma coisa?

Sim. Os dois termos descrevem a mesma técnica. “Flag” (bandeira) e “toggle” (interruptor) são usados de forma intercambiável.

Para que serve uma Feature Flag?

Para separar o deploy do lançamento. Serve para publicar código com segurança, liberar recursos gradualmente, desligar rapidamente algo que deu problema, liberar funcionalidades por cliente ou plano e rodar experimentos.

Feature Flags substituem testes?

Não. Elas limitam o estrago de um erro, mas não o impedem. Os dois caminhos do código, com a flag ligada e desligada, precisam ser testados.

Preciso de uma ferramenta paga para usar Feature Flags?

Não. Dá para começar com variáveis de ambiente ou uma tabela no banco. Ferramentas dedicadas passam a valer a pena quando há muitas flags, regras complexas, vários times ou necessidade de auditoria.

Qual a diferença entre Feature Flag e configuração do sistema?

Flag decide entre comportamentos diferentes de uma funcionalidade, e normalmente tem vida curta. Configuração define valores de parâmetros, como limites, textos e integrações, e tende a ser permanente.

Quando devo remover uma Feature Flag?

Assim que a funcionalidade estiver liberada para todos e estável. Remova a flag e o código do caminho antigo. Flags de lançamento esquecidas viram dívida técnica.

Feature Flags prejudicam a performance?

Quase nunca, se bem implementadas. A avaliação normalmente é uma consulta rápida, e pode ser feita com cache. O problema de desempenho aparece quando a consulta é feita a cada requisição sem cache, ou quando há dependência de um serviço externo lento.

Dá para usar Feature Flags em WordPress ou em sites simples?

Dá, mas raramente compensa. Em sites com um único público e poucas mudanças, o custo de manter a estrutura costuma superar o benefício. Elas fazem mais sentido em sistemas com vários clientes, deploys frequentes e funcionalidades em evolução.

Conclusão

Feature Flags são uma das práticas mais eficientes para reduzir o risco de entregar software. Elas permitem publicar com frequência, liberar com calma e voltar atrás sem drama. O preço é disciplina: nomear bem, testar os dois caminhos, monitorar a liberação e, principalmente, apagar a flag quando ela cumpriu seu papel.

Se o seu sistema atende vários clientes, tem entregas frequentes ou já passou por um susto em um deploy, é um bom momento de avaliar essa prática. E se você quer ajuda para desenhar isso no seu produto, do modelo de dados da flag ao processo de liberação, é o tipo de projeto que atendo como desenvolvedor freelancer.

Referências

Pete Hodgson, publicado em martinfowler.com. “Feature Toggles (aka Feature Flags)”. Artigo de referência que organiza os tipos de toggles e discute práticas e riscos.
OpenFeature. “Documentation”. Padrão aberto, independente de fornecedor, para avaliação de feature flags.
Unleash. “Feature toggles best practices”. Documentação de uma das ferramentas de código aberto mais usadas, com guias de uso e boas práticas.