AGENTS.md Template: Multi-tenant SaaS Database Architecture — AGENTS.md template

Overview

AGENTS.md template for multi-tenant SaaS database architecture defines the operating manual for AI coding agents that govern multi-tenant workflows. It covers both single agent and multi-agent orchestration patterns and provides concrete guardrails, handoff rules, and governance for tenant-scoped data, migrations, and tooling. The template helps teams formalize roles, responsibilities, and escalation paths for reliable multi-tenant operations. Direct answer: This AGENTS.md template codifies roles, guardrails, and handoffs to orchestrate AI-driven workflows across tenants with clear boundaries and audit trails.

When to Use This AGENTS.md Template

• When designing a multi-tenant database architecture and you want to codify an agent-driven workflow.
• When enabling multi-agent orchestration with explicit handoffs between planner, implementer, reviewer, tester, researcher, and domain specialist.
• When establishing governance for tenant data access, migrations, and deployment in production.
• When you need reproducible operations and audit trails for AI coding agents.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Multi-tenant SaaS Database Platform

Agent roster and responsibilities:
- Planner: designs tenant isolation strategy, data placement, and governance boundaries; creates the architecture blueprint and acceptance criteria.
- Implementer: implements tenant routing, schema separation, access controls, and migrations per the planner blueprint.
- Reviewer: validates security, privacy, performance, and compliance of changes before approval.
- Tester: executes unit, integration, and end-to-end tests across tenants; verifies performance budgets and isolation guarantees.
- Researcher: gathers requirements, edge cases, regulatory constraints, and performance targets; feeds the planner.
- Domain Specialist: Database Admin/DBA for vendor-specific features, index design, and backup/restore patterns.
- Orchestrator/Supervisor: coordinates agent work, tracks memory, sources of truth, and ensures cross-agent coherence.

Handoff rules:
- Planner -> Implementer: architecture artifacts, migration strategy, and acceptance criteria.
- Implementer -> Reviewer: implemented code, migration scripts, and test results for review.
- Reviewer -> Orchestrator: approved changes or escalation for blocking issues.
- Researcher -> Planner: new requirements, edge cases, or policy changes.
- Domain Specialist -> Implementer: specialized configurations or features.
- Orchestrator -> Agents: task assignments and prioritiation.

Context, memory, and source-of-truth rules:
- Context comes from the planner blueprint, migration docs, and design decisions stored in the central repo.
- Memory is a short-term store for active run state; the source of truth is the version-controlled code and policy documents.
- All knowledge must be traceable to PRs, issues, and design docs.

Tool access and permission rules:
- Agents have access to repo, CI/CD, feature flags, and staging environments only unless approved for production.
- Secrets are accessed via a vault; do not log secrets in messages or artifacts.
- Production data access requires explicit approval and audit logging.

Architecture rules:
- Enforce tenant isolation (schema-per-tenant or database-per-tenant as appropriate).
- Use centralized identity and authorization with least privilege.
- Apply row-level security and data masking where feasible.
- Design migrations to be backward compatible and reversible.

File structure rules:
- All architecture docs live under docs/ai-skills/agents-md-templates/md/multi-tenant-database
- Code and configs live under apps/tenant-db and infra/

Data, API, or integration rules:
- All tenant data must be isolated by tenant_id; never join across tenants without explicit governance.
- Provide a tenant-scoped API gateway layer with validated inputs.

Validation rules:
- All changes must pass unit tests, integration tests, and performance tests in staging before production.
- Validate rollback scripts and migration reversibility.

Security rules:
- Do not bypass security controls; enforce encryption at rest and in transit.
- Rotate credentials and secrets per policy; never hard-code secrets.

Testing rules:
- Include tests for tenant isolation, migration correctness, and failure scenarios.
- Test rollback paths for migrations.

Deployment rules:
- Deploy to staging first, run all tests, then promote to production via approved gates.
- Canary or blue-green deployment where appropriate.

Human review and escalation rules:
- All production changes must receive sign-off from security and platform leads.
- Escalate any tenancy boundary violation or data leak immediately.

Failure handling and rollback rules:
- If tests fail, revert to previous stable state and investigate root cause before reattempt.
- Maintain a rollback plan in the change document.

Things Agents must not do:
- Do not access production data without approval, do not bypass tests, do not modify tenant data without a migration plan, and do not drift from the architecture blueprint.

Recommended Agent Operating Model

The model assigns clear responsibilities, decision boundaries, and escalation paths for planner, implementer, reviewer, tester, researcher, and domain specialist, aligned to a symmetric multi-tenant workflow. Planner makes architectural decisions and sets acceptance criteria; Implementer translates those into code; Reviewer enforces security and correctness; Tester validates across tenants; Researcher informs scope and edge cases; Domain Specialist handles specialized database tasks. The Orchestrator coordinates cross-agent handoffs and enforces the source-of-truth rules. Escalation paths ensure blocking issues reach the right owner quickly and that tenant isolation remains uncompromised.

Recommended Project Structure

project/
  apps/
    tenant-db/
      orchestrator/
      planner/
      implementer/
      reviewer/
      tester/
      researcher/
      domain-specialist/
  infra/
  docs/
  tests/
  configs/
  scripts/
  workflows/

Core Operating Principles

• Explicit ownership for each agent role and a single orchestrator to coordinate handoffs.
• Tenant isolation and data governance drive all architectural decisions.
• Changes must be auditable with versioned design docs and PRs.
• Use least privilege, encrypted channels, and secret management for all tools.
• Guardrails prevent unsupervised production changes and ensure safe rollbacks.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide architecture blueprint, tenant isolation strategy, and acceptance criteria.
• Implementer to Reviewer: deliver code, migrations, tests, and evidence of isolation.
• Reviewer to Orchestrator: approve changes or escalate blockers.
• Researcher to Planner: share new requirements and edge cases discovered.
• Domain Specialist to Implementer: supply database configuration specifics and optimization tips.
• Orchestrator to all: assign tasks, track progress, and enforce memory/source-of-truth rules.

Tool Governance and Permission Rules

• Commands to run in CI/CD and prod require approval gates; direct destructive actions are prohibited.
• Code edits and migrations must be done via PRs with reviews and tests.
• API calls to tenant data require tenant-scoped credentials and audit logging.
• Secrets must be retrieved from a vault; never hard-coded.
• Production systems require blast doors and change control with rollback options.
• External services require documented SLAs and access reviews.
• All operations are subject to approval gates and monitoring.

Code Construction Rules

• Follow the architectural blueprint; deviations require justification and sign-off.
• Use well-defined interfaces between agents; avoid cross-team coupling.
• All migrations are forward and backward compatible.
• Data access must respect tenant boundaries and masking requirements.
• Tests cover tenant isolation, migration correctness, and failure scenarios.

Security and Production Rules

• Enforce encryption at rest and in transit for all tenant data.
• Rotate keys and credentials; never store in code or logs.
• Strict access control with role-based permissions and audit trails.
• Protect against data leakage across tenants; enforce strict separation.

Testing Checklist

• Unit tests for isolated components per tenant context.
• Integration tests across tenant boundaries and migrations.
• End-to-end tests in staging with realistic multi-tenant scenarios.
• Performance tests to validate isolation guarantees under load.
• Rollback and disaster recovery tests.

Common Mistakes to Avoid

• Assuming universal tenant behavior; validate with edge cases for each tenant type.
• Skipping migrations or rollback planning; always test rollback scripts.
• Bypassing gatekeepers and security controls in production changes.
• Imprecise handoff criteria leading to ambiguous acceptance criteria.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is AGENTS.md template?

AGENTS.md template is a copyable operating manual that defines agent roles, governance, and handoffs for a given workflow, here a multi-tenant SaaS database architecture.

How does multi-tenant architecture influence agent responsibilities?

It concentrates on tenant isolation, schema or database separation, tenant-scoped access, and auditability; each agent role enforces these constraints through design decisions, tests, and deployment guardrails.

How are agent handoffs managed in this template?

Handoffs follow explicit rules: planner to implementer for architecture, implementer to reviewer for code, reviewer to orchestrator for approval, and orchestrator for task assignment and state tracking.

What checks ensure tenant data isolation in this template?

Checks include isolation design in the planner, migration safety, tests for cross-tenant access suppression, and security reviews before production deployment.

How should changes be tested and deployed?

Changes require unit and integration tests, staging validation, security review, and a gated deployment (CI/CD with blue/green or canary). Rollback plans must exist.