AGENTS.md Template for Database Selection Strategy

Overview

This AGENTS.md template documents a database selection strategy for AI coding agents. It governs a workflow that may run with a single agent or across multiple agents coordinated by an orchestrator. It provides project level operating context, clear roles, memory discipline, handoffs, and governance rules.

Direct answer: The template is a practical operating manual for selecting a database technology in an AI coding agent workflow, with explicit multi-agent orchestration, tool governance, and human review where needed.

When to Use This AGENTS.md Template

• When selecting a database technology for a new or existing AI powered product where data access patterns and scale matter
• When you require explicit multi-agent orchestration with defined handoffs and audit trails
• When you need a reusable, copyable operating manual for database choices and migrations

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- Database Selection Specialist
- Objective: select the most suitable database solution for the workload and constraints, with documented criteria and auditable decisions.

Agent roster and responsibilities
- Planner: defines selection criteria, collects workload metrics and constraints.
- Evaluator: benchmarks candidate databases against the criteria and produces a recommendation.
- Implementer: configures provisioning, migrations, connections, and access controls.
- Reviewer: validate the criteria, outcomes, and alignment with governance.
- Researcher: gathers workload samples, benchmarks, and vendor notes.
- Domain Specialist: adds domain specific constraints for data types and access patterns.

Supervisor or orchestrator behavior
- The Supervisor keeps global context, enforces the source of truth, and records decisions in the project memory.
- It coordinates handoffs, ensures traceability, and escalates blockers.

Handoff rules between agents
- Planner to Evaluator: final criteria and data for evaluation are handed off.
- Evaluator to Implementer: a recommended database is approved for provisioning.
- Implementer to Reviewer: changes and migrations are validated before production.
- Domain Specialist and Researcher may provide input at any stage but must be anchored to source of truth.

Context, memory, and source-of-truth rules
- All critical decisions and data are stored in a single memory store accessible to all agents.
- Source of truth is the criteria document, benchmarks, and vendor notes.

Tool access and permission rules
- Access to secret stores is restricted and credentials are rotated.
- Tools and databases must be accessed with least privilege and isolation between environments.
- No credentials should be stored in code or chat history.

Architecture rules
- Align database choices with workload characteristics such as read vs write ratio, latency, consistency, and scaling needs.
- Document sharding, replication, and backup plans in the memory.

File structure rules
- Keep this AGENTS.md in docs at the project root.
- Store artifacts under artifacts and logs under logs.

Data, API, or integration rules when relevant
- Define data access patterns and data model fit for the chosen DB.
- Ensure API compatibility for migrations and connectors.

Validation rules
- Validate performance benchmarks against criteria.
- Validate migration scripts and rollback procedures.

Security rules
- Enforce least privilege for database users and API keys.
- Do not hard code secrets; use secret management.

Testing rules
- Include unit tests for adapters and migration scripts.
- Include integration tests for read and write flows against a staging DB.

Deployment rules
- Use feature flags for database switchovers.
- Maintain a rollback plan with reversible migrations.

Human review and escalation rules
- All critical decisions require sign off from the Reviewer and Domain Specialist.
- Escalate to the Engineering Lead for blockers.

Failure handling and rollback rules
- If a migration fails, roll back to the previous stable snapshot and verify data integrity.
- Maintain audit logs of changes and outcomes.

Things Agents must not do
- Do not bypass governance or security rules.
- Do not perform production migrations without approval and test coverage.
- Do not hide decisions or omit context.

Recommended Agent Operating Model

The model defines the planner, evaluator, implementer, reviewer, researcher, and domain specialist roles. Each role has clear decision boundaries and escalation paths. The orchestrator enforces handoffs and maintains the single source of truth, ensuring multi agent collaboration does not drift from the workflow.

Recommended Project Structure

db-selection-project/
  agents/
    planner/
    evaluator/
    implementer/
    reviewer/
    researcher/
    domain-specialist/
  workflows/
  data/
  migrations/
  connectors/
  docs/
  tests/
  deployments/

Core Operating Principles

• Single source of truth for criteria and decisions
• Explicit handoffs with traceability
• Least privilege and secure secret handling
• Auditable changes and rollback readiness
• Strict adherence to the workflow boundaries

Agent Handoff and Collaboration Rules

• Planner defines criteria and passes context to Evaluator
• Evaluator passes a recommended option to Implementer and informs Reviewer
• Implementer performs provisioning and migrations with tests
• Reviewer validates results and approves move to production
• Researcher and Domain Specialist provide input as artifacts or data when needed

Tool Governance and Permission Rules

• Secret access limited to environment boundaries
• Connections and migrations require approvals
• All actions logged and reversible

Code Construction Rules

• Use well structured adapters and migration scripts
• Avoid hard coded values in code
• Document every change with rationale

Security and Production Rules

• Encrypt data in transit and at rest where applicable
• Rotate credentials regularly
• Limit blast radius in production changes

Testing Checklist

• Unit tests for adapters and connectors
• Integration tests for data flows between components
• Migration tests and rollback tests
• Blue/green or canary deployment checks

Common Mistakes to Avoid

• Skipping governance or approvals
• Omitting traceability of decisions
• Hard coding secrets or credentials
• Unmonitored database migrations

Related implementation resources: AI Use Case for Policy Documents and Internal Question Answering and AI Use Case for Visa Consultants Using Government Portals To Check Application Documents for Missing Requirements.

FAQ

What is the primary purpose of this AGENTS.md template?

It defines a database selection workflow for AI coding agents and multi-agent orchestration, including roles, handoffs, and governance.

Who should use this template?

Engineering teams building AI powered systems that must choose between database technologies and manage agent handoffs.

How are agent handoffs defined?

Handoffs specify when an agent passes context, tasks, or decisions to another agent, with held context and traceability.

What are the security and access rules?

No secrets should be hard coded. Use secret managers and minimal privilege for tools and databases.

What constitutes success for this workflow?

A validated database choice with documented criteria, reversible changes, and traceable agent decisions.