Environment & Config
This chapter defines where environment files live, how tooling is allowed to touch them, where tests may write, and how configuration is loaded and validated. The placement and loading rules are conditional on a project that uses environment files; the no-auto-destroy guarantee is always in force.
Environment File Placement
Section titled “Environment File Placement”| Rule | Requirement |
|---|---|
| Real values | The real .env MUST live in the parent directory above the repository, never inside the repository. |
| Committed sample | Only an .example.env carrying dummy values MAY be committed. |
| Paths | Environment values that reference the filesystem MUST use relative paths; absolute paths MUST NOT be committed. |
| Changes | You MUST NOT change the real .env lightly; treat it as a last resort and only with a verified reason. |
No Auto-Destroy
Section titled “No Auto-Destroy”Tooling MUST NOT silently overwrite or auto-delete a .env file. Before writing, a tool MUST check whether the file already exists; if it does, the tool MUST ask the human and MUST NOT replace existing content on its own. Cleanup routines MUST NOT remove .env files automatically.
Test Isolation
Section titled “Test Isolation”Tests MUST write only inside repository-internal directories. A test MUST NOT write into a user’s home folder or any location outside the repository, so that running the suite never mutates personal or machine-wide state.
Configuration Loading
Section titled “Configuration Loading”Configuration SHOULD be assembled once at boot by a single loader, rather than read ad hoc throughout the code. The loader MUST validate the resolved environment against a schema before the application proceeds, and MUST fail loudly when a value is missing or out of range.
| Constraint | Meaning |
|---|---|
type | The value MUST match the declared type. |
required | A required value MUST be present. |
min / max | A numeric or length-bounded value MUST fall within the stated range. |
enum | The value MUST be one of the allowed members. |
A loader that detects a schema violation MUST stop startup with a clear message rather than continue with an invalid configuration.