Ship features safely with a written flag spec
A feature flag is a runtime switch that decouples deploy from release. The risk is not the flag — it is the undocumented flag. Without a spec, no one remembers who the flag targets, what would trigger a rollback, or when it should be deleted. This builder turns those decisions into a short, shareable specification before the flag goes live.
How it works
The tool collects the fields every well-run flag needs and renders them as Markdown:
- Flag key + description — a stable identifier and a one-line statement of what it controls.
- Targeting rules — ordered conditions that decide who is enabled. Rules are evaluated top-down and the first match wins, so narrow overrides (internal staff) go above broad rules (random 10%).
- Rollout plan — the percentage ladder you will climb, with an explicit pause between steps to inspect metrics.
- Metrics to watch — a guardrail (error rate, latency) and a success metric. Each has a threshold that defines “roll back”.
- Cleanup date — the date by which the flag is removed or the feature becomes the permanent default.
Everything runs locally in your browser; nothing is uploaded.
Tips and example
Name flags by intent, not implementation: new_checkout_flow ages better than temp_fix_2. Always pair the flag with an owner so cleanup has a responsible person.
A safe rollout ladder for a user-facing change is 1% internal, then 5%, 25%, 50%, 100%, holding at each step long enough to gather a meaningful sample. Define the rollback rule numerically: “roll back if checkout error rate exceeds 1.5% or p95 latency exceeds 800ms”.
Set the cleanup date when you create the flag, not later — two to four weeks after reaching 100% is typical. A flag with no expiry is technical debt that compounds.