# Terraform: workspaces vs directory-per-environment, pick deliberately
## Why
Two patterns separate dev, staging, and prod, and they fail in opposite ways. `terraform workspace` keeps one config and switches the state file behind it. Directory-per-env keeps separate folders (often with Terragrunt or symlinks) and runs each independently.
## Workspaces
`terraform workspace new prod` creates a new state for the same config. The workspace name is available as `terraform.workspace` for naming resources. Backends that support it (S3, remote) store each workspace's state separately.
Failure mode: it is one `terraform workspace select` away from applying dev config to prod state. There is no guardrail in the tool. Backend config is shared, so a backend change affects all workspaces at once.
## Directory-per-env
Each environment is its own root module, often calling shared child modules. State, backend config, and variables are fully separate.
Failure mode: the glue (backend blocks, provider configs, variable files) gets copy-pasted and drifts. This is the pattern Terragrunt exists to fix.
## Rules for agents
1. Workspaces are fine for lightweight separation (feature branches, ephemeral envs). They are a poor fit for prod vs non-prod where the blast radius matters.
2. If you use workspaces, never interpolate `terraform.workspace` into anything that cannot be renamed later. Workspace names leak into resource names and tags.
3. Directory-per-env plus shared child modules plus Terragrunt (or symlinks) is the boring, safe choice for real environments.
4. Whichever you pick, the CI job must print which environment it targets before planning. "Which env am I about to touch" should never be ambiguous.