Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Environment – configuration is what makes environments different from each other.

Context

This is an operational pattern that works hand-in-hand with Environment. Configuration is data that changes how your software behaves without changing its source code. Database connection strings, API keys, feature flags, log levels, timeout values, display settings: all of these are configuration. The same code, with different configuration, connects to different databases, enables different features, or behaves differently under load.

In agentic coding, configuration is one of the first things to get right. AI agents generate code quickly, and that code needs to connect to services, read credentials, and adapt to different contexts. If configuration is handled poorly (hardcoded values, secrets in source), the agent’s output creates security risks and operational headaches from day one.

Problem

You need the same application to behave differently in different contexts. Development should use a local database; production should use a managed cloud database. Staging should send emails to a test account; production should send to real users. How do you vary behavior across environments, deployments, and conditions without maintaining separate codebases?

Forces

  • Configuration must be easy to change without redeploying code.
  • Secrets (API keys, passwords) must be stored securely and never committed to Version Control.
  • Too many configuration options make a system hard to understand and debug.
  • Configuration errors can be just as catastrophic as code bugs. A wrong database URL can destroy data.

Solution

Externalize all environment-specific and deployment-specific values from your source code. Store them in environment variables, configuration files, secret managers, or a combination of these. Follow the principle from the Twelve-Factor App: configuration that varies between environments belongs in the environment, not in the code.

Layer your configuration with sensible defaults. The application should work with minimal configuration (reasonable defaults for development), and each environment overrides only what it needs to. This keeps individual configurations small and understandable.

Separate secrets from non-secret configuration. Secrets belong in a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password, or even encrypted environment variables), never in a config file committed to version control. Non-secret configuration (log levels, pagination sizes, feature names) can live in tracked config files.

Validate configuration at startup. If a required value is missing or malformed, fail fast with a clear error message rather than crashing mysteriously at runtime when the value is first used.

When directing an AI agent, specify how configuration should be handled: “Read the database URL from the DATABASE_URL environment variable. Do not hardcode any credentials. Use a .env.example file to document required variables.”

How It Plays Out

A developer hardcodes an API key in source code and commits it to a public repository. Within hours, the key is scraped and abused. The fix is immediate key rotation plus moving all secrets to environment variables loaded from a .env file that is listed in .gitignore.

A team uses a layered configuration approach: config/default.json provides sensible defaults, config/production.json overrides what is different in production, and environment variables override everything for secrets. Any developer can see what is configurable by reading the default file. Any operator can see what production changes by reading the production file.

Tip

When asking an agent to generate a new service or feature, always specify: “Create a .env.example file listing all required environment variables with placeholder values and comments explaining each one.” This documents your configuration from the start.

Example Prompt

“Move all hardcoded values — API keys, database URLs, feature flags — into environment variables. Create a .env.example file listing every required variable with placeholder values and a comment explaining each one.”

Consequences

Externalized configuration makes software portable across environments and deployable by operations teams who do not need to modify source code. It enables Feature Flags, environment-specific behavior, and clean Deployment pipelines.

The cost is one more thing to manage. Configuration drift, where environments have subtly different configurations, is a real source of bugs. Configuration must be documented, validated, and versioned (even if the values themselves aren’t in source control, the schema should be). And every new configuration option is a decision surface that someone can get wrong.

  • Depends on: Environment — configuration is what makes environments different from each other.
  • Enables: Feature Flag — feature flags are a specialized form of configuration.
  • Enables: Deployment — proper configuration makes deployment to different environments possible.
  • Used by: Internationalization — locale settings are a form of configuration.