AGENTS.md Template: Database Sharding Strategy

Overview

Direct answer: This AGENTS.md Template defines a database sharding strategy workflow and provides a copyable operating manual for AI coding agents. It governs both single-agent and multi-agent orchestration, with clear roles, handoffs, tool governance, and escalation paths.

The page presents a complete, pasteable AGENTS.md block that you can drop into your repository to establish a project-level operating context for shard allocation, rebalancing, and validation across services that share a database backbone.

When to Use This AGENTS.md Template

• You are designing a sharded database layer for a multi-tenant or high-traffic application.
• You need a repeatable, auditable operating model for planner, implementer, tester, reviewer, and domain specialists.
• You require strict handoffs between agents and a single source of truth for shard maps and state.
• Your workflow demands tool governance, secret handling, and secure production changes.

Copyable AGENTS.md Template

# AGENTS.md

Project: Database Sharding Orchestration for App X

Agent roster and responsibilities
- Planner: defines shard strategy, rebalancing policy, and orchestrates work across agents
- Implementer: encodes shard map changes into code or migration scripts
- Validator: validates shard allocations against load patterns and data locality rules
- Tester: executes unit, integration, and end-to-end tests for shard behavior
- Reviewer: reviews changes, approves deployments, and audits outcomes
- Researcher: investigates anomalies, gathers telemetry, and suggests improvements
- DomainExpert: provides service-specific rules for data access and consistency

Supervisor or orchestrator behavior
- The Planner acts as the central orchestrator, issuing tasks to agents and collecting results
- All actions are asynchronous but must be idempotent; replays are safe and deterministic
- The orchestrator enforces guardrails, budgets timeouts, and enforces security constraints

Handoff rules between agents
- Planner -> Implementer: provide shard map changes, migration plans, and risk assessment
- Implementer -> Validator: submit changes and migration scripts for validation
- Validator -> Tester: hand off validated changes for test runs
- Tester -> Reviewer: escalate failures or approvals for deployment
- Researcher/DomainExpert -> Planner: feed telemetry and policy updates back to strategy planning

Context, memory, and source-of-truth rules
- All shard map state is stored in a versioned repository with a canonical shard_map.json
- Agents must reference the source-of-truth for all decisions; local caches are ignored when divergent
- Memory is limited to task context; long-term memory resides in the repository and telemetry store

Tool access and permission rules
- Only authorized agents may access the database and secret stores; use read/write access per role
- Production changes require approval from the Reviewer and an audit log entry
- External services must be accessed via approved APIs with scoped tokens

Architecture rules
- Use a modular, service-oriented approach for shard management and routing
- All shard operations are idempotent and reversible
- Changes to shard topology must be validated before applying to production

File structure rules
- All AGENTS.md related artifacts live under a project folder with a clear shard-strategy subfolder
- Migration scripts live under migrations/ and are tied to versioned shard maps

Data, API, or integration rules when relevant
- Shard maps expose read-only endpoints for telemetry; write endpoints require elevated permissions
- All data-plane changes are logged and auditable

Validation rules
- Validate shard balance against target metrics (latency, throughput, data locality)
- Ensure data consistency across shards after rebalancing

Security rules
- Never commit secrets; use secret managers and rotation
- Enforce least privilege and role-based access for all agents

Testing rules
- Unit tests for shard allocation logic
- Integration tests for migration and rollback procedures
- End-to-end tests simulating shard rebalancing under load

Deployment rules
- Continuous deployment requires successful tests and approval
- Rollback procedures must be clearly defined and automated

Human review and escalation rules
- Any anomaly beyond defined thresholds triggers human review by DomainExpert and Reviewer
- All escalations are logged and auditable

Failure handling and rollback rules
- If a shard rebalancing step fails, revert to previous shard_map.json version and re-run tests
- Maintain a safety window to prevent data loss during migrations

Things Agents must not do
- Do not modify production shard maps without approval
- Do not bypass tests or skip validation steps
- Do not share secrets in code or logs

Recommended Agent Operating Model

The recommended operating model assigns clear boundaries and escalation paths for planning, execution, validation, and governance in a database sharding workflow. Planner leads the orchestration, while Implementer, Validator, Tester, Reviewer, Researcher, and DomainExpert collaborate with explicit handoff rules. Escalations route through the Planner and ultimately to humans when automatic mitigation is not possible.

Recommended Project Structure

database-sharding/
  ├── agents/
  │   ├── planner/
  │   ├── implementer/
  │   ├── validator/
  │   ├── tester/
  │   ├── reviewer/
  │   ├── researcher/
  │   └── domain-expert/
  ├── migrations/
  ├── configs/
  ├── services/
  ├── shard_maps/
  └── docs/

Core Operating Principles

• Direct, explicit agent roles with minimal overlap
• Single source of truth for shard maps and state
• Idempotent operations and safe replays
• Auditable decisions with provenance for each change
• Strict tool governance and secret management

Agent Handoff and Collaboration Rules

• Planner defines tasks and acceptance criteria; Implementer delivers changes with rationale
• Validator validates changes against metrics and policy; if failed, feedback goes to Planner
• Tester runs synthetic load tests; results go back to Validator and Reviewer
• DomainExpert approves policy-aware changes; any risk triggers escalation

Tool Governance and Permission Rules

• Database access limited to required roles; secrets in secret manager
• Migration scripts require approval and signed change tickets
• Production endpoints accessed only through approved gateways with logging
• All API calls must be auditable and scoped

Code Construction Rules

• Write modular, testable code; avoid global state
• Ensure idempotent shard operations and safe rollbacks
• Document decisions and edge cases within code and AGENTS.md
• Avoid hard-coded secrets; use secret managers

Security and Production Rules

• Least privilege access for all agents
• Secret rotation and vault-backed credentials
• Encryption at rest and in transit for shard data
• Proactive monitoring and anomaly detection for shard metrics

Testing Checklist

• Unit tests for shard allocation logic
• Integration tests for migration scripts
• End-to-end tests for rebalancing under load
• Smoke tests for production deployment

Common Mistakes to Avoid

• Skipping validation or tests before production
• Overcomplicating shard maps with ad-hoc changes
• Ignoring data locality and cross-shard join implications
• Leaking secrets or bypassing least-privilege controls

Related implementation resources: AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template?

It provides a copyable, project-level operating manual for database sharding that supports both single-agent and multi-agent orchestration with governance and handoffs.

How do handoffs occur between planner and implementer?

The planner issues shard maps and migration plans; the implementer delivers changes to the data layer with rationale and acceptance criteria, then hands to validator.

What if a migration fails in production?

Rollback is executed using the versioned shard map, with a return-to-safe state and a post-mortem documented by the Reviewer and DomainExpert.

How is data locality ensured during rebalancing?

Policies encoded by DomainExpert and validated by Validator; tests simulate real workloads to verify locality guarantees.

What security practices are mandated?

Least privilege, secret management, automated auditing, and approved gateways for production access.