Feature Flag Naming Conventions

Feature Flag Naming Conventions

Consistent naming makes flags discoverable, self-documenting, and easier to manage at scale. A good naming convention communicates the flag's purpose, scope, and ownership at a glance.

Recommended Format

{prefix}.{team}.{feature-name}

Examples:

• release.checkout.one-click-buy
• experiment.growth.signup-modal-v2
• ops.payments.stripe-circuit-breaker
• permission.enterprise.sso-login

Configuration Example

{
  "release.editor.ai-autocomplete": {
    "name": "AI Autocomplete in Editor",
    "description": "GPT-based code completion in the editor",
    "type": "boolean",
    "enabled": true,
    "defaultValue": false,
    "targeting": []
  },
  "ops.search.elasticsearch-circuit-breaker": {
    "name": "Elasticsearch Circuit Breaker",
    "description": "KILL SWITCH: Disable elasticsearch, fall back to SQL",
    "type": "boolean",
    "enabled": true,
    "defaultValue": true,
    "targeting": []
  }
}

Prefix Categories

Prefix	Purpose	Typical Lifetime	Example
release.	New feature rollout	Weeks	release.auth.passkey-login
experiment.	A/B test	2-4 weeks	experiment.pricing.annual-discount
ops.	Operational control	Permanent	ops.api.rate-limit-v2
permission.	Entitlement/plan	Long-lived	permission.pro.export-csv
config.	Dynamic config	Varies	config.ui.items-per-page

Casing Conventions

Style	Example	When to Use
kebab-case	new-checkout-flow	Most common, URL-friendly
snake_case	new_checkout_flow	Common in Python/Ruby ecosystems
camelCase	newCheckoutFlow	JavaScript/TypeScript codebases
dot.notation	checkout.new.flow	Hierarchical namespacing

Pick one style and use it consistently across all flags.

Anti-Patterns to Avoid

Bad	Why	Good Alternative
flag1, test-flag	No meaning	release.search.fuzzy-matching
temp-fix-for-bug	Too vague	ops.billing.invoice-retry-fix
johns-experiment	Person-specific	experiment.growth.signup-redesign
new-feature	Too generic	release.editor.markdown-preview
DO-NOT-DELETE	Maintenance nightmare	Document in description field

Large Team Conventions

For organizations with 10+ teams:

• Require team namespace: {prefix}.{team}.{feature}
• Enforce with linting: Reject flag keys that don't match the pattern
• Central registry: Searchable dashboard of all flags with owners
• Naming review: Include flag naming in PR review checklist