AGENTS.md Template for Database Replication Strategy

Overview

This AGENTS.md Template is a project-level operating manual for a database replication strategy that uses AI coding agents. It governs both single-agent execution and multi-agent orchestration, including planner, replicator, validator, monitor, and orchestrator roles. It specifies how agents coordinate, hand off work, validate results, and escalate when needed, with memory and source-of-truth rules to avoid context drift.

Direct answer: This template defines a repeatable, enforceable workflow for maintaining consistent, fault-tolerant database replication across regions using AI agents and explicit handoffs.

When to Use This AGENTS.md Template

• Implementing a robust, auditable database replication strategy with AI agents.
• Coordinating single-agent tasks and multi-agent handoffs for data consistency checks, lag monitoring, and failover tests.
• Establishing governance around tool usage, secrets, and deployment steps for replication workflows.
• Providing a copyable operating manual for onboarding teams to replicate patterns quickly with minimal drift.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Build and maintain a database replication workflow using AI coding agents. Ensure data consistency, low lag, and deterministic failover. All changes must go through orchestrator-guided handoffs and human review when thresholds are exceeded.

Agent roster and responsibilities
- Orchestrator: coordinates all agents, enforces rules, triggers handoffs, handles escalations.
- Planner: designs replication plan, schedules tasks, computes checkpoints, defines validation criteria.
- Replicator: executes data extraction, transport, and apply to replicas; enforces idempotency.
- Validator: validates data parity, checksums, row counts, and point-in-time consistency; raises alarms on drift.
- Monitor: tracks lag, failures, retries, and resource usage; signals orchestrator when thresholds breach.
- Researcher: investigates drift anomalies, schema drift, or replication gaps; proposes fixes.
- Domain Expert: handles schema evolution, conflict resolution rules, and governance constraints.

Supervisor or orchestrator behavior
- The Orchestrator maintains a single source of truth for replication state, instruction memory, and decision rationale. It routes tasks to agents, enforces dependency order, and triggers human review if automated checks fail.

Handoff rules between agents
- Handoff occurs only when the previous step completes its validation and records a verifiable checkpoint. Each handoff includes: task context, current state, required inputs, and acceptance criteria for the next agent.
- If a handoff fails, escalate to human review and revert to the last stable checkpoint.

Context, memory, and source-of-truth rules
- All replication state and outcomes are stored in a central, auditable store (source of truth). Agents can read but must not mutate the truth without orchestration.
- Context is scoped to the current replication cycle and is not valid across cycles unless explicitly carried forward by the orchestrator.

Tool access and permission rules
- Agents have limited scopes: Replicator can access DB connectors and write replication logs; Validator can read data state and logs; Orchestrator manages credentials and service tokens.
- Secrets are stored in a secured vault and rotated on a schedule; access is audited.

Architecture rules
- Idempotent operations; deterministic processing; stateless design wherever possible; event-driven triggers for changes.

File structure rules
- Use a single source of truth for replication state; separate agent directories for planner, replicator, validator, and monitor; avoid duplicate logic.

Data, API, or integration rules
- Only read/write replication data through defined APIs and connectors; never bypass governance gates; all schema changes must be staged and approved.

Validation rules
- Parity checks: row counts, checksums, and sample data validation; threshold-based drift alarms; post-merge validation before promotion.

Security rules
- Encrypt data in transit and at rest; restrict access by role; rotate credentials; audit all tool usage.

Testing rules
- Unit tests for replicator logic; integration tests across primary/replica; chaos testing for lag and failover scenarios.

Deployment rules
- Use blue/green or canary deployment for replication components; require successful post-deploy validation before traffic shifts.

Human review and escalation rules
- Escalate to humans when automated checks fail beyond a defined tolerance; require remediation plan and re-run.

Failure handling and rollback rules
- Retry with backoff; if unresolved, rollback to last known-good checkpoint; maintain an audit log of rollback actions.

Things Agents must not do
- Do not bypass approvals, bypass the source of truth, or modify governance rules without orchestrator consent. Do not perform destructive DB changes without explicit approval.

Recommended Agent Operating Model

Agent roles, decision boundaries, and escalation paths are defined to balance autonomy with governance. The Orchestrator remains the central decision-maker for handoffs and policy decisions; domain experts and researchers provide specialized input for schema changes and drift investigations. Escalation paths lead to human review when automated checks fail or when drift exceeds tolerance thresholds.

Recommended Project Structure

database-replication/
  orchestrator/
  planner/
  replicator/
  validator/
  monitor/
  researcher/
  domain-expert/
  shared-context/
  configs/
  scripts/
  docs/

Core Operating Principles

• Idempotent actions with deterministic outcomes.
• Single source of truth for replication state.
• Explicit, documented handoffs with verifiable checkpoints.
• Secret management and least-privilege access for all agents.
• Guardrails for human review and escalation.

Agent Handoff and Collaboration Rules

• Planner -> Replicator: pass replication plan, source-destination, and checkpoints.
• Replicator -> Validator: pass replication success, parity metrics, and logs.
• Validator -> Orchestrator: pass validation results and drift signals.
• Researcher/Domain Expert: provide schema-change recommendations via Orchestrator.

Tool Governance and Permission Rules

• Only orchestrator can grant credentials; tool usage is audited.
• Replicator can access DB connectors with read/write replication permissions; no direct production overrides.
• Secrets rotated regularly; any exposure triggers immediate revocation and alerting.
• All API calls must go through approved endpoints with safe fallbacks.

Code Construction Rules

• Replication logic must be idempotent and trigger-safe.
• All data movement uses deterministic ordering and explicit checkpoints.
• All changes are covered by tests and pass pre-release validations.

Security and Production Rules

• Encryption in transit and at rest; access control lists per component.
• Audit logs retained for a minimum period; tamper-evident logging where possible.
• Production changes require orchestrator approval and automated validation before promotion.

Testing Checklist

• Unit tests for replication components.
• Integration tests simulating primary/secondary delays and failures.
• End-to-end DR testing including failover and rollback.
• Post-deploy validation verifies data parity and timeliness.

Common Mistakes to Avoid

• Skipping validation after replication events; assume parity without checks.
• Bypassing the Orchestrator for handoffs or credential changes.
• Assuming delayed replication is acceptable without SLOs and alerting.
• Exposing secrets or broad privilege access to agents beyond necessity.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is an AGENTS.md Template for database replication?

An AGENTS.md Template provides a copyable operating manual for database replication workflows, coordinating AI coding agents and multi-agent handoffs to maintain data consistency, failover, and governed changes.

Who should own the AGENTS.md Template?

A cross-functional team with cloud, DB, and software engineering leadership should own it, with a designated platform or SRE to maintain the template.

Can this template support multi-region replication and disaster recovery?

Yes. It defines roles, handoffs, and validation to ensure consistent replication, conflict handling, and tested failover across regions.

How are tool access and secrets managed in this template?

Secrets are stored in a secured vault; agents receive limited scopes and rotation policies; access is audited and restricted.

What are common failure scenarios and rollback rules?

Network partition, lag, and schema drift are mitigated with automatic rollback plans, point-in-time restores, and roll-forward validations.

How do we handle human review and escalation?

Escalations route to humans when automated checks fail, with a clear signal path and review criteria to re-run or modify orchestrations.