feature_flags v1.0.0

name: "feature_flags" description: "Designing and operating feature flags: flag types, rollout strategies, kill switches, and cleanup discipline for agents shipping code changes. Triggers on: roll out a feature gradually, add a kill switch, feature flag design, darken-launch, remove old flags." metadata: { "includeInPrompt": true }

Purpose

Feature flags decouple deployment from release: ship code to trunk behind a flag, then expose it to users on your own schedule. Use them to roll out gradually, run experiments, and kill a bad change in seconds without a redeploy. The discipline that makes them work is cleanup — an undeleted flag is permanent conditional logic in your codebase, i.e. tech debt you opted into.

Workflow

1. Classify the flag. Pick one type before writing any code (types below). The type determines default value, owner, and expiry policy.
2. Name and register it. Use team.feature.state (e.g. checkout.applepay.v2). Record owner + expiry date at creation in your flag registry — a registry row without both is rejected.
3. Choose the rollout strategy. Start with targeted (your team, then beta cohort), widen to percentage, go to 100%. Ring deployments for infrastructure-level changes.
4. Add the kill switch first. For any flag guarding a risky path, the kill branch is written before the feature branch. Default the flag to the SAFE value and decide fail-closed vs fail-open per blast radius (payments: fail-closed; UI copy: fail-open is usually fine).
5. Ship, observe, complete. Track exposure (who saw the flag on) alongside errors. When rollout hits 100% and holds for the agreed bake period, the flag comes out in the next sprint — the old path is deleted, not left behind.

Output Contract

Given a change to ship safely, produce:

• Flag type (release / experiment / ops-kill-switch / permission / migration) and why it fits.
• Flag name in team.feature.state format, plus owner and expiry date.
• Rollout plan: stages (targeted → percentage → 100%), bucketing key, kill-switch default and fail mode.
• Evaluation snippet implementing the plan (see sketch below), wired to real user context.
• Cleanup ticket: the removal task with its due sprint, filed at creation time, not later.

Flag types (one paragraph each):

• Release flags (trunk gating). Gate unfinished or unreleased work so trunk stays deployable. Short-lived by design: the flag dies the moment the feature is fully rolled out and the old path is removed. Prefer one flag per feature slice.
• Experiment flags (A/B with bucketing). Split users into variants with stable bucketing so a user sees the same variant on every request. Keep the bucketing key fixed for the experiment's life — changing it mid-run invalidates results.
• Ops / kill-switch flags. Long-lived, rarely-on flags that disable a subsystem fast (payment provider, outbound email, expensive job). Default to the SAFE state; the kill branch must be the simplest possible code path.
• Permission / entitlement flags. Gate features by plan or entitlement (pro tier, beta program). These tend to be long-lived — that's acceptable, but treat them as access control, not rollout: they still get owners and review dates.
• Migration flags. Route traffic between old and new implementations of the same behavior (DB schema, API client, queue). Prefer dual-write + read-verify patterns where the blast radius justifies it; delete the old path aggressively once parity is proven.

Operating Rules

Rollout strategies. Boolean on/off for kill switches and dark launches. Percentage rollout with consistent hashing on a stable user key — stable assignment matters because a user flipping between variants mid-session sees inconsistent behavior and corrupts experiment data. Targeted rollout by user IDs, cohorts, or geography for staged exposure. Ring/canary deployments for infra changes (one region, then all).

Evaluation sketch (verified — see report). Context-based rules evaluated top-down: kill switch first, then explicit targets, then percentage bucket, then default. Evaluation failures return the safe default.

python
import hashlib

def _bucket(user_key: str, flag: str) -> float:
    h = hashlib.sha256(f"{flag}:{user_key}".encode()).hexdigest()
    return int(h[:8], 16) / 0xFFFFFFFF  # stable 0..1

def get_flag(user_key, flag_name, rules, default=False):
    try:
        r = rules.get(flag_name) or {}
        if r.get("kill"): return False                    # kill switch wins
        if user_key in r.get("users", set()): return True # targeted
        return _bucket(user_key, flag_name) * 100 < r.get("pct", 0)
    except Exception:
        return default  # eval failure -> fail-closed to safe value

Tooling landscape. OpenFeature: open standard / vendor-neutral SDK — prefer when you want to avoid lock-in or swap providers. Managed (LaunchDarkly): prefer when you want dashboards, targeting UI, and audit trails without operating infra. Self-hosted / open-source (Unleash, Flipt, Flagsmith): prefer when data must stay in your infrastructure or cost matters. Zero-dependency option for small projects — a config file:

yaml
flags:
  new-checkout: { users: [u_alice], pct: 50, default: false }

Lifecycle / cleanup discipline. This is the #1 operational failure mode, so it gets teeth: every flag is created with an owner and an expiry date, recorded in the registry. Cleanup rule — remove the flag within 2 sprints of reaching 100% rollout (release/experiment/migration types); permission flags get a quarterly review instead. Run a stale-flag audit on a fixed cadence (monthly for active teams): any flag past expiry without a renewed date gets a removal ticket assigned to its owner. Prefer deleting the old path over leaving "just in case" branches — the flag did its job; keeping it is the debt.

Anti-patterns. Flags that are never removed (the default outcome without the cleanup rule above). Flag-dependent flags — nesting one flag's evaluation inside another's branch; flatten to independent flags or a single rule set. Using flags as general config for non-rollout settings (timeouts, URLs, credentials) — that's what config management is for; flags gate behavior changes. Percentage rollout keyed on unstable identifiers (session ID, request ID, IP) — assignment must survive across requests, so key on user ID or another stable key.