feature-flags

name	feature-flags
description	Design and implement feature flags — flag types (release/experiment/ops/permission), lifecycle (create→target→rollout→cleanup), gradual rollout strategy, kill switch pattern, and flag hygiene. Use when asked to "add a feature flag", "gradual rollout", "kill switch", "LaunchDarkly", "Unleash", "GrowthBook", "dark launch", "flag cleanup", "percentage rollout", or "canary release via flags". Do NOT use for: deployment canaries managed at infra level (Kubernetes, load balancer weights). Do NOT use for: A/B test statistical analysis — flags gate traffic, stats belong in analytics.
origin	yamtam-original
license	MIT © 2026 Vũ Văn Tâm
version	1.0.0
compatibility	LaunchDarkly SDK ≥ 6.x, Unleash ≥ 5.x, GrowthBook ≥ 1.x. Patterns are provider-agnostic.

When to Use

• Use when: releasing a risky feature to a subset of users before full rollout
• Use when: you need an instant kill switch without a redeploy
• Use when: running an experiment (A/B test) behind a flag
• Use when: cleaning up stale flags that are 100% rolled out or removed
• Do NOT use for: infra-level canary deploys — those live in the deployment pipeline
• Do NOT use for: config values that never change — use env vars instead

---

Flag Types

Type	Purpose	Lifetime
Release toggle	Gate incomplete feature during development	Short — remove after full rollout
Experiment flag	A/B test — split traffic, measure impact	Short — remove after decision
Ops flag	Kill switch, circuit breaker, rate limit toggle	Long-lived — keep as safety valve
Permission flag	Beta access, entitlements, plan gating	Long-lived — tied to user identity

Use the narrowest type that fits. Release toggles are the most common source of flag debt.

---

Lifecycle

1. CREATE   — name, type, default (off), owner, expiry date
2. TARGET   — specify who sees it (user IDs, segments, attributes)
3. ROLLOUT  — ramp percentage: 1% → 5% → 25% → 100%
4. CLEAN UP — remove flag + code path within TTL after full rollout

Default must always be the safe/old behavior — flag ON = new behavior.

---

SDK Usage Patterns

LaunchDarkly (Node.js)

import * as ld from '@launchdarkly/node-server-sdk';

const client = ld.init(process.env.LD_SDK_KEY);
await client.waitForInitialization();

// Always pass a context (replaces the old "user" object)
const ctx = { kind: 'user', key: user.id, plan: user.plan, country: user.country };

const newCheckout = await client.variation('new-checkout-flow', ctx, false); // false = default

if (newCheckout) {
  return handleNewCheckout(cart);
} else {
  return handleLegacyCheckout(cart);
}

Unleash (Node.js)

import { initialize } from 'unleash-client';

const unleash = initialize({
  url: process.env.UNLEASH_URL,
  appName: 'my-service',
  customHeaders: { Authorization: process.env.UNLEASH_TOKEN },
});

// Context carries targeting attributes
const enabled = unleash.isEnabled('new-checkout-flow', {
  userId: user.id,
  properties: { plan: user.plan },
});

GrowthBook (Node.js)

import { GrowthBook } from '@growthbook/growthbook';

const gb = new GrowthBook({
  apiHost: process.env.GB_API_HOST,
  clientKey: process.env.GB_CLIENT_KEY,
  attributes: { id: user.id, plan: user.plan },
});
await gb.loadFeatures();

if (gb.isOn('new-checkout-flow')) {
  return handleNewCheckout(cart);
}

---

Gradual Rollout Strategy

Day 0:   Internal users only (flag ON for employee accounts)
Day 1:   1% — catch crashes before they scale
Day 2:   5% — confirm p99 latency unchanged
Day 3:   25% — validate at meaningful traffic
Day 5:   100% — complete rollout
Day 7+:  Remove flag + dead code path

Monitor error rate and p99 latency at each step. Roll back by flipping flag to 0% — no deploy needed.

---

Kill Switch Pattern

An ops flag that is ON by default — flipping it OFF disables the feature.

// Kill switch: default TRUE (feature running normally)
const paymentsEnabled = await client.variation('payments-kill-switch', ctx, true);

if (!paymentsEnabled) {
  return { error: 'Payments temporarily unavailable. Please try again later.' };
}

Rules:

• Kill switches are long-lived — do not put an expiry on them
• Name them clearly: {feature}-kill-switch or {feature}-enabled
• Test the OFF path explicitly — it's the path that matters in an incident

---

Targeting Rules

Rollout order: internal → beta users → low-value cohort → geo subset → percentage ramp.

Context attributes to expose: user.id (stable, for consistent bucketing), user.plan, user.country, request.env.

Never target by email — IDs ensure consistent bucketing across sessions.

---

Testing with Flags

Inject flag state directly into functions — never call the SDK in unit tests.

// Both paths must be tested
it('new checkout when flag ON',  () => expect(checkout(cart, { newCheckoutFlow: true  })).toMatchNewShape());
it('legacy checkout when flag OFF', () => expect(checkout(cart, { newCheckoutFlow: false })).toMatchLegacyShape());

// Integration: mock the client
const mockClient = { variation: jest.fn().mockResolvedValue(true) };

A flag with only the ON path tested breaks silently when rolled back.

---

Flag Hygiene

Rule	Detail
Set expiry on creation	Release flags: 30 days. Experiment flags: 14 days.
One owner per flag	Owning team is responsible for cleanup
No nested flags	if (flagA && flagB) — creates 4 states to test
Max 10 active release flags per service	More = coordination hell
Cleanup = delete flag + remove both code paths	Not just the old path

Flag debt compounds: 50 stale flags means 50 conditional branches no one understands.

---

Anti-Fake-Pass Rules

Before claiming feature flag work is done, you MUST show:

• Default value is the safe/old behavior (flag OFF = no change for users)
• Both code paths have test coverage — ON and OFF
• Kill switch (if applicable) tested in the OFF state explicitly
• Context/user object passes a stable ID for consistent bucketing
• Expiry date or cleanup ticket created for release/experiment flags
• Rollout plan defined — not "flip to 100% and see what happens"
• Flag removed from code (not just dashboard) after full rollout

Reference: gates/anti-fake-pass-gate.md