P3.EXP.001 — Environment and application configuration is documented explicitly¶

Field	Value
Principle	P3 (Shallow Explicitness)
Severity	`warn`
Evidence	`strong`
Stability	`experimental`

What it checks¶

This rule detects hidden configuration across multiple stacks and fires when documentation is missing:

1. `.env` files (Node, Python, Ruby, Go)¶

If the repository contains .env files, it must also have .env.example, .env.sample, or .env.template at the repository root.

2. Spring Boot profiles (Java/Kotlin)¶

If the repository contains application-*.yml, application-*.yaml, or application-*.properties files (profile-specific config), it must have config/README.md or docs/config.md documenting the profile differences.

3. Terraform variable files¶

If the repository contains *.tfvars files, it must have terraform.tfvars.example, example.tfvars, or sample.tfvars.

4. Rails environment configs (Ruby)¶

If the repository contains files under config/environments/, it must have config/README.md or docs/config.md documenting the environment differences.

Why it matters¶

P3 asks whether behaviour is visible without following hidden indirection. Configuration files — .env, Spring profiles, Terraform variables, Rails environments — affect runtime behaviour but their differences are invisible in the source tree without documentation. An agent has no way to know which settings differ between environments, what format they expect, or which are required.

When to care¶

Care always when the repo has any .env file, Spring Boot profiles, Terraform .tfvars, or Rails environment configs.
Care less for repos that use a typed config system as the primary config source. Even then, documenting the variables is cheap.

How to fix¶

For `.env` projects¶

Create .env.example at the repo root:

# Database connection
DATABASE_URL=postgres://localhost:5432/myapp_dev

# Authentication
SECRET_KEY=replace-me-with-a-real-secret

For Spring Boot projects¶

Create config/README.md documenting profile differences:

# Configuration profiles

| Profile | Database | Logging | Notes |
|---|---|---|---|
| `dev` | H2 in-memory | DEBUG | Hot reload enabled |
| `staging` | PostgreSQL | INFO | Mirrors prod |
| `prod` | PostgreSQL (RDS) | WARN | Read replicas |

For Terraform projects¶

Create terraform.tfvars.example:

ami_id        = "ami-12345678"
instance_type = "t3.micro"
environment   = "dev"

Suppressing this rule¶

ignore:
  - rule: P3.EXP.001
    reason: "Config is fully typed via Go structs; .env is only for local dev convenience"
    expires: 2027-01-01

History¶

0.3.0 — introduced at stability: experimental.
0.3.x — expanded to detect Spring Boot profiles, Terraform .tfvars, and Rails environment configs.