how we build · part seven
Feature Flags
When to use them and when not to. The lifecycle from creation to cleanup. Gradual rollout. The cost of flags that live forever — and the discipline that prevents it.
When to use flags — and when not to
This is where meaning and risk are decoupled. Not every change needs a feature flag. Flags add complexity — conditional paths in the code, more configurations to test, cleanup work when the flag is removed. The benefit must justify the cost.
- Use flags for: new user-facing features (the primary use case), risky infrastructure changes where rollback speed matters, gradual rollouts where you want to observe a subset before enabling for all, A/B tests where two variants run simultaneously.
- Do not use flags for: bug fixes (ship directly — the fix is the flag), configuration changes (use environment variables), pure refactors that don't change behaviour, dependency updates. These changes go through the pipeline and deploy normally.
The decision to flag or not is made at the Epic level, not the story level. One flag per Epic is the default. The flag name matches the Feature Brief and Epic slugs: feature-exam-grading-grade-and-mark. The flag is wired in from the first commit — not retrofitted later.
The flag lifecycle
1 2 3 4 5
Create → Wire → Test → Enable → Clean up- Create — register the flag in the flag platform. Name it. Set it to off.
- Wire — wrap the new behaviour in the flag from the first commit. Both paths (flag on, flag off) must work.
- Test — the pipeline tests both paths. Staging confirms the flag-off path is the current behaviour and the flag-on path is the new behaviour.
- Enable — the release gate passes; the flag is turned on. Gradual rollout if appropriate.
- Clean up — after the prediction check confirms the feature is stable, remove the flag and the conditional code. The feature becomes permanent.
Flags that live forever are tech debt. A flag not cleaned up within 30 days of full enablement gets a JIRA ticket with a date. The flag is the temporary scaffolding; the feature is the building. Leaving scaffolding up indefinitely is a cost the next developer pays every time they read the code.