Documentation

Feature Flags for AI Coding Agents

A copy-paste AGENTS.md section that tells Claude Code, Codex, Cursor and other coding agents to ship every user-facing change behind a Flipper feature flag, test both paths, and leave the rollout to a person.

Coding agents write a lot of code quickly, and some of it will be wrong in ways tests don't catch. Merge it behind a feature flag and you get to try it in production yourself, then with a few customers, before everyone sees it. If something breaks, you turn the flag off instead of reverting and redeploying.

Agents follow the instructions in your repository. Add the section below to your AGENTS.md (or CLAUDE.md, .cursor/rules, or whatever file your agent reads), and every user-facing change it writes ships behind a flag.

The AGENTS.md section

## Feature flags

This app uses Flipper for feature flags.
Docs: https://www.flippercloud.io/docs

- Put every user-facing change behind a Flipper feature
  flag. Check it with `Flipper.enabled?(:flag_name, user)`
  so it can be rolled out per user.
- Name flags in snake_case: short and descriptive, with an
  area prefix when it helps (`billing_annual_plans`,
  `search_typo_tolerance`). No team, type, or ticket
  prefixes.
- Keep the old code path working until the flag is
  removed. Test both paths with `Flipper.enable` and
  `Flipper.disable`.
- Never enable or disable flags in production, migrations,
  or seeds. A person rolls the change out.
- When a flag has been fully enabled for 14 days, remove
  the check and the old code path in a separate change.

Adjust the details to fit your team. The names follow our naming guide, and the testing advice follows Testing.

Catch typos in flag names

Agents sometimes check a flag under a slightly different name than the one you created, and Flipper.enabled? quietly returns false for a flag that doesn't exist. Turn on the strict adapter in development and test so the mistake shows up right away:

Rails.application.configure do
  config.flipper.strict = Rails.env.local? && :warn
end

Rolling out agent-written changes

1. Merge and deploy with the flag off. Nothing changes for customers.
2. Enable it for yourself or your team as actors or a group, and use the feature in production.
3. Widen it with a percentage of actors, and watch your errors and metrics.
4. Enable it for everyone, then remove the flag.

More agent-written code also means more flags to keep track of. Flipper Cloud shows who changed each flag and when in its audit history, lets you assign owners and tags, and reports how often each flag is checked with telemetry, so you can tell which flags are ready to remove.