Feature Flags Principles

Feature Flags Principles

CAUTION: Do NOT implement unless PRD/arch explicitly requires: gradual rollout, A/B testing, kill switches, or tier gating. Flags add real complexity (evaluation infra, lifecycle, test permutations). No spec → deploy directly.

When to Use

Infrastructure

Flag backend MUST be specified in tech arch doc. Do NOT choose independently — ask user.

Evaluation Rules

• Server-side for security-sensitive (never trust client)
• Evaluate at request boundary — never inside pure business logic
• Default disabled (fail closed if service unreachable)
• Wrap flag checks once (service method/middleware, not scattered)

// ✅ Flag at boundary
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 inside business logic
func calculateDiscount(items []Item) float64 {
    if flags.IsEnabled("new-discount-rules") { ... }   // NO
}

Lifecycle

Flags are temporary. Debt accumulates fast.

• Every flag has an owner
• Release flags: max 90 days
• 100% rollout → create removal ticket immediately
• Ops flags can be permanent (documented)
• Experiment flags removed when concluded
• Review flags in sprint planning

Testing

• Unit: test each branch independently (on + off)
• Integration: default to production-expected state
• Do NOT enumerate all flag combinations
• Use test-only override (flags.Override(ctx, "flag", true))

Checklist

• Infra in tech arch doc
• Backend provisioned + accessible
• Owner + expiry per flag
• Server-side for security paths
• Default: disabled
• Tests cover both paths
• Removal ticket at 100%

Related

• CI/CD @.gemini/skills/ci-cd-principles/SKILL.md
• Architectural Patterns @.gemini/rules/architectural-pattern.md
• Core Design @.gemini/rules/core-design-principles.md (YAGNI)
• Security Mandate @.gemini/rules/security-mandate.md