Feature Flags

Feature Flags

A feature flag decouples deploy from release: ship the code dark, turn it on when ready, turn it off instantly if it misbehaves. Powerful — and a debt magnet if you don't retire them. The single most important rule: every flag needs a removal plan from the day it's created.

Flag types (don't conflate them)

• Release flag — temporary, gates an in-progress feature. Removed once fully rolled out.
• Ops / kill switch — long-lived, lets you disable an expensive or risky subsystem under

load or incident. Kept on purpose.

• Experiment flag — drives an A/B test; removed when the experiment concludes.
• Permission / entitlement — long-lived, gates by plan/tenant. This is config, not a

feature flag — treat it as such.

Mixing these is how you end up with 200 flags nobody understands. Name and document which kind each one is.

Safe rollout

• Default off. A new flag's default is the old behavior. Shipping the code does nothing

until you deliberately turn it on.

• Ramp progressively: internal → 1% → canary cohort → 10% → 50% → 100%, watching the

error rate and key metrics at each step. Don't jump to 100%.

• Make it killable instantly — flipping off must not require a deploy, and off must be a

safe state at any ramp percentage.

• Both paths must work at every step. While a flag is live, old and new code paths both

run in production. Test both; don't let the off-path rot.

The cleanup discipline (where teams fail)

• A release flag is temporary. When it's at 100% and stable, delete the flag *and the

dead branch* — the code, the config, the tests for the old path. A flag left in forever is a permanent if nobody dares remove.

• Track flag age. A release flag older than its feature is a smell. Put an expiry/owner on

it; review stale flags regularly.

• Avoid flag dependencies (flag B only sane when flag A is on) — they multiply states

combinatorially and make reasoning impossible.

Gotchas

• State explosion: N flags = up to 2^N code paths. Keep the live set small.
• Consistency: a user flipping mid-session between on/off paths can hit inconsistent

state — evaluate the flag once per request/session, not per call.

• Don't gate data migrations on a release flag the way you'd gate UI — a half-migrated

schema behind a flag is a different, riskier problem (see safe-database-migrations).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AlisinaDevelo
• Source: AlisinaDevelo/md-files
• License: MIT

Install and usage instructions live in the source repository linked above.