spb/ultra-sharp-agent-skills Public

1---2name: managing-configuration3description: Structures backend service configuration the 12-factor way — environment variables into one typed config object validated at startup, secrets kept out of code and VCS, per-environment overrides without per-environment code. Use when the user asks how to manage config, environment variables, .env files, secrets in a service, add a config setting, or fix per-environment behavior. Do not use for infrastructure provisioning (Terraform/CloudFormation) or CI/CD pipeline configuration.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Managing Configuration1213## When to use / when NOT to use14- **Use for:** application-level configuration: env vars, .env files, secrets handling, typed config objects, feature flags vs config.15- **Do NOT use for:** provisioning infrastructure (Terraform etc.) or CI/CD pipeline YAML — different lifecycles and tools.1617## Core rules18191. **All config comes from the environment** (12-factor). Code reads env vars; nothing environment-specific is baked into the artifact — the same image runs in dev, staging, and prod.202. **One typed config object, validated at startup.** Parse env once into a frozen, typed structure; every missing/invalid key crashes the boot with the key named.21   - ✅ `Settings()` raises `DATABASE_URL: field required` before serving22   - ❌ `os.environ["DATABASE_URL"]` scattered across 30 files, failing at first use in prod.233. **Secrets are not config.** Passwords, API keys, signing keys come from a secret manager or injected env at deploy time — never committed, never in Docker images, never logged. `.env` is for local dev only and gitignored.244. **No per-environment code paths.** Behavior differences are driven by config *values*, not environment *names*.25   - ✅ `if settings.payments_sandbox:` (set true in staging's env)26   - ❌ `if ENV == "staging": use_sandbox()` sprinkled through the codebase.275. **Defaults are safe for dev, explicit for prod.** Local dev works out of the box (localhost DB, DEBUG level); production values must be provided — a prod boot with dev defaults should fail validation (e.g., `SECRET_KEY` has no default).286. **`.env.example` is the single, current catalog** of every variable: name, purpose, example value, required/optional. A new variable isn't merged without its line.297. **Feature flags are not settings.** Flags are runtime-togglable and short-lived (removed after rollout); config is boot-time and long-lived. Don't grow a flag system inside your config object.3031## Workflow32331. Inventory every `os.environ` / `process.env` access; move each into the central typed config object.342. Classify each key: plain config vs secret; route secrets to the secret manager / injected env.353. Set dev defaults where safe; mark prod-critical keys as required (no default).364. Update `.env.example` with every key; gitignore `.env`; purge any committed secrets (and rotate them — history remembers).375. Validate: boot with one required var unset → assert the process exits naming that key; run `git log -p | grep -iE "api_key|secret|password"` and a repo scan (`gitleaks detect`) → must be clean.3839## Edge cases & failure modes40- **A secret was committed** → rotating the secret is mandatory; rewriting git history is optional. Treat it as leaked.41- **Config needed before the config system loads** (log level for the config parser itself) → read that one var directly, document the exception.42- **Multi-tenant / per-customer settings** → that's data, not config: store in the database, not env vars.43- **Large config values** (PEM certs) → mount as files and put the *path* in env; multiline env vars break tooling.44- **Different values per process in one deploy** (worker vs web concurrency) → separate variables (`WEB_CONCURRENCY`, `WORKER_CONCURRENCY`), not conditionals on process type.4546## References47Deeper recipes and gotchas: see [references/patterns.md](references/patterns.md)48