LaunchDarkly Flag Pro

A specialized LaunchDarkly-aware agent that maintains feature flag health and consistency across repositories, automating flag hygiene workflows by safely removing stale flags, analyzing their usage, and managing lifecycle transitions.

When to Use This Agent

Choose LaunchDarkly Flag Pro when:

• Cleaning up stale feature flags that have been fully rolled out
• Analyzing flag usage across the codebase to understand dependencies
• Planning safe flag removal with impact analysis
• Auditing feature flag hygiene and lifecycle compliance
• Managing flag targeting rules and rollout percentages

Consider alternatives when:

• Implementing new feature flags from scratch (use a general development agent)
• Setting up LaunchDarkly infrastructure (use a DevOps agent)
• Designing feature flag strategy and conventions (use an architecture agent)

Quick Start

Copy
# .claude/agents/launchdarkly-flag-pro.yml
name: LaunchDarkly Flag Pro
description: Manage LaunchDarkly feature flag lifecycle and cleanup
model: claude-sonnet
tools:
  - Read
  - Edit
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Identify all stale feature flags that have been at 100% rollout for more than 30 days and generate a safe removal plan for each"

Core Concepts

Flag Lifecycle Stages

Stage	Status	Action	Duration
Created	New	Flag added to LD, code wrapped	Day 0
Testing	Active	Targeted to internal users	1-7 days
Rollout	Active	Progressive % increase	1-4 weeks
Fully On	Stale candidate	100% for all users	Monitoring period
Cleanup	Removal	Remove flag code + LD config	After validation
Archived	Done	Flag deleted from LaunchDarkly	Final step

Flag Usage Analysis

Copy
// Flag usage pattern detection
interface FlagAnalysis {
  key: string;
  status: 'active' | 'stale' | 'dead';
  codeReferences: CodeReference[];
  lastEvaluated: Date;
  rolloutPercentage: number;
  daysAtCurrentState: number;
  dependencies: string[];    // Other flags that reference this one
  safeToRemove: boolean;
  removalComplexity: 'simple' | 'moderate' | 'complex';
}

// Simple removal: flag wraps a single code path
// if (flagEnabled('new-checkout')) { newCheckout() } else { oldCheckout() }
// → Remove condition, keep newCheckout(), delete oldCheckout()

// Complex removal: flag is checked in multiple files, affects data schemas
// or has dependencies with other flags

Safe Flag Removal Pattern

Copy
// Before removal: feature flag in code
import { useFlags } from 'launchdarkly-react-client-sdk';

function CheckoutPage() {
  const { newCheckoutFlow } = useFlags();

  if (newCheckoutFlow) {
    return <NewCheckout />;
  }
  return <LegacyCheckout />;
}

// After removal: flag fully rolled out, remove the conditional
function CheckoutPage() {
  return <NewCheckout />;
}

// Cleanup checklist:
// 1. Remove flag evaluation from code
// 2. Remove the "off" code path (LegacyCheckout)
// 3. Remove any flag-specific tests
// 4. Update tests that mocked the flag
// 5. Archive the flag in LaunchDarkly
// 6. Delete unused components/functions

Configuration

Parameter	Description	Default
stale_threshold_days	Days at 100% before considered stale	30
auto_detect_sdk	Detect LaunchDarkly SDK usage patterns	true
include_tests	Analyze test files for flag references	true
removal_strategy	Removal approach (conservative, standard, aggressive)	standard
require_approval	Require manual approval before each removal	true
backup_old_code	Comment out old code paths instead of deleting	false

Best Practices

1. Always analyze the full dependency graph before removing a flag. A flag might be checked in 3 application files, 5 test files, 2 configuration files, and referenced by another flag's targeting rules. Missing any reference causes runtime errors or broken tests. Use comprehensive search patterns: the flag key as a string literal, as a constant, and in LaunchDarkly API calls. Grep for both the flag key and any aliased constant names.

2. Remove the code path that is no longer active, not the flag check alone. When a flag is at 100%, the "off" path is dead code. Simply removing the if statement without removing the dead code leaves unused functions, components, and imports in the codebase. Remove the entire dead code path, then verify that nothing else references the removed code. This keeps the codebase clean and reduces bundle size.

3. Create separate PRs for each flag removal. Bundling multiple flag removals into one PR makes rollback difficult if one removal causes issues. Each flag removal PR should be independently reviewable, testable, and revertable. Include the flag key in the PR title: "Remove feature flag: new-checkout-flow." This makes the git history searchable by flag name.

4. Verify flag removal in staging before merging to production. Deploy the flag removal to a staging environment and verify that the feature works correctly without the flag. Check both the happy path and error scenarios. The flag may have been masking a bug in the "on" path that was never exercised because the flag was gradually rolled out.

5. Set up automated stale flag detection in CI. Add a CI check that scans for flags at 100% rollout for more than the configured threshold (e.g., 30 days) and creates issues or alerts. This prevents flag debt from accumulating. Pair this with a dashboard showing the total number of active flags and the age distribution — healthy projects keep this number under 20.

Common Issues

Removing a flag breaks a test that mocks the flag value. Tests that set up LaunchDarkly mocks or test both code paths will fail when the flag is removed. Update tests in the same PR: remove flag mocking, remove tests for the dead code path, and keep tests for the surviving code path. If tests use a shared flag mock setup, update it once and verify all dependent tests.

Flag removal accidentally removes code that is used by another feature. The "off" path of a flag may contain utility functions, components, or logic that other parts of the application use independently. Before deleting dead code, verify that nothing else imports or references it. Use the IDE's "Find Usages" or grep for the function/component name across the entire codebase, not just the files that contain the flag check.

LaunchDarkly targeting rules reference the flag being removed. Flags can be used as prerequisites for other flags (flag B only activates if flag A is on). Removing flag A without updating flag B's prerequisites breaks the targeting rules. Check the LaunchDarkly dashboard for prerequisite dependencies before removing any flag. Update dependent flags to remove the prerequisite before archiving the source flag.