| name | environment-management |
| description | Environment separation and configuration management for production applications. Use when: setting up dev/staging/production environments, managing environment variables, configuring secrets, adding feature flags, or deploying across environments.
|
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
Environment Management
Overview
Environment separation prevents development mistakes from reaching real users. Every change should pass through at least two environments before production. Configuration that varies between environments belongs in environment variables, never hardcoded.
When to Use
- Setting up a new project's environment structure
- Adding environment variables or secrets
- Configuring feature flags for staged rollout
- Setting up deployment pipelines
- Promoting changes between environments
- Reviewing environment security
When NOT to Use
- Throwaway scripts or one-off experiments
- Local-only tools that will never be deployed
- Prototype stage with no users (but plan for it)
Process
1. Environment Separation
| Environment | Purpose | Data | Deploys |
|---|
| Development | Local coding and debugging | Seed/mock data | On save (hot reload) |
| Staging | Pre-production validation | Anonymized production snapshot | On PR merge |
| Production | Real users, real data | Live data | Manual trigger or release tag |
Minimum viable: dev + production. Ideal: dev + staging + production.
2. Environment Variables
All configuration that varies by environment goes in env vars:
- Database URLs and connection strings
- API keys and third-party credentials (e.g.
OPENROUTER_API_KEY, STRIPE_SECRET_KEY)
- AI model assignments (e.g.
OPENROUTER_MODEL_FAST, OPENROUTER_MODEL_REASON)
- Log levels and debug flags
- Feature flags
- Service URLs (API base URL, CDN URL)
3. .env File Management
.env.example — Checked into repo with placeholder values. Documents every required variable..env.local / .env — Gitignored. Contains real values for local development.- Never commit
.env with real secrets. Ever.
Verify .gitignore includes: .env, .env.local, .env.*.local
4. Secrets Management
| Approach | When to Use |
|---|
| Environment variables | Minimum viable — all platforms support them |
| Platform secrets (Vercel env, Railway secrets) | Managed hosting — encrypted at rest |
| Secrets manager (AWS SSM, HashiCorp Vault) | Enterprise — rotation, audit trails, access control |
Never store secrets in: code, git history, CI logs, client-side bundles, or Slack messages.
5. Per-Environment Configuration
Development: Verbose logging, debug mode on, local database, mock external services, hot reload.
Staging: Production-like config, test/anonymized data, real external services (sandbox mode), CI/CD deployed.
Production: Minimal logging (info+error), debug off, real database, HTTPS enforced, error tracking active.
6. Feature Flags
Use for staged rollout and safe deployment.
Simple (small projects): Boolean env var (FEATURE_NEW_CHECKOUT=true). Toggle per environment.
Advanced (larger projects): Feature flag service (LaunchDarkly, Unleash, Flipt). Percentage rollout, user targeting, kill switch.
7. Database Per Environment
Never share a database between environments. One wrong query in dev wipes production data.
- Dev: local database (SQLite, local Postgres)
- Staging: separate cloud database with anonymized data
- Production: isolated, backed up, access-controlled
8. Deploy Pipeline
Dev deploys on push (automatic). Staging deploys on PR merge (automatic). Production deploys on release tag or manual approval (deliberate).
Common Rationalizations
| Rationalization | Reality |
|---|
| "One environment is fine for now" | Deploying untested changes to production is gambling with user data. |
| "I'll just use the production database for testing" | One wrong DELETE statement and you have lost real user data. |
| "Env vars are overkill" | Hardcoded config means redeploying to change a value. Env vars change without code changes. |
| "We'll add staging later" | Without staging, every deploy is a production experiment on real users. |
| "Secrets in code are fine, it's a private repo" | Private repos get forked, cloned, and shared. Secrets in code are secrets in every copy. |
Red Flags
- Production database URL hardcoded in source code
.env file committed to git with real secrets- No
.env.example documenting required variables
- Same database used for development and production
- No staging environment — dev ships straight to production
- Secrets visible in CI/CD logs
- Feature flags that are never cleaned up after full rollout
Verification
