Configuration bugs are insidious: they often don't cause immediate errors, just wrong behavior. The service starts, everything looks fine, but it's pointing at the wrong database or using the wrong API key.
Claude Code helps set up config management that catches these problems at startup.
Validated configuration
Build a config module for this service. Requirements:
- Read all config from environment variables
- Validate at startup: fail fast if required vars are missing
- Type coercion: convert strings to numbers/booleans where needed
- Provide defaults for optional config
- Export a typed config object (no process.env scattered through the codebase)
Config needed: [list all env vars and their types/requirements]The "fail fast" requirement is the key one. Services that start successfully with missing config cause mysterious failures later. Fail at startup instead of at the moment the config is first used.
Config schema with Zod
Use Zod to validate the config. Schema:
- DATABASE_URL: string, URL format
- PORT: number, default 3000, range 1-65535
- LOG_LEVEL: enum ['debug', 'info', 'warn', 'error'], default 'info'
- API_KEY: string, min length 32
- FEATURE_FLAG_X: boolean, default false
On validation failure: log which variables failed and why, then exit.Zod gives you validation and TypeScript types in one shot. The error messages tell you exactly what's wrong with the config, not just "config invalid."
Environment-specific config
Add environment-specific configuration:
- Development: verbose logging, mock external services, shorter timeouts
- Testing: use in-memory/test databases, disable external calls
- Staging: production-like but with test data
- Production: strict validation, real services only
Pattern: base config merged with environment overrides.
Don't use separate .env files per environment — use a config object
that reads ENVIRONMENT variable and applies the right settings.Secrets vs config
Separate secrets from non-secret config:
- Secrets (API keys, tokens, passwords): never logged, never exported
- Config (ports, feature flags, URLs): can be logged on startup
Write a startup log that shows config but redacts secrets.
Format: "Starting with config: PORT=3000, LOG_LEVEL=info, API_KEY=[REDACTED]"The startup config log is useful for debugging deployment issues. But you need to redact secrets so they don't appear in your logs.
Config documentation
Generate a .env.example file that documents every config variable.
For each one:
- The variable name
- A description of what it does
- Whether it's required or optional
- The default value if optional
- Example value (not the real value)
This file should be committed to the repo.A well-maintained .env.example is the fastest onboarding document for new engineers. They clone the repo, copy .env.example to .env, fill in the blanks, and they're running.
Config patterns — validation, secrets handling, environment-specific setup — are in the Agent Prompt Playbook. $29.