AGENTS.md Template: Multi-Region System Design

Overview

Direct answer: This AGENTS.md Template governs a multi-region system design workflow where regional and global AI coding agents collaborate to design, validate, and govern cross-region architectures. It supports both single-agent execution and multi-agent orchestration by defining roles, handoffs, context memory, and tool governance rules.

The template provides an actionable operating manual that teams can paste into an AGENTS.md file to bootstrap a project-level operating context for multi-region designs.

When to Use This AGENTS.md Template

• Launching a distributed system design across multiple cloud regions (e.g., US-East, EU-West, APAC).
• Establishing cross-region governance for data residency, latency, and failover strategies.
• Coordinating planner, implementer, reviewer, tester, and domain specialist agents with explicit handoffs.
• Documenting tool access, permissions, and security constraints for the orchestration.

Copyable AGENTS.md Template

# AGENTS.md

# AGENTS.md Template for Multi-Region System Design

Project role: Systems Architect / Engineering Lead responsible for cross-region design and governance.

Agent roster and responsibilities:
- Planner: defines regional scope, horizons, and cross-region interfaces.
- Regional Engineers (region-specific): implement design details, satisfy local constraints, and validate region-level SLAs.
- Global Integrator: ensures coherence across regions, aligns with global standards, and manages end-to-end workflow.
- Security Auditor: reviews data residency, encryption, and access controls.
- Reliability Engineer: designs regional failover, replication, and DR testing.
- Domain Specialist (region-specific): provides regulatory, data-privacy, and domain controls for that region.

Supervisor / orchestrator behavior:
- The Global Integrator acts as the orchestrator, approving transitions between planning, implementation, and validation phases, and enabling cross-region handoffs.
- Issue escalation follows a defined channel to the program sponsor and architecture board.

Handoff rules between agents:
- Planner -> Regional Engineer: when regional scope is defined and interfaces are specified.
- Regional Engineer -> Global Integrator: when regional design is complete and cross-region implications are identified.
- Global Integrator -> Security Auditor: to validate security postures across regions.
- Security Auditor -> Reliability Engineer: after security validation to incorporate resilience requirements.
- Any handoff includes a shared design document update and a summary of decisions.

Context, memory, and source-of-truth rules:
- All decisions are recorded in a central DESIGN_DECISIONS.md file and linked from the main AGENTS.md.
- Reference architectures, diagrams, and data schemas live in /design and /docs.
- Memory is the current set of decisions, assumptions, and constraints; history is archived in /design/archives.

Tool access and permission rules:
- Agents may access the repository with role-based permissions; production system changes require a formal approval gate.
- Secrets are managed via a vault; avoid storing credentials in code.
- CI/CD pipelines must be triggered only through approved PRs.

Architecture rules:
- Use active-active or active-passive replication across regions; respect data residency requirements.
- Clear boundary definitions for regional services and shared services.
- Idempotent operations for cross-region actions.

File structure rules:
- /design: architecture decisions, diagrams, and cross-region interfaces.
- /design/regional: per-region design details.
- /docs: supporting documentation and runbooks.
- /tests: tests for region-specific and cross-region flows.
- /scripts: automation or orchestration helpers.

Data, API, or integration rules:
- Define per-region data schemas and a global schema where needed.
- Use secure, audited APIs; ensure consistent versioning across regions.

Validation rules:
- Validate cross-region latency targets, data replication success, and DR test outcomes.
- All critical changes require reviewer sign-off and automated tests.

Security rules:
- Enforce data residency, encryption at rest and in transit, and least privilege access.
- Secrets never embedded in code; rotate keys regularly.

Testing rules:
- Unit, integration, and cross-region end-to-end tests; include chaos testing for region failover.

Deployment rules:
- Deploy regional changes via controlled pipelines; regional rollouts require canary tests and monitoring.

Human review and escalation rules:
- All major design decisions require architecture review board approval.
- Escalate issues to the program sponsor if risks exceed threshold.

Failure handling and rollback rules:
- Define rollback steps for each cross-region change; preserve identity of resources for traceability.

Things Agents must not do:
- Do not bypass approvals or skip tests.
- Do not modify production systems directly; avoid secrets in code.
- Do not drift from the approved cross-region architecture.

Recommended Agent Operating Model

Roles and boundaries: Planner, Regional Engineers, Global Integrator, Security Auditor, Reliability Engineer, Domain Specialist. Decisions are bounded by documented cross-region interfaces and a shared DESIGN_DECISIONS.md. Escalations route to the Architecture Review Board when risk is high. The orchestrator routes work between agents to maintain coherence and prevent conflicts.

Recommended Project Structure

design/
├── regional/
│   ├── us-east-1/
│   ├── eu-west-1/
│   └── ap-southeast-1/
├── diagrams/
├── docs/
├── tests/
└── scripts/

Core Operating Principles

• Single source of truth: DESIGN_DECISIONS.md as the canonical memory.
• Clear ownership and explicit handoffs between agents.
• Idempotent, auditable actions with traceable changes.
• Defensive design for cross-region faults and data residency.

Agent Handoff and Collaboration Rules

Planner, Implementer, Reviewer, Tester, and Domain Specialist rules ensure explicit transitions, with the orchestrator enforcing guardrails and avoiding context drift.

Tool Governance and Permission Rules

• Commands and API calls require approval for production changes.
• Code edits must be done in PRs; secrets in vault only.
• Automations run in isolated environments; do not connect directly to production from agents.

Code Construction Rules

• All cross-region changes are encapsulated in modules with clear interfaces.
• Do not duplicate data; reuse shared services where possible.
• All inputs are validated; outputs are deterministic.

Security and Production Rules

• Enforce encryption, access control, and audit trails across regions.
• Limit blast radius; implement circuit breakers and failover guards.

Testing Checklist

• Unit tests for regional components.
• Integration tests for cross-region interactions.
• DR and failover testing; simulate regional outages.

Common Mistakes to Avoid

• Assuming global latency is uniform; plan for regional variance.
• Underestimating data residency constraints.
• Rushing cross-region deployments without validations.

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 AGENTS.md Template for multi-region system design?

It is a structured operating manual that codifies agent roles, handoffs, and governance for coordinating AI coding agents across regions.

Who approves cross-region design decisions?

The Global Integrator in collaboration with the Architecture Review Board signs off on changes affecting multiple regions.

How are region handoffs validated?

Through shared design documents, automated tests, and PR approvals before progressing to the next stage.

What happens on regional failure?

The orchestrator triggers cross-region failover workflows, validates state, and rolls back non-idempotent changes.

Where is the central memory stored?

In DESIGN_DECISIONS.md and related artifacts under /design with versioning and audit trails.