--- inclusion: always --- # Safe and Reversible Shipping These conventions apply on every interaction. They exist so that risky changes can be shipped dark, isolated, and reverted without disrupting production. Follow them whenever you write code, define environments, or commit changes. ## 1. Feature-flag every new or changed behavior Wrap each code path that introduces new externally-visible behavior or modifies existing production behavior in a `Feature_Flag` that defaults to **disabled**. This decouples deployment from release: code ships turned off and is enabled or disabled at runtime without a redeploy. - A new flag's default state is always disabled — never enabled on creation. - Prefer a single, clearly named flag per behavior over broad, multi-purpose toggles. - Pure refactors with no externally-visible or production-behavior change do not require a flag. ## 2. Express every environment as Infrastructure_As_Code Express every deployable environment as `Infrastructure_As_Code` so that each environment can be provisioned and destroyed reproducibly, supporting disposable sandboxes. - Environments are defined in machine-readable, version-controlled definitions — not created or mutated by hand. - Every environment must be reproducible from its definition and fully destroyable, leaving no residual state. ## 3. Work on a feature branch, never on main Perform all work on a feature branch that is distinct from the `main` branch. - Create or switch to a feature branch before making changes. - The `main` branch is never a working branch. ## 4. Redirect any direct-to-main change If a change would be committed directly to the `main` branch, redirect the change to a feature branch and leave `main` unmodified. - Stop before writing to `main`, move the change onto a feature branch, and confirm `main` is left untouched. ## 5. Track every feature flag For each `Feature_Flag`, record an **owner**, a **creation date**, and an explicit **removal condition** in a tracked location. Maintain these records using the Feature-Flag Tracking Record schema below. ### Feature-Flag Tracking Record Keep a version-controlled record (for example, `feature-flags.md`) with one row per flag: ```markdown # Feature Flags | Flag | Owner | Created | Removal Condition | State (enabled/disabled) | | ---- | ----- | ------- | ----------------- | ------------------------ | ``` - **Flag** — the flag's identifier as used in code. - **Owner** — the person or team accountable for the flag. - **Created** — the flag's creation date. - **Removal Condition** — the explicit, checkable condition under which the flag and its code path will be removed (for example, "permanently enabled after GA" or "permanently disabled after rollback validated"). - **State** — the flag's current state: `enabled` or `disabled` (new flags start `disabled`). Add the record entry when the flag is introduced, and keep the State column current. ## 6. Remove flags once their removal condition is met When a `Feature_Flag`'s removal condition is met — because the flag has become permanently enabled or permanently disabled — remove the `Feature_Flag` together with its associated dead code path. - Delete the flag check and the now-unreachable branch it guarded, leaving only the surviving behavior. - Remove the flag's row from the Feature-Flag Tracking Record. - Leave no dormant flag or dead code path behind.