AGENTS.md Template for MongoDB Production Architecture

Overview

This page documents a complete AGENTS.md template for MongoDB production architecture. It governs a mix of single-agent and multi-agent workflows to operate, monitor, and evolve a MongoDB deployment in production. The template defines roles, handoffs, memory rules, tool governance, and escalation paths so AI coding agents can operate with a clear operating context.

Direct answer: This AGENTS.md template specifies roles, responsibilities, handoff rules, and governance for MongoDB production architecture, enabling coordinated, auditable, and safe multi-agent workflows.

When to Use This AGENTS.md Template

When planning and operating a MongoDB production deployment (replica sets, backups, security, and performance tuning).
When coordinating multiple agents across deployment, backup, monitoring, and schema migrations.
When formalizing governance, handoffs, approvals, and human review cycles for production changes.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Platform Architect, Database Reliability Engineer, DevOps Engineer, Security Engineer, DBA

Agent roster and responsibilities
- Planner: defines goals, milestones, and constraints for MongoDB production architecture
- MongoDB Specialist: configures replica sets, sharding (if applicable), backups, and index strategies
- Data Engineer: designs data pipelines, ETL, and data consistency checks
- Security Auditor: enforces RBAC, encryption in transit at rest, and secret management
- Deployment Engineer: handles migrations, schema updates, and CI/CD for DB changes
- Observability Engineer: builds health dashboards, alerts, and runbooks

Supervisor or orchestrator behavior
- The orchestrator coordinates dependencies, enforces memory/source-of-truth rules, and triggers handoffs when criteria are met
- Collects status from agents, applies policy, and maintains audit logs

Handoff rules between agents
- Handoff only occurs when goals are achieved and all preconditions are true
- The planner hands off to implementer with a clear objective, context, and acceptance criteria
- The reviewer and tester verify outputs before production deployment

Context, memory, and source-of-truth rules
- Memory window: 14 days of actionable context; long-term runbooks are stored in Git
- Source of truth: Git repo + MongoDB Atlas projects + runbooks
- All outputs must reference the source-of-truth artifacts

Tool access and permission rules
- Agents may access DB consoles, cloud provider consoles, and secrets manager only through sanctioned tools
- Secrets must never be printed or embedded in code
- Production changes require approval gates

Architecture rules
- Use MongoDB replica sets with automatic failover; enable backups; enable TLS; enable auditing
- Apply appropriate index strategies and shard keys if sharding is used
- Maintain read/write splitting patterns and latency budgets

File structure rules
- infra/, db/, apps/, migrations/, scripts/, configs/, docs/, tests/

Data, API, or integration rules when relevant
- Use standard data models; ensure migrations are versioned; document API changes in release notes

Validation rules
- Smoke tests pass in staging before production
- Validate replica set health, replication lag, backup integrity

Security rules
- Rotate keys, enforce RBAC, encrypt at rest where available
- No plaintext credentials in code or logs

Testing rules
- Unit tests for scripts, integration tests for migrations, end-to-end tests for critical paths

Deployment rules
- Use blue/green or canary deployment for DB changes where feasible
- Rollback plans documented and tested

Human review and escalation rules
- Any production break requires immediate escalation to the Platform Owner
- All changes pass through a change-review process

Failure handling and rollback rules
- Rollback to previous replica set or backup snapshot when a critical failure occurs
- Verify data integrity after rollback

Things Agents must not do
- Do not bypass approval gates
- Do not modify production data outside approved workflows
- Do not reveal secrets in logs or messages

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support MongoDB production orchestration with multi-agent coordination. The Planner coordinates planning and constraints, while the Implementer makes changes under the orchestrator's supervision. Reviewers validate outputs, and the Tester exercises production-like scenarios before deployment. Handoffs follow strict criteria and auditable steps.

Recommended Project Structure

mongodb-prod-architecture/
├─ infra/
├─ db/
│  ├─ replica-sets/
│  ├─ shards/
│  ├─ backups/
│  └─ indexes/
├─ migrations/
├─ scripts/
├─ configs/
├─ docs/
├─ tests/

Core Operating Principles

Single source of truth for architecture and runbooks.
Explicit memory, context, and audit trails for all agent outputs.
Careful, auditable handoffs between planner, implementer, reviewer, tester, and domain experts.
Strict access controls and secret management for all tools.

Agent Handoff and Collaboration Rules

Rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents.

Planner → Implementer: clear objectives, context, dependencies, acceptance criteria.
Implementer → Reviewer: compiled changes with tests, migration notes, rollback plan.
Reviewer → Tester: validated changes and production-readiness signals.
Tester → Orchestrator: pass/fail signals and deployment readiness.
Researcher/Domain Specialist: provides subject-matter inputs when needed; must attach sources of truth.

Tool Governance and Permission Rules

Only sanctioned tools may be used for DB operations, deployments, and secret access.
All commands and changes are logged and auditable.
Environment separation and least-privilege access for production systems.

Code Construction Rules

Scripts and configs must be idempotent and reversible.
Inputs must be validated; outputs must have traceable provenance.
Avoid hard-coded secrets; reference vaults and config stores.

Security and Production Rules

Encrypt data in transit and at rest; enforce TLS and encryption keys rotation.
RBAC with least privilege; audit logging enabled for all DB actions.
Secret management and no exposure in code or logs.

Testing Checklist

Unit tests for scripts and tooling.
Integration tests for migrations and backups/restore.
End-to-end tests for critical MongoDB workflows (failover, restore, migrations).
Production-like staging tests and blast tests for latency budgets.

Common Mistakes to Avoid

Skipping approvals or bypassing change management.
Forgetting rollback plans or performing irreversible changes without tests.
Leaking secrets or using plaintext credentials in code or logs.

FAQ

Question?

What is the purpose of this AGENTS.md Template for MongoDB Production Architecture?

Question?

Who should participate in the agent roster?

Question?

How are agent handoffs managed?

Question?

What are the memory and source-of-truth rules?

Question?

How is security enforced in this workflow?

Target User

Use Cases