Terraform Infrastructure

Scenario

You maintain cloud infrastructure using Terraform.

The repository manages resources such as:

• networks;
• databases;
• compute services;
• storage;
• IAM configuration.

Infrastructure changes can create, modify, or destroy real cloud resources.

You want coding agents to treat Terraform changes differently from ordinary application code.

Repository Structure

infrastructure/
├── environments/
│   ├── staging/
│   └── production/
├── modules/
│   ├── database/
│   ├── network/
│   └── application/
├── versions.tf
├── providers.tf
└── AGENTS.md

AGENTS.md

# Infrastructure Instructions

## Terraform

- Follow the existing module and environment structure.
- Reuse existing modules before creating duplicate resource definitions.
- Keep environment-specific values in the repository's established environment configuration.

## Safety

- Do not apply Terraform changes automatically.
- Do not destroy, replace, import, or move infrastructure unless the task explicitly requires it.
- Treat changes affecting production resources as high-impact.

## Secrets

- Do not commit cloud credentials, passwords, private keys, or secret values.
- Use the repository's existing secret-management mechanism.

## Validation

After Terraform changes:

- run `terraform fmt`;
- run `terraform validate`;
- inspect the relevant `terraform plan` when the environment and credentials are available.

Review the plan for unexpected:

- resource destruction;
- resource replacement;
- permission changes;
- networking changes.

## IAM

- Preserve least-privilege patterns.
- Do not broaden permissions to `*` merely to resolve an authorization failure.
- Follow existing role and policy boundaries.

## State

- Do not manually edit Terraform state.
- Follow the repository's established state migration workflow when state operations are intentionally required.

What This Does

This recognizes that Terraform source code can directly affect infrastructure.

A small-looking change such as:

instance_type = "..."

may cause:

in-place update

or:

resource replacement

depending on the resource.

That is why the workflow includes:

edit
 ↓
format
 ↓
validate
 ↓
plan
 ↓
inspect
 ↓
apply through approved workflow

rather than automatically applying the change.

What This Does NOT Do

The instructions do not prohibit infrastructure changes.

They separate:

preparing and validating infrastructure code

from:

executing high-impact changes against real environments

The file also does not assume that a successful terraform validate means the infrastructure change is safe.

Validation checks configuration correctness.

The plan reveals intended resource changes.

Why These Instructions Matter

Consider an agent changing:

resource "aws_db_instance" "main" {
  ...
}

A configuration change may cause Terraform to report:

-/+ destroy and then create replacement

If the agent looks only at source code, that consequence may not be obvious.

The plan is therefore an important part of reasoning about the change.

IAM changes deserve similar caution.

Suppose an application receives an authorization error.

A tempting fix is:

actions   = ["*"]
resources = ["*"]

The application may work afterward, but the permission model has been dramatically weakened.

Key Decisions

Plan before execution

Infrastructure code describes desired state, but the plan shows how Terraform intends to reach that state.

Don't automatically apply

Application tests are usually reversible.

Destroying or replacing infrastructure may not be.

Preserve least privilege

Authorization problems should be solved by identifying the required permission, not granting unrestricted access.

Protect state

Terraform state represents the mapping between configuration and real resources.

Manual edits can create serious inconsistencies.

Reuse modules

Duplicating resource definitions can create inconsistent infrastructure patterns.

When to Use This Pattern

Use this pattern when:

• Terraform manages real infrastructure;
• production resources are represented in code;
• IAM policies are maintained;
• state is remotely managed;
• agents may prepare infrastructure changes.

Infrastructure instructions should make the difference between editing code and changing live systems explicit.