Document Database Design AGENTS.md Template for AI coding agents

Overview

This AGENTS.md template defines a project level operating manual for AI coding agents engaged in document database design. It governs the end-to-end workflow from planning a document model to deployment in a governed environment. The template supports both a single agent working in a focused design loop and multi-agent orchestration where planner, implementer, reviewer, researcher, domain specialist, and tester collaborate with strict handoffs and a common memory store to avoid context drift.

When to Use This AGENTS.md Template

• Starting a new document oriented database design project requiring governance and reproducibility.
• Coordinating planner, implementer, reviewer, researcher, and domain specialist through design, validation, and deployment.
• Maintaining memory across sessions and ensuring a single source of truth for the design artifacts.
• Enforcing tool governance and permissions at each step boundary.
• Creating auditable handoffs and change logs for schema and index decisions.

Copyable AGENTS.md Template

Use this block to create a project level AGENTS.md for document database design. Paste into your repo as AGENTS.md and customize for your domain.

# AGENTS.md

Project role
- You are an AI coding agent team responsible for designing a document database schema, indexes, and migrations, with governance and complete handoffs.

Agent roster and responsibilities
- Planner: defines goals, constraints, metrics, milestones, and orchestrates the handoffs.
- Implementer (db-designer): drafts document schema, indexing, validation rules, and migration plan.
- Reviewer (db-admin): validates design against governance, security, and performance criteria.
- Researcher (docs-researcher): gathers domain requirements, data sources, and business rules.
- Domain Specialist (nosql-expert): ensures adherence to NoSQL design patterns and versioning strategies.
- Tester (qa-engineer): runs tests for schema correctness, queries, and migrations.

Supervisor or orchestrator behavior
- Planner coordinates all work, maintains design backlog, and enforces memory synchronization. Acts as the central memory and gatekeeper for handoffs.
- The orchestrator ensures artifacts are linked to a design id and propagated to downstream agents at each milestone.

Handoff rules between agents
- Planner -> Implementer: design goals, constraints, success metrics, initial schema draft
- Implementer -> Reviewer: draft schema, indexes, migrations, validation plan
- Reviewer -> Researcher: security and domain validation flags
- Researcher -> Implementer: domain data, business rules, data samples
- Implementer -> Tester: final schema and migration plan
- Tester -> Planner: validation results, risk assessment, readiness
- Planner -> (approve/revise) -> Deployment

Context, memory, and source-of-truth rules
- All artifacts live in a central memory store tied to a design id.
- Canonical schema, test results, and migration scripts are the source of truth.
- Agents reference memory by IDs to prevent drift.

Tool access and permission rules
- Agents have scoped access to repositories, databases, and staging environments.
- Do not store production credentials in memory; use vaults or secret managers.
- Execution of destructive actions requires explicit sign-off from Planner.

Architecture rules
- Layered architecture: Domain Model, Data Access Layer, Validation, and Migration layers.
- Explicit interfaces for read/write paths; no implicit side effects.

File structure rules
- project-root
  - docs
  - agents
    - planner
    - implementer
    - reviewer
    - researcher
    - domain-specialist
    - tester
  - migrations
  - tests
  - src
  - config

Data, API, or integration rules
- Use a document store API for documents; json schema compatible validation; deterministic sample data.

Validation rules
- Validate with unit and integration tests; ensure backward compatibility.
- All migrations must be reversible or have a rollback plan.

Security rules
- Secrets stored securely; production credentials gated by approval.
- Access tokens scoped per agent role; avoid broad permissions.

Testing rules
- Unit tests for schema validation; integration tests for data access; E2E tests for migration and design workflow.

Deployment rules
- Migrate to staging first; require sign-off before production deployment; maintain a changelog.

Human review and escalation rules
- Significant design changes require product owner and data governance review.

Failure handling and rollback rules
- On failure, execute rollback to prior schema and halt deployment until approval.

Things Agents must not do
- Do not modify production data directly
- Do not bypass the planner
- Do not share secrets
- Do not perform unsanctioned migrations
- Do not drift from the defined memory
- Do not execute tool commands outside approved contexts

Recommended Agent Operating Model

The recommended operating model defines distinct roles and boundaries for planning, design, validation, and deployment. The Planner acts as the orchestrator and decision authority, while Implementer produces concrete document schemas and index strategies. Reviewers enforce governance and security, Researchers validate domain requirements, Domain Specialists ensure NoSQL pattern correctness, and Testers verify functionality and performance. Escalation paths and memory synchronization enable robust multi-agent collaboration with clear ownership and traceability.

Recommended Project Structure

project-root
  docs
  agents
    planner
      prompts.md
      AGENTS.md
    implementer
      design.md
      schema.json
      migrations/
    reviewer
      governance.md
    researcher
      domain-requirements.md
    domain-specialist
      nosql-patterns.md
    tester
      tests/
  migrations
  tests
  src
  config

Core Operating Principles

• Single source of truth with immutable design artifacts
• Explicit handoffs with context transfer
• Auditability and reproducibility of changes
• Separation of concerns between design, validation, and deployment
• Security by default and least privilege access

Agent Handoff and Collaboration Rules

Handoffs must include design goals, constraints, and a memory reference. Planner records the decision context, outputs, and acceptance criteria. Implementer surfaces artifacts for validation; Reviewer validates; Researcher provides domain checks; Domain Specialist confirms pattern alignment; Tester validates readiness.

Tool Governance and Permission Rules

• Commands and edits must be routed through approved channels
• Secrets must be accessed via vaults; do not embed credentials
• Production changes require explicit approval gates
• All tool actions must be logged and attributed to agents

Code Construction Rules

• All code and schemas must be deterministic and versioned
• Schema changes must include migration plans and rollback steps
• Queries and indexes should be designed for predictable performance
• Avoid duplicating data; prefer embedding vs referencing based on domain

Security and Production Rules

• Limit exposure of data; use access controls for domain data
• Validate inputs and enforce schema at the boundary
• Production deployments require security review and runbook

Testing Checklist

• Unit tests verify schema validation
• Integration tests cover data access patterns
• Migration tests ensure data integrity during upgrades
• End-to-end tests validate planner -> implementer -> reviewer workflow

Common Mistakes to Avoid

• Skipping memory synchronization across agents
• Introducing ungoverned schema drift
• Overlooking security and secret management
• Rushing migrations without rollback plans

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 Courier Fleets Using Fuel Consumption Indexes To Identify and Flag Aggressive Driving Habits.

FAQ

What is the purpose of this AGENTS.md Template for Document Database Design?

It provides a repeatable operating manual for AI coding agents to design, validate, and deploy document oriented schemas with clear handoffs and governance.

Which agents are required in the roster for this workflow?

Planner, Implementer, Reviewer, Researcher, Domain Specialist, and Tester form a coordinated roster covering planning, design, validation, and deployment.

How are memory and source of truth handled?

A central memory store holds canonical design artifacts, schema specs, and test results. Agents reference memory by IDs to avoid drift.

What are the escalation and human review rules?

If validation or security checks fail beyond thresholds, escalate to human reviewers and the product owner before production changes.

What are the security rules for tool access?

Secrets must be stored in secure vaults; access tokens must be scoped; production connections require approval gates.