| name | feature-flags-principles |
| description | Apply feature flag patterns ONLY when explicitly required by the PRD or technical architecture document. Covers flag evaluation rules, lifecycle management, testing strategies, and infrastructure requirements. Do NOT load speculatively. |
| user-invocable | false |
Feature Flags Principles
[!CAUTION]
Do NOT implement feature flags unless explicitly required.
Feature flags add real operational complexity: flag evaluation infrastructure,
lifecycle management, and a multiplicative increase in test permutations.
The cost is non-trivial for solo developers or simple projects.
Only introduce feature flags when the PRD or technical architecture document
explicitly specifies one of:
- Gradual / percentage rollout of a risky feature
- A/B testing or experimentation
- Emergency kill switches for production code paths
- Feature entitlement gating by user tier or permission
If none of these are specified, deploy code directly. Do not introduce flags speculatively.
When to Use Feature Flags
Feature flags decouple deployment from release. Code ships to production but stays
dormant until the flag enables it. This is valuable for:
| Use case | Flag type | Example |
|---|
| Gradual rollout | Release flag | new-checkout-flow: 0→5→25→100% |
| Emergency kill switch | Ops flag | use-legacy-payment-provider |
| A/B test / experiment | Experiment flag | button-color-blue-vs-green |
| Tier / permission gating | Permission flag | pro-tier-analytics |
Infrastructure Requirements
[!IMPORTANT]
The flag evaluation backend must be specified in the technical architecture document
before implementation begins. Do NOT choose a provider independently — ask the user
which infrastructure to use.
| Approach | When to use | Notes |
|---|
| Managed SaaS | Teams > 5, multi-environment, complex targeting | LaunchDarkly, Flagsmith, Unleash Cloud |
| Self-hosted | Full control, no SaaS dependency | Unleash (OSS), Flagsmith (OSS) |
| Firebase Remote Config | Mobile apps in the Firebase ecosystem | Firebase SDK required |
| Static config (YAML / env) | Solo dev, simple on/off, single environment | Loaded at startup; no runtime targeting |
Flag configuration is infrastructure — it must be provisioned before code references it.
Flag Evaluation Rules
- Evaluate server-side for security-sensitive features (never trust the client)
- Evaluate at request boundary — never inside pure business logic functions
- Default to disabled — if the flag service is unreachable, the flag is off (fail closed)
- Wrap flag checks once — in a service method or middleware, not scattered across business logic
Pattern:
// ✅ Flag evaluation at the boundary (handler or service entry point)
func (s *Service) CreateOrder(ctx context.Context, req Request) (Response, error) {
useNewPricing := s.flags.IsEnabled(ctx, "new-pricing-engine", req.UserID)
if useNewPricing {
return s.handleWithNewPricing(ctx, req)
}
return s.handleWithLegacyPricing(ctx, req)
}
// ❌ Flag evaluation buried inside business logic
func calculateDiscount(items []Item) float64 {
if flags.IsEnabled("new-discount-rules") { ... } // NO
}
Flag Lifecycle Rules
Flags are temporary by design. Flag debt accumulates fast and becomes a maintenance burden.
- Every flag must have an owner (the team or developer responsible for its lifecycle)
- Every release flag has a maximum lifespan of 90 days
- When a release flag reaches 100% rollout, create a ticket immediately to remove it
- Ops (kill switch) flags can be permanent but must be documented as such
- Experiment flags must be removed when the experiment concludes
- Review all flags in sprint planning — any flag past its expiry date is tech debt
Testing with Feature Flags
Feature flags multiply test permutations. Keep tests tractable:
- Unit tests test each branch independently (flag on + flag off)
- Integration tests default the flag to its production-expected state (usually fully on or off)
- Do not write tests that enumerate every possible flag combination
- Use a test-only flag override mechanism (e.g.,
flags.Override(ctx, "flag", true)) — never
branch test logic on environment variables
CI/CD Checklist (Feature Flags)
Related Principles
- CI/CD Principles @.claude/skills/ci-cd-principles/SKILL.md (deployment vs release concept)
- Architectural Patterns — Testability-First Design @.claude/rules/architectural-pattern.md
- Core Design Principles @.claude/rules/core-design-principles.md (YAGNI)
- Security Mandate @.claude/rules/security-mandate.md (server-side evaluation)
