AGENTS.md Template: NoSQL Database Selection

Overview

This AGENTS.md template is a project-level operating manual for the NoSQL database selection workflow. It governs how AI coding agents collaborate in single-agent and multi-agent orchestration to evaluate, compare, and select NoSQL databases (e.g., MongoDB, DynamoDB, Cassandra, Redis) based on project constraints. It provides a clear, copyable governance model that teams can paste into their AGENTS.md to bootstrap an auditable decision process and maintain alignment across engineering, security, and product teams.

Direct answer: This AGENTS.md template defines roles, sequences, and guardrails to ensure methodical NoSQL selection with traceability, tool governance, and human review where needed.

When to Use This AGENTS.md Template

Starting a NoSQL database selection project with cross-team governance needs
Coordinating multiple agents (planner, researcher, evaluator, domain specialist) for an apples-to-apples comparison
Establishing clear handoffs and single source of truth for architecture decisions
Embedding validation, security, and deployment rules into the evaluation workflow
Ensuring traceability and reproducibility of the decision

Copyable AGENTS.md Template

Paste this block into your repository as your project-level AGENTS.md and customize the fields for your organization.

# AGENTS.md

Project role
- NoSQL DB Selection Program: orchestrates the evaluation, comparison, and selection of a NoSQL database that meets project constraints (performance, cost, scalability, consistency, operational maturity).

Agent roster and responsibilities
- Planner: defines goals, constraints, success criteria, and evaluation plan.
- Researcher: gathers vendor documents, benchmarks, and telemetry sources.
- Evaluator: runs structured comparisons against criteria and produces scoring reports.
- Domain Specialist: provides domain-specific constraints (consistency models, latency SLAs, data modeling patterns).
- Implementer: translates evaluation outputs into a recommended configuration and deployment plan.
- Reviewer: validates results, ensures alignment with security and governance policies, and signs off.

Supervisor or orchestrator behavior
- The Orchestrator coordinates tasks, milestones, and handoffs; maintains a central decision log; enforces decisions follow a repeatable workflow; triggers human review when confidence is below threshold.

Handoff rules between agents
- Researcher → Evaluator: deliver collected evidence, benchmarks, and links.
- Evaluator → Implementer: hand off the recommended database plus configuration and rationale.
- Implementer → Reviewer: hand off final proposal, test results, and rollback plan.
- Domain Specialist → All: provide domain constraints to all agents as context updates.

Context, memory, and source-of-truth rules
- Context: include project constraints, workload patterns, access patterns, and workload projections.
- Memory: store decision logs, data sources, and scoring rubrics in a central knowledge store (docs/decision-log).
- Source of truth: maintain a central repository of vendor documents, benchmarks, and architecture diagrams (docs/benchmarks, docs/architecture).

Tool access and permission rules
- Read-only access to vendor documents and benchmarks; API calls to read metrics only; no secrets in AGENTS.md.
- Implementer and Reviewer may modify docs in approved sections; avoid altering production configs without review.

Architecture rules
- Central decision store for all criteria, weights, and outcomes.
- All outputs must be reproducible and auditable.

File structure rules
- Keep all decision artifacts under docs/decision-no-sql and docs/benchmarks.
- Use docs/architecture for diagrams and rationale.

Data, API, or integration rules when relevant
- Use official benchmarks, vendor whitepapers, and independent third-party reviews.
- Normalize metrics (latency, throughput, cost) to a common scale for comparison.

Validation rules
- Validate results against predefined scoring rubric with transparent weights.
- Cross-verify numbers with at least two sources.

Security rules
- Do not expose credentials; avoid leaking connection strings in AGENTS.md.
- Ensure proposed database adheres to enterprise security requirements.

Testing rules
- Include unit tests for evaluation scripts; integration tests for data-connectors; end-to-end tests for scenario execution.

Deployment rules
- Gate final recommendation behind staging validation and management sign-off.

Human review and escalation rules
- Escalate ambiguous results to architecture review board; require explicit approval for field-critical deployments.

Failure handling and rollback rules
- If evaluation is inconclusive or data is inconsistent, revert to a documented fallback option and trigger a review loop.

Things Agents must not do
- Do not change core requirements without approval; do not bypass validation steps; do not access production data without authorization.

Recommended Agent Operating Model

Roles and decision boundaries for NoSQL selection workflow:

Planner: defines evaluation criteria, success metrics, and decision thresholds. Escalates when risk is high.
Researcher: collects evidence from vendor docs and benchmarks; presents sources with traceability.
Evaluator: scores candidates using a transparent rubric; identifies trade-offs and risks.
Domain Specialist: adds constraints from domain-specific requirements (consistency; latency; data models).
Implementer: drafts a concrete configuration proposal, migration considerations, and cost model.
Reviewer: validates the proposal, ensures alignment with security, compliance, and governance; approves or requests revisions.

Recommended Project Structure

Workflow-specific directory tree:

nosql-selection/
├── agents/
│   ├── planner/
│   │   └── planner.py
│   ├── researcher/
│   │   └── researcher.py
│   ├── evaluator/
│   │   └── evaluator.py
│   ├── reviewer/
│   │   └── reviewer.py
│   └── domain-specialist/
│       └── domain.py
├── configs/
│   └── agent-config.yaml
├── data/
│   └── benchmarks/
├── docs/
│   ├── architecture-diagrams/
│   └── decision-log/
├── scripts/
│   └── run-workflow.sh
└── tests/
    └── test-evaluation.py

Core Operating Principles

Single source of truth; decisions and evidence must be traceable.
Clear ownership and escalation paths; no ambiguity in responsibilities.
Guardrails against context drift; maintain memory of prior decisions.
Observable workflows with transparent scoring and traceable sources.
Only approved tools and data sources; enforce access control and secrets handling.

Agent Handoff and Collaboration Rules

Collaborative handoffs for the NoSQL selection workflow:

Planner → Researcher: share goals, constraints, and evaluation plan.
Researcher → Evaluator: provide evidence and scoring rubric; attach sources.
Evaluator → Implementer: deliver recommended database, configuration, and rationale.
Domain Specialist → All: update constraints and constraints-driven requirements as context updates.
Reviewer → Planner: approve or request revisions; finalize decision.

Tool Governance and Permission Rules

Commands and API calls must be scoped to read operations unless explicit approval is granted for write actions.
All secret handling must use secure vaults; never hard-code credentials.
Production systems require explicit change control and sign-off before any modifications.
Handoffs and outputs must be logged in the central decision log with timestamps.

Code Construction Rules

All scripts and configs must be deterministic and reproducible; avoid non-deterministic randomness in evaluation.
Use typed inputs; validate all inputs against schema definitions.
Documentation must accompany code changes; update the decision log accordingly.

Security and Production Rules

Isolation between environments; no direct access from agents to production data.
Implement role-based access control for all tools and data sources.
Audit logs retained; ensure tamper-evident records for decisions.

Testing Checklist

Unit tests for evaluation metrics; integration tests for data connectors; end-to-end tests for workflow scenarios.
Validation of scoring rubric against historical decisions; regression tests for workflow changes.
Security tests for secrets handling and access controls.

Common Mistakes to Avoid

Skipping independent validation sources; relying on a single benchmark.
Ambiguity in requirements leading to biased choices.
Bypassing governance steps to save time.
Dropping context between handoffs; not updating the knowledge base.
Neglecting security and cost implications in the evaluation.

FAQ

Question?

What is the purpose of this AGENTS.md Template for NoSQL selection?

Question?

Who should be on the agent roster and what are their responsibilities?

Question?

How are handoffs between agents governed for NoSQL evaluation?

Question?

What governance and security rules apply to tool usage and deployment?

Question?

How is validation performed and how are decisions rolled out?

Target User

Use Cases