AGENTS.md Template for Multi Availability Zone Architecture

Overview

Direct answer: This AGENTS.md Template provides a blueprint for coordinating AI coding agents to deploy and manage resources across multiple availability zones, with explicit agent roles, handoffs, tool governance, and rollback rules to ensure resilience and consistent configuration. It governs both single-agent execution and multi-agent orchestration across AZs.

The template describes an end-to-end workflow for multi-AZ architecture, including cross-AZ provisioning, data replication, health checks, and automated failover paths. It anchors all work in a single source-of-truth and a well-defined memory model so agents stay aligned even when operating across zones.

When to Use This AGENTS.md Template

• When you need automated provisioning and validation of resources across multiple availability zones.
• When cross-zone data replication and DNS failover must stay in sync with deployment changes.
• When you require explicit agent handoffs, guardrails, and escalation paths for resilience and security.
• When you want a copyable operating manual that can be pasted into a project-level AGENTS.md and reused for similar AZ patterns.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Multi-AZ Deployment Operator for AI coding agents.

Agent roster and responsibilities:
- Planner-Agent: designs cross-AZ deployment plan and sequencing.
- AZ1-Implementer: provisions resources and validates state in Availability Zone 1.
- AZ2-Implementer: provisions resources and validates state in Availability Zone 2.
- Failover-Coordinator: monitors health and orchestrates cross-AZ failover and recovery.
- Validator-Agent: validates IaC state, drift against plan, and runbook conformance.
- Security-Agent: enforces IAM, access policies, secrets handling, and least privilege.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, enforces idempotency, maintains a single source of truth, and triggers escalation if drift or failure is detected. It issues clear handoffs with status, intent, and checkpoints.

Handoff rules between agents:
- Planner → Implementers (AZ1 and AZ2) → Validator → Security → Failover-Coordinator → Reviewer.
- Implementers hand off to Validator after provisioning blocks complete; Validator passes to Orchestrator for drift checks.

Context, memory, and source-of-truth rules:
- All state lives in a central memory and a versioned state file, artifacts in infra/logs. The source of truth is the deployed state and the plan document, not chat.

Tool access and permission rules:
- Access via least privilege roles. Use Secrets Manager for credentials. Cloud APIs should be invoked through the orchestrator with scoped permissions.

Architecture rules:
- Deploy resources across at least two AZs with auto-failover readiness. Use cross-AZ load balancers, replicated databases, and replication as required. Ensure network paths for health checks and control plane communications are isolated and audited.

File structure rules:
- infra/
  - az1/
  - az2/
  - modules/
  - policies/
  - configs/
- docs/
- scripts/
- tests/
- logs/

Data, API, or integration rules when relevant:
- Use IaC for provisioning. Interact with cloud APIs only via the orchestrator. Do not call cloud services directly from agents unless allowed.

Validation rules:
- Run a plan before apply. Verify drift-free state after provisioning. Validate cross-AZ replication health and DNS failover readiness.

Security rules:
- Rotate credentials, enforce network segmentation, audit access, and monitor secrets usage. Secrets must never be logged.

Testing rules:
- Unit tests for IaC modules; integration tests across AZs; failover tests; drift detection tests.

Deployment rules:
- Changes require governance gate and canary or blue-green rollout.

Human review and escalation rules:
- Escalate to Platform or SRE for cross-AZ failures or security incidents.

Failure handling and rollback rules:
- Maintain a rollback plan to last known good state; automated rollback; log all changes.

Things Agents must not do:
- Do not bypass approvals or perform production changes without governance. Do not reveal secrets in logs.

Recommended Agent Operating Model

Roles and responsibilities: Planner determines the multi-AZ strategy; Implementers carry out cross-AZ provisioning; Validator checks state and drift; Security enforces governance; Failover-Coordinator manages cross-AZ health and disasters; Orchestrator ties it all together with clear decision boundaries and escalation paths.

Recommended Project Structure

infra/
  az1/
    main.tf
    variables.tf
    outputs.tf
  az2/
    main.tf
    variables.tf
  modules/
    common/
    networking/
    databases/
  policies/
  configs/
  tests/
  scripts/
logs/
docs/

Core Operating Principles

• Single source of truth for plan, state, and runbooks.
• Idempotent agent actions with deterministic outcomes.
• Explicit handoffs with verifiable checkpoints.
• Least privilege and auditable actions for all tools.
• Resilience through multi-AZ replication and graceful failover.

Agent Handoff and Collaboration Rules

Planner coordinates with Implementers; Implementers pass validation to Validator; Validator ensures compliance; Failover-Coordinator oversees cross-AZ recovery; Orchestrator enforces all rules and handles escalation when needed.

Tool Governance and Permission Rules

• Access only via approved roles and scopes.
• Secrets must be retrieved from a secure vault; do not store in logs.
• All cloud calls are audited and versioned.
• Changes requiring production access must pass approval gates.

Code Construction Rules

• All IaC modules must be versioned and tested with plan-before-apply.
• Use idempotent operations and avoid side effects outside the plan.
• Document resource dependencies and cross-AZ constraints in module README.

Security and Production Rules

• Enforce network segmentation and MFA for elevated actions.
• Rotate credentials on deploys and after incident events.
• Monitor access and alert on policy violations.

Testing Checklist

• Unit tests for IaC modules; integration tests across AZs; failover tests.
• Drift detection and drift remediation tests.
• Canary and blue-green validation before production rollout.

Common Mistakes to Avoid

• Skipping cross-AZ tests before applying changes.
• Hardcoding AZ-specific endpoints without fallbacks.
• Bypassing the governance gates or secret handling policies.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts 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 Multi AZ architecture?

It provides a copyable operating manual for AI coding agents to coordinate across AZs, ensuring resilience, guardrails, and clear handoffs.

How does multi-agent orchestration work across availability zones?

It defines roles (Planner, Implementers in AZs, Validator, Security, Failover-Coordinator) and an orchestrator that coordinates state, plans, and deployments across AZs with a single memory source of truth.

What are the key handoff rules between planner, implementers, and validator?

The Planner creates the plan; Implementers deploy in their AZs; Validator checks state and drift; Orchestrator moves to the next stage with verified checkpoints.

What security and governance rules apply to cross-AZ deployments?

Enforce least privilege, secrets in vaults, auditable access, and gated production changes with traceability to roles.

How is rollback and failure handled?

Rollback to the last known-good IaC state with automated rollback scripts and a tested runbook; escalate as needed.