Skip to content

borghei/Claude-Skills / project-management/execution/feature-flag-strategy

feature-flag-strategy

Unverified

Plan a flag-gated rollout: classify the flag, pick a rollout shape, set kill-switch thresholds and retire the flag. Use when planning a phased rollout, a kill switch, a holdout or a cleanup of old flags.

references/fowler-feature-toggle-taxonomy-guide.md

View on GitHub
# Fowler's Feature Toggle Taxonomy Guide

A working reference for Martin Fowler's "Feature Toggles" taxonomy and how to apply it operationally. The taxonomy matters because each toggle category has different lifespan, ownership, and risk -- conflating them is the single most common cause of flag debt.

## 1. Origin

Pete Hodgson published "Feature Toggles (aka Feature Flags)" on Martin Fowler's site in 2017 (updated through 2020). The article codified what teams at LaunchDarkly, Etsy, Facebook, and Yelp had been doing for years: flags are not all the same; treat them by category.

## 2. The four categories

### Release Toggles

**Purpose.** Decouple deploy from launch. Code ships behind the toggle; product turns it on when ready.

**Lifespan.** Days to weeks. Should be **retired** within ~30 days of full rollout.

**Ownership.** The product team that built the feature. PM + Eng lead.

**Failure mode.** Never retired. Becomes "permanent" without explicit decision. Three years later, nobody remembers what `enable_new_search_v2_2023` controls.

**Discipline.**
- Set a retirement date when the flag is created.
- Track in the team's flag inventory.
- File a retirement PR as part of the launch checklist.
- The flag library should support marking "stale" toggles and alerting on them.

### Experiment Toggles

**Purpose.** A/B test variants. Allocate users to control / variant arms; measure lift.

**Lifespan.** Days to weeks. **Retire when the experiment concludes**, whether the variant ships or not.

**Ownership.** Product team + analytics / data science.

**Failure mode.** Experiment "runs forever" because the analyst is on PTO; the team forgets which is the winning variant; the analysis never finalizes.

**Discipline.**
- Pre-register the experiment: hypothesis, primary metric, sample size, run window.
- Define the decision criteria (statistical significance threshold, effect-size minimum).
- Define the decision date and the decider.
- Retire the experiment toggle within 14 days of decision.
- Keep the holdout slice open beyond the experiment for long-term lift attribution.

### Ops Toggles

**Purpose.** Operational controls: circuit breakers, throttles, kill-switches for system protection, degrade-modes.

**Lifespan.** Permanent or long-lived. They are part of the system's defensive surface.

**Ownership.** Infrastructure / SRE / platform team.

**Failure mode.** Rare; ops toggles tend to be well-maintained because they are critical to incident response.

**Discipline.**
- Document each ops toggle in the SRE runbook.
- Test the ops toggle quarterly in non-prod (and ideally in prod with a controlled drill).
- Rotate ownership when team members leave.

### Permission Toggles

**Purpose.** Gate features by user, plan tier, role, tenant, beta program enrollment.

**Lifespan.** Permanent. Lives with the product.

**Ownership.** Product + Eng.

**Failure mode.** Treated as a release toggle and "cleaned up", removing the permission boundary and exposing the feature universally.

**Discipline.**
- Distinguish permission flags from release flags in naming (`__permission`, `__beta_access`).
- Document in the product entitlement system / pricing page.
- Treat the permission flag as part of the product's contract with users, not a deploy artifact.

## 3. The lifecycle-vs-dynamism matrix

Fowler's original article includes a useful 2x2:

|  | Short-lived | Long-lived |
|---|---|---|
| **Static (per environment, per deploy)** | Release toggle | Permission toggle |
| **Dynamic (per request)** | Experiment toggle | Ops toggle |

- Release toggles are typically *static* and *short-lived*: set once for the deploy, retired after launch.
- Experiment toggles are *dynamic* (per-user evaluation) and *short-lived*.
- Permission toggles are *static* (per-tenant or per-user) and *long-lived*.
- Ops toggles are *dynamic* (often per-request) and *long-lived*.

Picking the wrong cell is a category error. A "permission" implemented as a dynamic per-request flag will hammer your flag service. A "release toggle" implemented as a long-lived permission flag will never get cleaned up.

## 4. Implementation patterns Fowler highlights

Fowler distinguishes between **toggle point** (where in code the toggle is checked) and **toggle router** (the runtime that decides). Patterns:

- **Toggle point as low-level as possible.** Each branch is small, easy to remove.
- **Toggle router as a single source.** All evaluations route through one library, one config, one audit log.
- **Inversion of control.** Code does not query "is feature X on?"; rather, the platform injects the variant. This makes A/B testing and rollout cleaner.

## 5. Lifespan disciplines

Fowler's strongest claim: the practice of feature flagging is **operationally expensive**. The investment pays off only if flags are retired aggressively. Specifically:

- **Track every flag.** A registry of all flags, their type, their owner, their last-flip timestamp.
- **Stale-flag alerting.** A flag at 100% (or 0%) for more than 30 days is stale. The flag service or CI should surface this weekly.
- **Retirement is engineering work.** Plan it into sprints; do not treat it as cleanup.
- **Limit concurrent flags.** A team running 50 active flags simultaneously is in flag-debt territory. Target 5-15 for most teams.
- **Pair every release toggle with a retirement PR opened at flag-creation time.**

## 6. Pitfalls

| Pitfall | Cause | Mitigation |
|---|---|---|
| **Flag debt** | No retirement discipline | Quarterly audit; retirement PRs at creation |
| **Configuration sprawl** | Flags pile up across environments | Single source of truth in the flag service |
| **Hidden coupling** | Feature A depends implicitly on Feature B's flag state | Explicit prerequisite dependencies in the flag service |
| **Production flag drift** | Prod flag state diverges from staging/dev | Same flag service for all environments; staging flag state mirrors prod |
| **Test matrix explosion** | N flags = 2^N combinations | Test only combinations that occur in production; retire flags to shrink N |
| **"Toggle as permission" anti-pattern** | Using a temporary toggle to gate permanent access | Convert to a permission flag explicitly; rename; transfer ownership |
| **No audit log** | Hard to debug post-incident | Flag service should log every flip with who / when / why |
| **No granular control** | "On/off" only, no percentage rollout | Use a flag library that supports percentage and segmented rollouts |

## 7. Modern updates (2020-2026)

The 2017 Fowler article remains the canonical text, but the 2020-2026 industry has settled on additional norms:

- **OpenFeature** (CNCF spec) standardizes the SDK surface across vendors. Adopted by LaunchDarkly, Flagsmith, Unleash, ConfigCat.
- **Statsig** popularized the experimentation-first flag model (deep integration with metrics and stat-sig analysis).
- **Eppo + StatSig + Optimizely** dominate the experimentation-toggle category.
- **Hypothesis-driven rollout.** Each release toggle has a stated hypothesis ("rolling this out should not regress p95 latency by more than 5%") that gates each ramp step.
- **AI-feature ramps.** For LLM features, ramps include cost and eval gates (see `ai-feature-prd/` Section 11.3).
- **Compliance flags.** EU AI Act compliance + GDPR / regional opt-outs are increasingly enforced via permission flags scoped to geography.

## 8. Anti-pattern: the "permanent release toggle"

By far the most common failure. A release toggle was created in 2023, ramped to 100%, never retired. By 2026, the code has two branches around every check; nobody is sure which branch is dead; engineers fix bugs in the dead branch; the team is afraid to clean it up because the consequences are unclear.

Prevention:
- Retirement date is a required field at flag creation.
- Stale-flag report on the team's weekly engineering review.
- Retirement PRs treated as ordinary work, not "tech debt."
- Engineering manager owns the team-level flag count metric.

## 9. Reading list

- Pete Hodgson, "Feature Toggles (aka Feature Flags)" (martinfowler.com, 2017, updated 2020)
- "Trunk-Based Development" -- trunkbaseddevelopment.com (the flag practice goes hand-in-hand with TBD)
- LaunchDarkly, "Effective Feature Management Engineering" (free e-book, multiple editions)
- OpenFeature, "Specification" (openfeature.dev)
- "Accelerate" (Forsgren, Humble, Kim) -- references feature flagging as a deployment-decoupling practice

---
**Last Updated:** 2026-05-22
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall