AGENTS.md Template for Infrastructure as Code Reviews

Overview

This AGENTS.md template governs an infrastructure as code (IaC) review workflow using AI coding agents. It supports both a single-agent operating model and a multi-agent orchestration pattern, ensuring auditable decisions, clear handoffs, and tool governance across Terraform, CloudFormation, and other IaC technologies.

Direct answer: Use this AGENTS.md Template to establish a repeatable, auditable IaC review process with defined roles, orchestrator rules, and strict escalation and rollback paths.

When to Use This AGENTS.md Template

• When you need a structured IaC review that spans multiple tools and environments.
• When governance requires explicit agent roles, handoffs, and an orchestrator to coordinate tasks.
• When you must capture a reproducible IaC review process for compliance and security audits.
• When you want a scalable template that works for both single-agent and multi-agent workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project: Infrastructure as Code Review Orchestrator

Agent roster:
- Planner Agent: defines scope, acceptance criteria, and review plan.
- Implementer Agent: extracts IaC changes, applies transformations, and prepares execution steps.
- Reviewer Agent: checks compliance, security posture, and cloud governance.
- Researcher Agent: fetches standards, guidelines, and module patterns.
- Domain Specialist Agent: Cloud Architect/Security Engineer for risk assessment.
- Tester Agent: validates changes in a sandbox environment.
- Orchestrator Agent: supervises, coordinates handoffs, and enforces governance.

Supervisor / Orchestrator behavior:
- Issue tasks to roster based on the plan.
- Collect outputs and determine readiness to hand off.
- Require human review for high-risk changes.
- Maintain a shared memory/context store for traceability.

Handoff rules:
- Implementer passes to Reviewer after transformation.
- Reviewer validates, then passes to Tester.
- Tester confirms in staging before final apply.
- Orchestrator handles rollback triggers if failures occur.

Context, memory, and source-of-truth:
- Context lives in a persistent context store (context.json) and is versioned in the IaC repo.
- Source of Truth is the Git repository and the IaC state in the target environment.
- Outputs and decisions reference the latest plan ID.

Tool access and permission rules:
- Agents have scoped API keys with least privilege.
- Secrets never appear in logs or outputs; use a secrets manager.
- Access to cloud accounts is restricted to approved roles.

Architecture rules:
- Idempotent, declarative changes only.
- All changes must be traceable to a plan and a commit.
- Use modular IaC patterns and reusable modules.

File structure rules:
- All IaC code lives under infra/.
- Each module has a dedicated folder and tests.
- Review notes go under infra/reviews/.

Data, API, or integration rules:
- All API calls must be auditable and rate-limited.
- External service calls require explicit approvals.

Validation rules:
- Run fmt, validate, and plan; ensure no syntax errors.
- Run security checks (tfsec, terrascan) and lints.
- Capture drift and reconcile where appropriate.

Security rules:
- Never embed credentials in code or logs.
- Use environment isolation for reviews.
- Enforce least privilege for all resources.

Testing rules:
- Unit tests for modules, integration tests for provider interactions.
- End-to-end tests in CI that simulate real deployments.

Deployment rules:
- Approvals required for production apply.
- Apply only after successful plan and review.
- Changes must be auditable in repository history.

Human review and escalation rules:
- Escalate high-risk findings to Security and Cloud Architect.
- Document all escalations with rationale.

Failure handling and rollback rules:
- If deployment fails, rollback to last known-good state and notify stakeholders.
- Preserve failure logs for analysis.

Things Agents must not do:
- Do not perform destructive changes without explicit approval.
- Do not bypass validations or bypass the orchestrator.
- Do not share secrets or access outside approved channels.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined for robust IaC governance. The Planner establishes scope, the Orchestrator enforces rules, Implementer executes changes, Reviewer ensures compliance, and Tester validates in staging. Domain Specialists provide risk guidance when needed.

Recommended Project Structure

Workflow-specific directory tree:

infra/
  modules/
    network/
    compute/
  reviews/
    plan/
    security/
  orchestrator/
  tests/
  docs/
  pipelines/
  scripts/

Core Operating Principles

• Single source of truth and traceable changes.
• Idempotent, declarative IaC changes only.
• Clear ownership and auditable handoffs.
• Security-first, secrets managed externally.
• Automated validations and auditable records.

Agent Handoff and Collaboration Rules

Planner ➜ Implementer ➜ Reviewer ➜ Tester; Domain Specialist participates on risk findings; Orchestrator coordinates all handoffs and rollbacks as needed.

Tool Governance and Permission Rules

• Execute commands only through approved tooling and CI pipelines.
• Edits must go through pull requests in the repository.
• All API calls must be authenticated and logged.
• Secrets must be retrieved from a secrets manager; do not log them.
• Production access requires explicit approvals and governance gates.

Code Construction Rules

Use modular IaC patterns, clear naming, and strictly declare dependencies. Avoid ad-hoc changes in main modules and favor reusable modules and templates with version pinning.

Security and Production Rules

• Enforce least privilege and network segmentation.
• Isolate review environments from production.
• Audit all changes and maintain a risk register for production deployments.

Testing Checklist

• lint, fmt, validate; plan and preview in a sandbox.
• Run security scans and policy checks (tfsec, terrascan).
• Run end-to-end tests in staging before production apply.

Common Mistakes to Avoid

• Skipping security and compliance checks in IaC reviews.
• Applying changes to production without proper approvals.
• Overloading the planner with non-governed tasks.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template for IaC reviews?

This AGENTS.md Template defines a repeatable, auditable workflow for infrastructure as code reviews using AI coding agents and multi-agent orchestration.

Who should use this IAAC AGENTS.md Template?

DevOps, Platform Engineers, and engineering leaders who implement IaC governance and review workflows.

What are the main agent roles and how do they hand off work?

Planner defines scope, Implementer executes changes, Reviewer validates, Tester tests, Domain Specialist provides risk guidance, Orchestrator coordinates and handles rollbacks.

How are secrets and sensitive data protected?

Secrets are stored in a secrets manager; never written to logs or code; access is restricted by least privilege.

What constitutes a successful IaC review in this template?

A validated plan, security checks pass, no drift, and a staging deployment that passes tests before production apply with proper approvals.