diff --git a/.claude/guidelines/terraform_style_guide.md b/.claude/guidelines/terraform_style_guide.md new file mode 100644 index 0000000..e12674f --- /dev/null +++ b/.claude/guidelines/terraform_style_guide.md @@ -0,0 +1,37 @@ +# Terraform Style Guide (Project Overrides) + +## Project status + +**Legacy compatibility mode.** This code is in production with real clients. It was written before the house Terraform style guide (``) was adopted. A V2 will refactor to current standards; until then, minimize churn. + + + +## Style-guide applicability (overrides global) + +The Terraform style guide applies to: + +- **New files** being added. +- **Bug fixes** — keep the fix minimal. Do not bundle stylistic cleanup. +- **Security findings** from checkov / trivy / terrascan — fix or consciously suppress with reason. + +The style guide does NOT apply to: + +- **Renaming existing resources** (requires `moved {}` blocks or `terraform state mv` — both blast-radius). +- **Restructuring existing files** to match the strict module layout. +- **Converting `count` → `for_each`** on existing resources (causes destroy/recreate). +- **Backfilling `description` / `type` / `sensitive`** on pre-existing variables/outputs unless the user explicitly asks. +- **Argument ordering changes** inside existing resource/variable/output blocks. + +## When a linter flags existing code + +1. **Do NOT auto-fix.** Surface the finding with `file:line`. +2. Propose **suppression first** (inline `# tflint-ignore:` / `# checkov:skip=: `), refactor second — and only on explicit user request. +3. Accumulated suppressions = breadcrumbs for the V2 migration. + +## Blast radius — additional rules for this repo + +Beyond the global rails: + +- `terraform state mv` / `rm` / `import` are **forbidden without a written migration plan in the PR description**. +- Resource renames require a `moved {}` block AND explicit user confirmation of `terraform plan` output before apply. +- Any refactor that changes resource addresses (module extraction, renaming, loop-style changes) is a V2 concern and should be flagged, not attempted. diff --git a/CLAUDE.md b/CLAUDE.md index db0ed5e..3632b60 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ References in the table below use these prefixes: |-----------|----------| | ALWAYS DO FOR ALL TASKS | `proj:variable_default_values.md` | | Any PR that changes deployer-visible behaviour (variables, component config, components added/removed) | `proj:changelog_protocol.md` | -| Writing or editing Terraform (`*.tf`, `terraform.tfvars`) | `proj:terraform_conventions.md` | +| Writing or editing Terraform (`*.tf`, `terraform.tfvars`) | `proj:terraform_conventions.md`, `proj:terraform_style_guide.md` | | Writing or editing Python | `proj:python_standards.md` | | Running, writing, or analysing tests | `proj:testing_strategy.md`, `proj:testing_commands.md` | | Working on security-sensitive code (secrets, IAM, SSM, certificates) | `proj:security_considerations.md` | @@ -75,7 +75,7 @@ For test commands and structured-logging tooling, see [`proj:testing_commands.md ## Project Structure ### Core Infrastructure (`*.tf` files) -Sequential numbered files defining infrastructure resources in dependency order. +Sequential numbered files defining infrastructure resources in (rough) dependency order. ### Python Scripts (`scripts/`) - `scripts/installer/validation/` - Configuration validation