Vertical Partitioning Design AGENTS.md Template

Overview

This AGENTS.md template governs the operating model for vertical partitioning design in AI coding agents. It supports both single-agent execution and multi-agent orchestration, with explicit roles, handoffs, and governance to ensure predictable outcomes, auditability, and safety. Direct answer: this AGENTS.md template defines the agent workflow, responsibilities, context handling, and escalation paths needed to design vertical partitions for data schemas while enforcing tool governance and human review where appropriate.

When to Use This AGENTS.md Template

When designing vertical partitions by column groups for scalable read patterns and privacy controls.
When you need a repeatable operating model that scales from a solo agent to a multi-agent orchestration pattern.
When strict handoffs, context memory, and source-of-truth governance are required for design decisions and migrations.
When enforcing security, audit trails, and deployment controls for schema changes.

Copyable AGENTS.md Template

# AGENTS.md

Project: Vertical Partitioning Design

Agent roster and responsibilities:
- Planner: Define goals, success criteria, data model, and partition keys.
- Architect: Translate goals into partitioning schema, column ownership, and access patterns.
- Implementer: Implement schema changes, generate migration scripts, adjust API endpoints.
- Validator: Validate correctness, performance, and data integrity across partitions.
- Reviewer: Review changes for governance, compliance, and alignment with requirements.
- Tester: Run tests, performance benchmarks, and regression checks.
- Researcher: Gather tradeoffs, document rationale, and capture edge cases.
- Domain Specialist: Validate business rules, privacy constraints, and regulatory requirements.

Supervisor or orchestrator behavior:
- Orchestrator coordinates tasks, maintains memory/context, enforces timeouts, and escalates risk beyond thresholds.
- Keeps a single source of truth and ensures idempotent operations across agents.

Handoff rules between agents:
- Planner -> Architect: share goals, constraints, and success criteria.
- Architect -> Implementer: deliver concrete partitioning schema and migration plan.
- Implementer -> Validator: provide changes, test results, and traceability.
- Validator -> Reviewer: pass governance verdict, risk assessment, and validation results.
- Reviewer -> Tester: hand off readiness signal and test plan.
- Tester -> Production: approve deployment or trigger rollback.

Context, memory, and source-of-truth rules:
- Use a central design doc as the source of truth; all agents read/write to a shared memory store.
- Context is versioned with immutable checkpoints; store decisions and tradeoffs for audit.

Tool access and permission rules:
- Agents may access the repository, DB design tools, and CI/CD with least privilege; secrets managed by a dedicated vault.
- Do not store plaintext secrets in memory or logs.

Architecture rules:
- Vertical partitioning by column groups aligned to access patterns; minimize cross-partition operations in runtime.
- Maintain backward compatibility for migrations and provide rollbacks.

File structure rules:
- /design/vertical-partitioning/
  - /docs/
  - /migrations/
  - /src/
  - /tests/
  - /scripts/

Data, API, or integration rules when relevant:
- APIs must respect partition keys; migrations are versioned and reversible.
- Avoid coupling across partitions in critical paths.

Validation rules:
- Data integrity checks, schema validation, performance benchmarks, and regression tests are mandatory.

Security rules:
- Enforce least privilege, encryption at rest/in transit, and audit logging for all schema changes.

Testing rules:
- Include unit, integration, and end-to-end tests; validate performance under load.

Deployment rules:
- Use canary or blue-green deployments for migrations; require rollbacks on failure.

Human review and escalation rules:
- Any risk beyond defined thresholds requires sign-off from the Tech Lead.
- Escalate production hotfixes through the standard change advisory process.

Failure handling and rollback rules:
- Maintain a verified rollback script for each migration; revert partitions and data migrations if issues arise.

Things Agents must not do:
- Do not bypass tests or approvals; do not modify production without governance.
- Do not perform unapproved schema changes or data migrations without explicit sign-off.

Recommended Agent Operating Model

The agent operating model assigns clear decision boundaries and escalation paths. Planner initiates goals and constraints; Architect defines the partitioning strategy; Implementer translates designs into migrations and code; Validator and Reviewer enforce quality and governance; Tester validates performance and regressions; Domain Specialist and Researcher provide business insight. If any risk exceeds thresholds, escalate to the orchestrator and, if needed, to a human lead for approval. This model supports both single-agent execution and graceful multi-agent handoffs across the vertical partitioning workflow.

Recommended Project Structure

/projects/vertical-partitioning-design/
  /agent-planner/
  /agent-architect/
  /agent-implementer/
  /agent-validator/
  /agent-reviewer/
  /agent-tester/
  /agent-researcher/
  /agent-domain-specialist/
  /shared-memory/
  /design-docs/
  /migrations/
  /tests/

Core Operating Principles

Single source of truth and auditable decisions.
Explicit, documented handoffs and decision boundaries.
Idempotent actions with deterministic outputs.
Memory hygiene and strict access control for context and results.
Security by design and enforced governance gates.
Traceable rationale for partition choices and tradeoffs.
Early validation of performance and data integrity.

Agent Handoff and Collaboration Rules

Planner communicates goals, constraints, and acceptance criteria to Architect in a structured summary document.
Architect produces a concrete vertical partitioning design with schema, ownership, and access patterns, then hands to Implementer with migration steps.
Implementer translates design into migrations and code, logs changes to the shared memory, and passes test results to Validator.
Validator performs data integrity and performance checks, documents findings, and passes to Reviewer for governance sign-off.
Reviewer ensures compliance, risk assessment, and alignment with business rules; approves or requests changes before Tester.
Tester runs unit/integration tests and signals readiness for production or triggers rollback.
Domain Specialist and Researcher provide domain-specific validation and document tradeoffs for decisions.

Tool Governance and Permission Rules

Commands and migrations must be executed only through approved scripts in CI/CD with access controls.
Code edits and schema changes require peer review and sign-off before deployment.
Secrets must never be stored in code or memory; use a vault with role-based access.
External service calls must be auditable and respect partition boundaries.
Production changes require change advisory board approval and rollback plans.

Code Construction Rules

All migrations must be reversible and logged with a timestamp, author, and rationale.
Queries must target partition keys only; avoid cross-partition joins in hot paths.
Code written for the agent must be idempotent and deterministic.
Use typed schemas for data models and validate against the source-of-truth document.
Document any architectural assumptions and tradeoffs in design-docs.

Security and Production Rules

Enforce least privilege for all agents; restrict production access to authorized roles.
Encrypt sensitive data at rest and in transit; monitor for unauthorized access.
Maintain full audit trails for design decisions, migrations, and deployments.
Implement rollback capabilities and canary deployments for partition changes.

Testing Checklist

Unit tests for each partitioned component and helper utilities.
Integration tests validating cross-service interactions within partitioned schemas.
Performance tests to ensure partitioned queries meet latency targets.
Migration tests that verify reversible rollbacks and data integrity.

Common Mistakes to Avoid

Ignoring cross-partition performance implications.
Bypassing governance gates or skipping tests to save time.
Drifting from the defined design due to ad-hoc changes without approval.
Failing to document tradeoffs and rationale for partition choices.

FAQ

What is the purpose of this AGENTS.md Template for vertical partitioning design?

It defines the operating model, roles, handoffs, and governance for AI coding agents executing a vertical partitioning design workflow.

Who should use this template?

Product teams, data engineers, platform teams, and engineering leaders implementing vertical partitioning with AI coding agents and multi-agent orchestration.

How are handoffs enforced between agents?

Handoffs follow a linear chain: Planner > Architect > Implementer > Validator > Reviewer > Tester > Production, with clear criteria at each step.

What should be your source of truth?

A central, versioned design document and a shared memory store that all agents can read and write to, ensuring traceability of decisions.

What happens on failure or rollback?

Rollback scripts revert migrations, partitions, and data changes; the orchestrator reverts to the last known good state and informs the stakeholders.

Can this template scale to more agents?

Yes. The workflow supports adding specialized agents (e.g., privacy specialist, optimization researcher) with gate-kept handoffs and shared context.

Target User

Use Cases