Flag cleanup and flag debt

Why flag debt builds up

Every flag doubles the paths through a piece of code. Once a feature is on for everyone and stable, the off path is dead code, its tests test nothing real, and the flag check is a place where a wrong click could still turn the feature off. Teams whose agents create a flag for every change accumulate flags faster than anyone remembers to remove them.

Find stale flags

• On for everyone, for a while. flagger list --state on --json lists flags fully on; each flag's history shows when it got there.
• No longer in code. A flag is "in code" when an SDK registered it in that environment in the last 30 days. Each deploy's registration refreshes it, so a flag that stops being registered loses the mark after 30 days.
• Never in code. Flags an agent created through the API or MCP show "Not in code yet" in the console until a deploy registers them; one that never gets there is usually abandoned.

Remove a flag safely

1. Make sure the flag is on in production and has been stable.
2. Delete the flag check and the old code path, its entry in your flag declarations, and the off branch of its tests. This is a small, mechanical PR, a good task for a coding agent.
3. Deploy. Once no app registers the flag any more, archive it in the console. Archived flags are left out of the rules SDKs download, so a missed check falls back to off, which is why the code goes first.

Archiving is for people and admin tokens; agents can't archive flags.

Automated cleanup

In development Stale-flag detection that opens a cleanup PR for an agent to finish is in development. Today the "in code" and "not in code yet" marks plus each flag's history tell you what to remove.

FAQ

What is feature flag debt?

The cost of flags left in code after they've done their job: extra code paths, extra tests, and a switch that can still change behaviour by accident.

How do I clean up old feature flags?

Find flags that are fully on and stable, remove the check and the old code path, deploy, then archive the flag in your flag service.

When should a feature flag be removed?

Once it's been on for everyone long enough that you wouldn't turn it off, usually days to a few weeks. Long-lived operational flags, like kill switches for a dependency, are the exception.

Can an AI agent remove feature flags?

It can make the code change, which is the bulk of the work. In Flagger.gg, archiving the flag afterwards is done by a person or an admin token.