DevOps & Tooling · Any coding agent
Terraform & OpenTofu IaC ARCHITECTURE.md
An ARCHITECTURE.md for Terraform & OpenTofu IaC: module responsibilities, data flow and the boundaries code changes must keep.
- Path
- ARCHITECTURE.md
- Loads
- Read when referenced
- Format
- Markdown (.md)
- Used by
- Any coding agent
What this file tells the agent
ARCHITECTURE.md describes module responsibilities, state boundaries and data flow, so a coding agent knows where code belongs before it changes anything. Point to it from CLAUDE.md or AGENTS.md so agents read it.
- Pin explicit version constraints for all providers and required Terraform/OpenTofu core versions (required_providers).
- Store state securely in remote backends (S3 with DynamoDB state locking or GCS/Terraform Cloud); ban local terraform.tfstate.
- Enforce mandatory resource tagging (Environment, Project, Owner, ManagedBy) on all provisioned cloud assets.
- Never hardcode secrets, API keys, or master database passwords; inject via secure variables with sensitive = true or secret managers.
- Declare explicit lifecycle { prevent_destroy = true } blocks on critical production databases and storage buckets.
Code to avoid, and what to write instead
The rule steers the agent away from the left and toward the right.
# Dangerous: Hardcoded secret, no version lock, unmanaged state
resource "aws_db_instance" "bad_db" {
engine = "postgres"
password = "plaintextpassword123" # Leaked credentials in git!
}terraform {
required_version = ">= 1.7.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.40"
}
}
backend "s3" {
bucket = "corp-tf-state-prod"
key = "vpc/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}
resource "aws_db_instance" "primary" {
identifier = "app-db-prod"
allocated_storage = 50
engine = "postgres"
instance_class = "db.r6g.large"
password = var.db_password
skip_final_snapshot = false
lifecycle {
prevent_destroy = true
}
}Install it in one command
- 01
Go to your project root
The file goes at ARCHITECTURE.md, relative to the root.
- 02
Download the file
Run the command on the right. It downloads this preset and writes the file.
- 03
Make sure it gets used
Agents read it when your CLAUDE.md or AGENTS.md points to it. Add a line such as "Read ARCHITECTURE.md before structural changes".
$ curl -fsSL "https://www.devscratchpad.tech/api/raw/architecture-md/terraform-iac" -o "ARCHITECTURE.md"
writes ARCHITECTURE.md
ARCHITECTURE.md
To write the file from your own code instead, use Read your code or Convert Legacy Rules in the editor above.
More for Terraform & OpenTofu IaC
Questions
- What belongs in ARCHITECTURE.md?
- How the main modules relate, how state and data flow, and the boundaries every change must keep.
- How does ARCHITECTURE.md help AI agents?
- It tells them where code belongs and which boundaries to keep, so they are less likely to add circular dependencies or skip layers. Point to it from CLAUDE.md or AGENTS.md so they read it.