Configuration Specification

Agent Prompt Snippet

Ensure the project has a configuration specification covering all config sources, their formats, precedence rules, required vs optional fields, and how to validate configuration at startup.

Purpose

A configuration specification documents everything a user or operator needs to know to configure software correctly. It defines the configuration sources (config files, environment variables, CLI flags), their formats, which settings are required vs. optional, what the valid values are, how conflicts between sources are resolved (precedence rules), and how configuration errors are reported.

Configuration is the seam between software and environment. Poorly specified configuration is one of the most common sources of production incidents: a configuration parameter that works in development silently behaves differently in production, a required parameter is omitted and the software fails at startup with a cryptic error, or two configuration sources contradict each other and the precedence rule is unknown.

The configuration specification is also a security document. It tells operators which settings should be treated as secrets (database passwords, API keys), which settings affect security posture (TLS modes, authentication bypass flags), and which settings should never be set in plaintext environment variables.

For CLI tools, the configuration specification is part of the product’s public contract. Users depend on it to automate and script the tool. Breaking changes to configuration require semantic versioning and deprecation notices.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Configures the tool correctly the first time; understands which settings affect behavior	Reads before first configuration; updates when adding new features that need config
Claude Code (AI Agent)	Needs to generate valid configuration files and environment setups	Reads spec before generating `.env` files or config templates; validates generated config against schema
Priya (Eng Lead)	Onboards engineers to new environments; standardizes config across team	Links from README and runbooks; enforces spec compliance in PR review
DevOps (CI Operator)	Provisions infrastructure configuration; writes environment-specific config files	Uses spec to write Kubernetes ConfigMaps, Terraform variables, and CI environment setup

What separates a good version from a bad one

Criterion 1: Every configuration key is typed with valid values documented

✓ Strong: “LOG_LEVEL (string, default: info): Log verbosity. Valid values: debug, info, warn, error. Invalid values are rejected at startup with a descriptive error. Case-insensitive. Setting debug in production logs request bodies and may expose PII — see Security Considerations §4.2.”

✗ Weak: “LOG_LEVEL: sets the log level.” (No type, no valid values, no default, no security note. Engineers must read the source code to understand this setting.)

Criterion 2: Precedence rules are explicit and tested

✓ Strong: “Configuration is applied in this precedence order (highest to lowest): (1) CLI flags, (2) environment variables, (3) project config file (specbase.yaml), (4) user config file (~/.config/specbase/config.yaml), (5) built-in defaults. Each source overrides the same key from lower-precedence sources. A CLI flag of --log-level debug always wins, even if LOG_LEVEL=error is set.”

✗ Weak: “The tool can be configured via config file or environment variables.” (Which wins when both are set? This is the question that causes production incidents.)

Criterion 3: Required vs. optional is explicit with startup behavior documented

✓ Strong: “Required at startup: DATABASE_URL, SESSION_SECRET. If either is absent, the process exits with code 1 and an error listing all missing required configuration: Fatal: missing required configuration: DATABASE_URL, SESSION_SECRET. Optional: CACHE_TTL (default: 300s). The process starts successfully without it.”

✗ Weak: “Some configuration is required.” (Which configuration? What error? Does it fail immediately or fail silently during first use?)

Criterion 4: Secrets are explicitly identified and handling is specified

✓ Strong: “Secret configuration (never log, never include in error messages, never commit to version control): DATABASE_URL, SESSION_SECRET, STRIPE_SECRET_KEY, SENDGRID_API_KEY. Secret values must be set via environment variable, not config file. Recommended: use a secrets manager (AWS Secrets Manager, Vault) and inject at runtime. The config spec validator will warn if secret keys are found in config files on disk.”

✗ Weak: “API keys should be kept secure.” (Which keys? How? Without explicit identification, engineers routinely commit secrets to version control “temporarily”.)

Common mistakes

Documenting only the happy path configuration. Configuration specs often document how to configure for success but not how to debug misconfiguration. Include: what the error message looks like for each invalid configuration, where to find configuration validation output, and how to print the effective configuration (all sources merged) for debugging.

No migration path for configuration changes. When configuration keys are renamed, removed, or their valid values change, users’ existing configurations break. Document deprecation notices, the transition period, and whether old keys are accepted with a warning.

Mixing configuration with code. Configuration that requires recompilation or redeployment to change is not configuration—it is a constant. True configuration is changed at runtime without touching code. The spec should only document actual runtime configuration.

No schema validation. A configuration spec that isn’t enforced by startup validation is advisory only. Provide a validate-config subcommand or startup validation that confirms all required keys are present and all values are within valid ranges before the service accepts traffic.

How to use this document

When to create it

Write the configuration specification before the first public release. For internal tools, write it when the second person uses the tool—that’s when configuration ambiguity first costs time. Keep it updated whenever a new configuration parameter is added.

Who owns it

The engineering team that maintains the software. Configuration spec changes should be reviewed with the same care as API changes—they may be breaking changes for existing users.

How AI agents should reference it

get_standard_docs(type="cli_tool", features=[])
→ config_spec in documents[]
→ agent reads config spec before generating configuration files or environment setups
→ agent validates generated config against documented keys and valid values
→ agent identifies which settings are secrets and should not appear in generated files

The prompt_snippet — “Ensure the project has a configuration specification covering all config sources, their formats, precedence rules, required vs optional fields, and how to validate configuration at startup” — tells the agent to check for all five dimensions.

How it connects to other documents

The Configuration Specification feeds the Installation Guide (which tells users how to configure for first run), the Security & Privacy Plan (which lists which configuration affects security posture), and the Architecture Overview (which describes what components exist and therefore what configuration namespaces are expected).