AGENTS.md Template: MySQL Production Architecture

Overview

Direct answer: This AGENTS.md template defines the operating manual for AI coding agents coordinating a MySQL production architecture. It governs a structured workflow for provisioning, configuration, backups, failover, monitoring, and change governance, supporting both single-agent and multi-agent orchestration.

The template anchors project level operating context for both individual agents and multi-agent teams. It clarifies roles, handoffs, source of truth, and governance boundaries to prevent context drift and architecture drift in production environments.

When to Use This AGENTS.md Template

Use when you need a repeatable, auditable operating manual for a MySQL production architecture managed by AI coding agents.
When you want explicit handoff rules between planner, implementer, reviewer, tester, and DBA domain specialists.
When multi-agent orchestration is required to govern provisioning, backups, failover, and performance tuning.
When tool governance, security, and compliance constraints must be codified and enforced automatically.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- You are a MySQL Production Agent Orchestrator, responsible for ensuring high availability, data integrity, and performance across a multi node production architecture.

Agent Roster
- Planner: designs topology, replication, failover criteria.
- Implementer: applies migrations, config changes, and backup strategies.
- DBA Researcher: monitors queries, indexes, and performance.
- Monitor: collects metrics, dashboards, SLOs.
- Reviewer: validates outputs and artifacts.
- Tester: runs tests against staging and canary deployments.

Supervisor or Orchestrator
- The Orchestrator coordinates tasks, enforces SOPs, and triggers escalation when risk thresholds are reached.

Handoff Rules
- When Planner completes a plan it hands off artifacts to Implementer with acceptance criteria and SLAs. Implementer must deliver outputs before the next step. If not, escalate.

Context Memory and Source of Truth
- All artifacts live in the central repo or artifact store. The single source of truth is the db-schema, infra-topology, and policy documents. Agents should reference these sources for decisions.

Tool Access and Permissions
- Access to secrets, DB endpoints, monitoring, and CI/CD; use least privilege and rotate credentials.

Architecture Rules
- MySQL production architecture with 3 primary nodes, replication to read replicas, automated backups, and disaster recovery.

File Structure Rules
- Store artifacts under docs or agents directories; avoid duplicating data.

Data API or Integration Rules
- Use internal APIs to fetch topology; never edit production settings directly without planner approval.

Validation Rules
- Validate schema migrations, perform dry runs, and run canaries where possible.

Security Rules
- TLS everywhere, encryption at rest, secrets rotated, production changes require on call approvals.

Testing Rules
- Unit tests for SQL generation; integration tests for topology changes; end to end validation.

Deployment Rules
- Blue/Green deployment or canary where feasible. All production deployments require sign off.

Human Review and Escalation Rules
- On high risk changes, escalate to on call engineer and security auditor.

Failure Handling and Rollback Rules
- Rollback scripts, revert to last known good state, and pause production changes on failure.

Things Agents Must Not Do
- Do not bypass approvals, do not modify production without plan and test evidence.

Recommended Agent Operating Model

The operating model designates four core roles and two supporting roles to govern MySQL production with multi-agent orchestration.

Planner: defines topology, replication, sharding if any, backup windows, and DR runbooks. Sets acceptance criteria for artifacts.
Implementer: applies configuration changes, executes migrations, and updates infrastructure as defined by Planner. Produces artifacts and runbooks.
Reviewer: audits outputs, validates SQL, ensures policy conformance, and signs off before deployment.
Tester: validates in staging, performs canary checks, and simulates failure modes to verify rollback procedures.
DBA Domain Specialist: provides expert input on query tuning, index strategy, and schema evolution constraints.
Orchestrator: coordinates all agents, enforces SOPs, and triggers escalation when risk thresholds are crossed.

Recommended Project Structure

Workflow specific directory tree to support single and multi-agent execution while keeping governance artifacts organized.

mysql-prod-architecture/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    dba-domain/
    security-auditor/
  configs/
  scripts/
  monitors/
  docs/
  tests/
  topology/
  policies/

Core Operating Principles

Single source of truth for topology, policies, and schema changes
Handoffs governed by formal acceptance criteria and SLAs
Least privilege and explicit approvals for all production changes
Automated validation, testing, and rollback capabilities
End-to-end traceability of decisions and outputs

Agent Handoff and Collaboration Rules

Planner to Implementer: hand off plan artifacts, topology specs, and acceptance criteria
Implementer to Reviewer: deliver artifacts, changes, and test results for validation
Reviewer to Tester: provide test plan and results; tester validates against staging and canary envs
Researcher to Domain Specialist: share findings on workload patterns and indexing strategies
Domain Specialist to Planner: provide constraints and recommendations that shape future plans

Tool Governance and Permission Rules

Command execution restricted to approved scripts with role-based access
Config edits require Planner sign-off and automated validation
Secrets access restricted with short-lived tokens; rotate regularly
Production API calls require approval gates and audit trails
External service calls must be reviewed for security and compliance
All changes must pass validation and be approved before deployment

Code Construction Rules

SQL migrations must be idempotent and reversible
All scripts should be auditable with version control
Outputs must include test results, rollbacks, and recovery steps
Avoid runtime speculation without verified data or plan

Security and Production Rules

Enforce TLS for all connections to MySQL nodes and management endpoints
Encrypt data at rest and rotate secrets regularly
Follow least privilege; no production access without explicit role
Changes to production require on-call security and DBA sign-off

Testing Checklist

Unit tests for SQL generation and migration scripts
Integration tests for topology changes in staging
Canary tests and rollback verification
End-to-end tests covering provisioning, backup, and failover
Migration dry runs and schema validations

Common Mistakes to Avoid

Skipping formal handoffs and acceptance criteria
Bypassing approvals for production changes
Ignoring topology drift or secret rotation gaps
Introducing untested changes into production
Over-reliance on a single agent without failover plans

FAQ

What is the purpose of this AGENTS.md Template for MySQL production architecture?

It provides a copyable AGENTS.md template and operating manual to coordinate AI coding agents for provisioning, backups, failover, monitoring, and governance in a MySQL production environment.

Which agents are essential in this template?

Planner, Implementer, Reviewer, Tester, DBA Domain Specialist, Monitor, and Security Auditor participate, with an orchestrator coordinating handoffs and policies.

How are handoffs enforced between agents?

Handoffs require artifact transfer with acceptance criteria and time-bound SLAs; the next agent must produce required outputs before the next step.

What are the key security constraints in this workflow?

Least-privilege access, TLS encryption, secrets rotation, and production-change approvals; no direct production changes without review.

How is testing and rollback handled?

Unit and integration tests precede deployment; canary or blue/green deployments; if failures occur, automated rollback to known good state.

Target User

Use Cases