AGENTS.md Template: Tenant-based Database Partitioning

Overview

Direct answer: This AGENTS.md Template defines the operating model for tenant based database partitioning and provides a recipe for single-agent execution or multi-agent orchestration to partition tenants across databases or shards, enforce tenancy boundaries, manage memory, maintain a single source of truth, and govern the workflow end-to-end.

The AGENTS.md Template for tenant based database partitioning gives project teams a formal operating manual. It codifies agent roles, handoffs, memory context, tool access, architecture constraints, and escalation paths so both individual agents and multi-agent systems can reliably implement per-tenant data partitions with governance and safety checks.

When to Use This AGENTS.md Template

• Designing a multi-tenant data platform that requires strict tenant isolation and per-tenant partitioning strategies.
• Coordinating a multi-agent workflow to plan, implement, test, and validate tenant partitions across databases or shards.
• Establishing clear handoff rules, memory sharing, and a single source of truth for partition maps and tenancy policies.
• Enforcing tool governance, security, and approval gates before production changes.
• Onboarding new tenants with consistent partitioning standards and rollback plans.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Primary owner: Platform Engineer or Data Architect
- Support roles: Data Engineer, Security Auditor, Domain Specialist, QA Engineer

Agent roster and responsibilities
- Orchestrator: coordinates tasks, enforces policies, passes context and memory between agents
- Planner: designs per-tenant partition strategy, generates the Partition Plan
- Implementer: applies partition changes in the database layer (DDL, migrations, schema updates)
- Researcher: collects tenancy usage patterns, access controls, and policy constraints
- Domain Specialist: ensures compliance with tenancy policies and regulatory constraints
- Reviewer: validates changes against requirements and risk controls
- Tester: executes tests across tenants and records results

Supervisor or orchestrator behavior
- Acts as the single point of control for cross-agent coordination
- Enforces memory passing rules, versioning of Plans, and traceability
- Requires explicit approvals for production deployments

Handoff rules between agents
- Planner → Implementer: deliver Partition Plan with memory and required artifacts
- Implementer → Tester: deliver Change Artifacts and Migration Details
- Tester → Reviewer: deliver Test Report and risk findings
- Reviewer → Orchestrator: deliver Release Readiness and risk mitigation plan
- Researcher/Domain Specialist → Planner: deliver policy constraints and tenancy requirements

Context, memory, and source-of-truth rules
- Memory store: Partition Map, Tenant Registry, and Policy Ledger
- All changes must reference the source data: DB schema, tenancy docs, API docs
- Maintain a single source of truth; avoid divergent partition maps

Tool access and permission rules
- No direct production DB updates by agents without orchestrator approval
- Secrets managed via a secure secrets manager with rotation
- API calls allowed only to whitelisted endpoints with audit logging
- Use read-only access to production data unless a change requires approval

Architecture rules
- Tenant-based partitioning uses per-tenant shards or logical partitions with a central partition map
- Data access layer abstracts tenant context and enforces tenancy on every query
- Backups and restores must be tenant-scoped where possible

File structure rules
- All artifacts reside in a dedicated tenant-partitioning repo
- Do not mix partitioning artifacts with unrelated workflows

Data, API, or integration rules when relevant
- Validate tenant identifiers before any operation
- Use scoped API keys per tenant; enforce least privilege
- Audit data movement and migrations per tenant

Validation rules
- Partition Plan validation: idempotent, testable, and auditable
- Pre-merge validation: schema compatibility, tenant isolation checks
- Post-deployment verification: data integrity and access controls

Security rules
- Encrypt data in transit and at rest
- Enforce least privilege and multi-party approvals for production changes
- Maintain an immutable audit log for all partitioning actions

Testing rules
- Unit tests for agent logic
- Integration tests for planner-implementer handoffs
- End-to-end tests across a representative tenant subset

Deployment rules
- Use feature flags for partitioning changes
- Perform blue-green or canary deployments per tenant when feasible
- Maintain per-tenant rollback procedures

Human review and escalation rules
- Any change impacting tenancy policy requires human sign-off
- Escalate policy violations to the Domain Specialist and Security Auditor

Failure handling and rollback rules
- If a migration fails for a tenant, rollback only that tenant's changes
- Reconcile partition maps and re-validate tenancy after rollback

Things Agents must not do
- Do not deploy to production without approvals and tests
- Do not bypass the single source of truth for partition maps
- Do not perform unsanctioned data migrations or cross-tenant data access

Recommended Agent Operating Model

The agent operating model defines roles, responsibilities, decision boundaries, and escalation paths for tenant-based database partitioning. It supports both single-agent execution and multi-agent orchestration to maintain strict tenancy, ensure data isolation, and enable safe, auditable changes.

• Orchestrator: Enforces governance, routes tasks, and preserves memory across agents.
• Planner: Proposes partition strategies, creates the Partition Plan, and tags risk items.
• Implementer: Applies per-tenant changes in the database layer with reversible steps.
• Researcher: Analyzes tenancy workloads and flag potential policy conflicts.
• Domain Specialist: Verifies policy alignment with regulatory and business constraints.
• Reviewer: Confirms adherence to security, compliance, and design criteria.
• Tester: Executes tenant-level validation and regression tests; reports results.

Recommended Project Structure

project-root/
  tenants/
    tenant-partitioning/
      orchestrator/
      planner/
      implementer/
      tester/
      reviewer/
      researcher/
      domain-specialist/
  infra/
  docs/
  scripts/

Core Operating Principles

• Single source of truth for partition decisions and tenant registry.
• Memory persists across agent runs and is versioned with plans.
• All changes are idempotent and auditable.
• Strict tenancy boundaries and least-privilege access for all tools.
• Escalation gates and human review for every policy or major change.

Agent Handoff and Collaboration Rules

• Planner to Implementer: supply Partition Plan, memory state, and required artifacts.
• Implementer to Tester: supply change artifacts and migration details.
• Tester to Reviewer: supply test results and risk notes.
• Domain Specialist to Planner: supply policy constraints and tenancy requirements.
• Researcher to Domain Specialist: supply findings and potential exceptions.

Tool Governance and Permission Rules

• Production changes require orchestrator approval and test verification.
• Secrets access managed via a secure vault; keys rotated and logged.
• All API calls restricted to whitelisted services with audit trails.
• Database access is mediated; direct writes to production are blocked by design.

Code Construction Rules

• Follow idiomatic programming practices; write clear, testable code.
• Ensure idempotency; repeatable migrations and re-runnable scripts.
• Include unit and integration tests for all agent actions.
• Avoid hard-coded tenant IDs or secrets; use configuration and secret stores.
• Document all changes with a per-tenant changelog entry.

Security and Production Rules

• Encrypt data in transit and at rest; enforce per-tenant access controls.
• Log all privileged actions; retain audit data per policy.
• Apply least privilege; use per-tenant service accounts with scoped permissions.
• Backups must be tenant-aware; ensure restore procedures for each tenant.

Testing Checklist

• Unit tests for each agent function; mock external services.
• Integration tests for planner-implementer handoffs and migrations.
• Tenant-level end-to-end tests; regression tests for partitioning logic.
• Production-readiness checks and rollback verification.

Common Mistakes to Avoid

• Skipping tenant-specific validation; treat each tenant as an isolated unit.
• Drifting from the single source of truth; never update memory without traceability.
• Over-permissioning agents; use least privilege and approvals.
• Neglecting rollback plans and test coverage for migrations.
• Ignoring security or compliance constraints during partition changes.

Related implementation resources: AI Use Case for Gym Franchises Using Excel To Analyze Membership Peak Check-In Times and Adjust Staffing Levels and AI Use Case for Excel Customer Data and HubSpot Leads.

FAQ

What is the purpose of this AGENTS.md Template for tenant-based database partitioning?

This template defines roles, memory, governance, and handoffs for multi-tenant partitioning with AI coding agents.

When should I use this template?

Use when designing tenant-based partitions, coordinating multi-agent workflows, and enforcing tenancy policies and approvals.

How should agent handoffs be performed?

Handoffs occur with a formal artifact passing process, including memory, plan, and required artifacts to ensure continuity.

What are the success criteria for this workflow?

All tenants partitioned with validated isolation, tests passing, and compliant security controls.

What are common failure modes and rollback steps?

Migration failures, policy drift, and permission issues require tenant-level rollbacks and audit reconciliation.