AGENTS.md Template: Terraform Production Architecture

Overview

Direct answer: This AGENTS.md template governs Terraform production architecture workflows for AI coding agents and multi-agent orchestration, defining roles, memory, handoffs, backends, and governance to operate safely in production.

This AGENTS.md template serves as a project-level operating context for single-agent and multi-agent Terraform workflows. It codifies the agent roster, source of truth, and collaboration rules that keep infrastructure changes auditable, reversible, and auditable.

When to Use This AGENTS.md Template

• When standardizing Terraform production workflows across a multi-agent orchestration system.
• When enforcing tool governance, state management, and approval gates in IaC pipelines.
• When migrating from ad-hoc IaC changes to a reproducible, auditable runtime.
• When onboarding new agents (planner, implementer, reviewer, tester, researcher, domain specialist).

Copyable AGENTS.md Template

# AGENTS.md
Project role: Terraform production architecture steward for AI coding agents.

Agent roster and responsibilities:
- Planner: designs the intended Terraform state and architecture, prepares plan commands, defines inputs/outputs, and creates the initial Terraform code structure.
- Implementer: translates planner intents into Terraform configuration, modules, and backend settings; applies changes in a controlled, auditable manner.
- Reviewer: validates plan output, adherence to policy, and risk assessment; ensures changes meet security and compliance requirements.
- Researcher: gathers cloud constraints, limits, and provider updates; tracks drift and recommends cost-optimized alternatives.
- Domain Specialist: ensures security, compliance, and domain-specific controls are met (secret management, access control, governance).

Supervisor or orchestrator behavior:
- The orchestrator enforces the plan/apply cycle, requires approvals for prod changes, and coordinates handoffs between agents.
- Maintains a single source of truth for state management and backends; propagates context to downstream tasks.

Handoff rules between agents:
- Planner -> Implementer: pass intents, inputs, and constraints.
- Implementer -> Reviewer: present generated plan, risks, and changes for approval.
- Reviewer -> Implementer: return approved changes with any required adjustments.
- Implementer -> Tester: guide deployment tests and validation steps before production.
- Tester -> Planner: report test results and any defects.

Context, memory, and source-of-truth rules:
- All Terraform state is stored remotely with backend locking; the planner and orchestrator reference a single source of truth.
- Use a versioned code repository as the primary memory; avoid untracked local edits.
- Source-of-truth for parameters is the repository with environment-specific overrides.

Tool access and permission rules:
- Agents may run Terraform CLI with read/write access only to configured workspaces in prod.
- Secrets and provider credentials are retrieved from a centralized vault; never hard-code credentials.
- Backend configuration must point to a restricted remote state bucket with state locking enabled.

Architecture rules:
- Use modular Terraform structure with clearly defined modules for network, compute, and IAM.
- Enforce remote backends and consistent provider versions; pin versions where appropriate.
- Use version-controlled modules and environment-specific overrides.

File structure rules:
- infrastructure/
- infrastructure/modules/
- infrastructure/environments/prod/
- infrastructure/environments/prod/main.tf
- infrastructure/environments/prod/backend.tf
- infrastructure/environments/prod/variables.tf

Data, API, or integration rules when relevant:
- All cloud provider API calls must pass through the Terraform provider and be version pinned.
- Any external data sources must be treated as read-only in production runs.

Validation rules:
- Run terraform fmt, terraform validate, and terraform plan before any apply.
- All changes must be approved by the Reviewer before apply.

Security rules:
- Secrets must be stored in a vault; do not store secrets in code or state files.
- Access to prod workspaces requires least-privilege roles and MFA where supported.

Testing rules:
- Use infrastructure tests where possible to verify network and IAM behavior.
- Validate that plan matches the intended architecture and that no drift exists post-apply.

Deployment rules:
- All changes go through CI/CD gates; apply only in prod after approval and successful tests.
- Monitor deployment and roll back on failure using a validated rollback plan.

Human review and escalation rules:
- Escalate security concerns to Domain Specialist and Paas or Security Ops as required.
- If critical issues are detected, halt changes and revert to last known good state.

Failure handling and rollback rules:
- If a deployment fails, revert state changes and re-run validation against the last-good plan.
- Keep a changelog of failures and fixes for audit.

Things Agents must not do:
- Do not apply changes without an approved plan.
- Do not access prod secrets directly; use vaults and permissioned roles.
- Do not drift from the centralized source of truth or bypass backends.

Recommended Agent Operating Model

Roles and decision boundaries: Planner decides on the desired Terraform state; Implementer translates into code; Reviewer approves; Tester validates; Researcher informs constraints; Domain Specialist ensures security and compliance. Escalation paths: if any actor detects risk, escalate to Supervisor and Security.

Recommended Project Structure

infrastructure/
  modules/
    network/
    compute/
  environments/
    prod/
      main.tf
      backend.tf
      variables.tf
  scripts/

Core Operating Principles

• Single source of truth for Terraform state with remote backend; all agents reference it.
• Idempotent changes; plan-first approach with strict approvals for production.
• Least privilege for all tools and credentials; secrets stored in vaults.
• Auditability; every change is traceable to a specific agent and decision.
• Clear handoffs and deterministic workflows to avoid context drift.

Agent Handoff and Collaboration Rules

• Planner communicates intent with constraints and expected outputs.
• Implementer carries out code changes and prepares plan for review.
• Reviewer checks policy compliance, risk, and drift potential.
• Tester validates deployment in a staging-like environment before prod.
• Researcher updates constraints and provider data as needed.
• Domain Specialist ensures security and governance alignment.

Tool Governance and Permission Rules

• CLI access restricted to prod workspaces with MFA and role-based access.
• Secrets retrieved from vault; never embedded in code or state.
• Backend state must be remote and locked; encryption at rest.
• Approvals required before production apply; automated checks enforced.

Code Construction Rules

• Modularize Terraform into networks, compute, and IAM modules with clear inputs and outputs.
• Pin provider versions and module versions; use version constraints.
• Environment-specific overrides stored in separate files and Git branches.

Security and Production Rules

• Use vault-backed secrets; do not store secrets in code or state.
• Require audit logs for all production changes; protect against drift.
• Enforce network segmentation and least privilege throughout the stack.

Testing Checklist

• terraform fmt, terraform validate, and terraform plan in CI.
• Infrastructure tests for network and IAM behavior; fail on drift.
• End-to-end deployment tests in staging prior to prod.

Common Mistakes to Avoid

• Omitting remote state locking or misconfiguring backend.
• Hard-coding secrets or credentials in code or state.
• Skipping approvals for production changes.
• Drifting architecture due to untracked manual edits.
• Ignoring dependency changes across modules.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts.

FAQ

What is the goal of this AGENTS.md template for Terraform production architecture?

It defines agent roles, memory, sources of truth, and handoff rules to govern Terraform plan/apply cycles and state management.

How is Terraform state and backend managed in a multi-agent workflow?

State is stored in a remote backend with locking; a state manager ensures proper configuration, least-privilege access, and drift detection.

How are agent handoffs and escalations handled?

Handoffs follow Planner -> Implementer -> Reviewer -> Tester, with escalations to Supervisor for approvals and security reviews when required.

What security or secret management rules apply?

Secrets are stored in a vault; do not embed credentials in code or state; enforce least privilege.

What testing and deployment checks are required?

CI should run terraform fmt, validate, and plan; require approved production applies and post-deployment validation.