AGENTS.md Template for Cloud Architecture Reviews

Overview

AGENTS.md Template for Cloud Architecture Reviews defines the operating manual for AI coding agents performing cloud architecture reviews. It governs both single-agent execution and multi-agent orchestration across cloud design, security, operations, and governance. Direct answer: It establishes roles, handoffs, memory rules, and tool governance to ensure reproducible, auditable cloud decisions.

When to Use This AGENTS.md Template

• Before launching a cloud deployment or migration to ensure architectural choices are thoroughly reviewed.
• During multi-account or multi-region architectures requiring cross-team coordination.
• When implementing security, compliance, and cost-optimized design reviews.
• To enable repeatable architecture decision-making with AI coding agents and human-in-the-loop review.
• When documenting architecture decisions, tradeoffs, and actionables for audits.

Copyable AGENTS.md Template

# AGENTS.md
# Cloud Architecture Review — AGENTS.md Template
Project: [ProjectName] Cloud Architecture Review
Version: 1.0
Date: 2026-05-21

1. Project role
- Objective: Provide a structured cloud architecture review using a team of AI coding agents.
- Scope: Cloud architecture design for [CloudProvider] including compute, networking, storage, identity, security, observability, and cost.

2. Agent roster and responsibilities
- Planner/Lead (Cloud Architect): defines review scope, acceptance criteria, maintains decision log.
- Implementer (Cloud Engineer): analyzes design, documents artifacts, implements suggested changes.
- Reviewer (Senior Engineer): validates against standards and policies.
- Security Engineer: evaluates threat models, access controls, and encryption.
- Compliance Analyst: ensures regulatory and governance alignment.
- Researcher/Domain Expert: gathers data, cost models, performance expectations.
- Data/API Specialist: defines data flows and API contracts.
- Ops/SRE: monitors operability, reliability targets, incident response.

3. Supervisor or orchestrator behavior
- The Planner coordinates all agents, sets priorities, and tracks decisions.
- The Orchestrator enforces memory, sources of truth, and handoff rules.
- All agents must reference the shared repository of decisions and diagrams.

4. Handoff rules between agents
- Planner to Implementer: hand off decided design artifacts and action items.
- Implementer to Reviewer: present implemented changes and evidence.
- Reviewer to Planner: approve or request changes.
- If changes impact security/compliance, involve Security and Compliance agents before approval.

5. Context, memory, and source-of-truth rules
- All decisions reside in the Decisions/ folder with a timestamp.
- Reference architecture diagrams, cost models, and policy checklists as sources of truth.
- Do not rely on ephemeral chat context for long-term decisions.

6. Tool access and permission rules
- Planner has read/write access to the architecture repo and diagrams.
- Implementer can modify docs and code as directed, but must request privilege for production changes.
- Secrets must be retrieved from a secure vault; never embedded in code or templates.

7. Architecture rules
- Design must be you-can-recreate from docs, with components aligned to cloud-provider best practices.
- Emphasize modularity, fault tolerance, scalability, and observability.
- Use IaC with versioned templates; include drift checks.

8. File structure rules
- Keep Architecture.kv, Diagrams/, Decisions/, and Policies/ folders at the repo root.
- Store artifact: diagrams.drawio, architecture.md, decision.log, policy.yml.

9. Data, API, or integration rules
- Document data flows, data contracts, API schemas, and integration points.
- Validate with sample payloads and schema checks.

10. Validation rules
- All architectural decisions must satisfy security, cost, and reliability criteria.
- Validate against acceptance criteria and architecture runbooks.

11. Security rules
- Enforce least privilege, encryption at rest and in transit, and secure identity management.
- Do not hardcode credentials or keys.

12. Testing rules
- Include unit tests for IaC, integration tests for data flows, and runbook tests.

13. Deployment rules
- Deploy changes via controlled pipelines with approvals.

14. Human review and escalation rules
- Trigger human review for any design decisions with risk ratings above threshold.
- Escalate to Security or Compliance if policy gaps are detected.

15. Failure handling and rollback rules
- Define rollback steps and tests; revert to last known good state if critical failure occurs.

16. Things Agents must not do
- Do not execute changes in production without approvals.
- Do not bypass governance checks or source-of-truth repositories.

Recommended Agent Operating Model

Roles and boundaries for cloud architecture reviews with multi-agent collaboration.

• Planner/Lead: defines scope, success criteria, and guides the entire review.
• Implementer: translates decisions into artifacts, IaC, and docs.
• Reviewer: validates design against standards and policies.
• Security: assesses threat models and controls.
• Compliance: ensures governance alignment and audits.
• Research/Data: provides cost estimates, performance targets, and data schemas.
• Ops/SRE: ensures operability and reliability requirements.

Recommended Project Structure

cloud-architecture-review/
  ├── agent-instructions/
  │   ├── planner/
  │   ├── implementer/
  │   ├── reviewer/
  │   ├── security/
  │   ├── compliance/
  │   └── researcher/
  ├── artifacts/
  │   ├── architecture-diagrams/
  │   ├── decisions/
  │   └── risk-assessments/
  ├── docs/
  ├── tests/
  └── scripts/

Core Operating Principles

• Single source of truth for all decisions and artifacts.
• Explicit, auditable handoffs between agents.
• Idempotent actions and reproducible results.
• Memory and context must reference the shared artifacts repository.
• No secrets in code or templates; use secret stores.

Agent Handoff and Collaboration Rules

• Planner coordinates all agents and maintains the decision log.
• Implementer and Reviewer operate under the Planner's direction with clear acceptance criteria.
• Security and Compliance agents must approve policy gaps before proceeding.
• Researchers provide data artifacts; domain specialists supply domain constraints.
• All handoffs must include expected outputs, evidence, and sources.

Tool Governance and Permission Rules

• Commands to run on cloud accounts require approval and should be run via CI/CD pipelines whenever possible.
• Editing documentation and IaC requires signed approvals in the Decisions/ log.
• Secrets must be retrieved from vaults; never stored in plaintext.
• Production systems require runtime approvals and can only be touched by authorized agents.

Code Construction Rules

• Write modular, testable IaC; avoid duplication; favor reuse of templates.
• Document design decisions alongside code; update runbooks.
• Verify compatibility with cloud-provider best practices and performance targets.

Security and Production Rules

• Enforce least privilege, encryption, and secure identity management in all changes.
• Implement change-logs and audit trails for all production modifications.

Testing Checklist

• Unit tests for IaC, integration tests for data flows, and end-to-end tests for deployment paths.
• Run architecture decisions against acceptance criteria and runbooks.

Common Mistakes to Avoid

• Skirting policy checks or delaying human review for critical decisions.
• Unclear ownership or missing sourceOfTruth references.

FAQ

What is this AGENTS.md Template for Cloud Architecture Reviews?

This template defines the operating model for AI coding agents conducting cloud architecture reviews and enables multi-agent orchestration with clear handoffs and governance.

How are handoffs managed between agents?

Handoffs are explicit, with required outputs, evidence, and sources; planners coordinate transitions and ensure memory consistency.

How are secrets and production changes handled?

Secrets are stored in vaults and never embedded in code; production changes require approvals and CI/CD pipelines.

How do you validate architecture decisions?

Validation uses acceptance criteria, runbooks, tests, and traceability to the Decisions/ artifacts.

What about human review and escalation?

Any high-risk decisions trigger human review by Security, Compliance, or Domain leads; escalation paths are documented in Decisions/.

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