Feature flags instead of staging

Why skip the staging server?

A staging server is a second copy of production that is never quite the same: different data, different traffic, different settings. Bugs that only show up in production still reach production, and every release waits on a step that adds little.

When coding agents write a large share of the code, changes arrive faster and in smaller pieces. Merging each one, deploying it switched off and turning it on deliberately keeps that pace safe. The deploy and the release become two separate decisions.

So when the studio launches a new company, it creates no staging environment: no staging secrets, no staging subdomain, no staging database and no staging deploy step. Sign-in and payments are set up for production and local development only. Sandboxer and Transformer, which were built before this rule, ship behind the same flag system.

How does a flag move from off to on?

Each flag is in one of five states, and a feature usually moves through them in order:

Targets can be user ids, verified email addresses or workspace ids. Percentage rollouts are sticky: a user's bucket comes from a hash of the flag key and their user id, so raising the percentage only ever adds people. Target lists are kept whatever the state, so switching state never loses them.

Why are flags declared in code?

Every flag is declared in the app's code with a key, a description, an owner and a default. When the app starts, any declared flag that doesn't exist yet is added as off, and a state someone already set is never overwritten by a deploy. There is no way to create or delete a flag through the admin API.

That keeps the code and the flag list from drifting apart. A flag exists because some code checks it, and it goes away when that code is deleted.

What happens when something goes wrong?

The rule is off by default. A flag that is unknown, not yet loaded or hit an error counts as off, so a bad deploy or a slow database never turns on unfinished work by accident. Signed-out visitors and background jobs with no user only see flags that are fully on.

If a feature misbehaves after it's turned on, a kill switch sets the flag off in one call and keeps its targets, so it can be turned back on exactly as it was. Every change records who made it, when, the state before and after, and a note.

How do flags stay safe and private?

• The server decides. The server checks every flag and enforces it. The browser only hides what the server already refuses.
• Nothing extra reaches the browser. A signed-in user receives only the flags that are on for them. The full list and the targeting are never sent to anyone who isn't an admin.
• No secrets in flags. Flags hold state and targeting, never keys or tokens.
• Admins only. Changing a flag takes an admin session or an admin CLI login. Customer API keys never get flag access.

Checks are fast because they read an in-memory snapshot that refreshes every 5 seconds and right after any change, so a flag adds no network call to a request.

How do you test code behind a flag?

Both paths stay tested until the flag is removed. Three small helpers make that routine:

• withFlag(key, on, fn) runs one test with the flag forced on or off.
• setFlagOverride(key, on) forces a flag for a whole test file.
• bothFlagStates(key, fn) runs a test with the flag off, then on.

The last habit is the one teams most often skip: remove the flag when done. Once a feature is on for everyone and stable, delete the flag and the old code path, so the codebase doesn't fill up with switches nobody remembers.