AGENTS.md Template for Relational Database Design

Overview

The AGENTS.md template for Relational Database Design defines an operating manual for AI coding agents involved in conceptual, logical, and physical database design. It governs both single-agent workflows and multi-agent orchestration, ensuring clear memory, source-of-truth, and handoff discipline across schema modeling, normalization, DDL generation, and validation. Direct answer: this page provides a runnable AGENTS.md template that you can paste into your project as operating context for designing relational schemas with AI agents.

When to Use This AGENTS.md Template

• When establishing a repeatable, auditable workflow for relational database design with AI agents.
• When you need explicit handoffs between planning, modeling, SQL generation, and validation steps.
• When enforcing tool governance, memory boundaries, and source-of-truth rules across the design lifecycle.
• When you require escalation paths to human review and rollback strategies for production-ready schemas.

Copyable AGENTS.md Template

Use the block below to initialize or refresh your project operating context. It includes the roster, responsibilities, handoff rules, memory sources, and governance rules for relational database design using AI coding agents.

# AGENTS.md

# Relational Database Design - AI Agent Operating Manual

Project role
- Lead: Orchestrator (single agent or multi-agent cohort) that coordinates the RDBMS design workflow from conceptual to physical schema, DDL generation, and validation.
- Co-Agents: Planner, ConceptualModeler, LogicalModeler, PhysicalModeler, SQLGenerator, Validator, Reviewer, SecurityAuditor, MigrationAgent.

Agent roster and responsibilities
- Planner: defines milestones, collects requirements, and breaks work into tasks with acceptance criteria.
- ConceptualModeler: builds ER-like models, entities, relationships, and high-level constraints.
- LogicalModeler: derives relational schemas (tables, keys, normalization to 3NF/BKNF as needed).
- PhysicalModeler: designs storage characteristics, indexes, partitioning, and physical constraints.
- SQLGenerator: outputs DDL for create/alter statements, constraints, and triggers if needed.
- Validator: runs consistency checks, data type compatibility, referential integrity, and basic data quality rules.
- MigrationAgent: produces migration scripts with versioning, rollback procedures, and non-destructive changes when possible.
- SecurityAuditor: ensures access controls and least-privilege practices for DB users and apps.
- Reviewer: performs final review, notes edge cases, and approves handoffs to production.
- Orchestrator: resides as the supervisory controller, coordinating handoffs, artifact storage, and versioning.

Supervisor or orchestrator behavior
- Maintain a single source of truth: store design artifacts (ER diagrams, schema definitions, DDL) in an artifacts/ folder and increment version numbers for each design cycle.
- Enforce idempotence: repeated runs yield the same artifacts if inputs are unchanged.
- Trigger driven: progress only on explicit task completions and validated checks.
- Escalate to human review when critical constraints or security concerns arise.

Handoff rules between agents
- Planner → ConceptualModeler: deliver requirements, constraints, and initial entity sketch.
- ConceptualModeler → LogicalModeler: deliver entities, relationships, and mapping to relational constructs.
- LogicalModeler → PhysicalModeler: deliver normalized schema + data types and storage considerations.
- PhysicalModeler → SQLGenerator: deliver DDL and indexes.
- SQLGenerator → Validator: deliver generated DDL and constraints; include sample data type checks.
- Validator → SecurityAuditor/Reviewer: deliver validated schema; request security review and final sign-off.
- MigrationAgent → Orchestrator: deliver migration plan and rollback steps for staging/production.

Context, memory, and source-of-truth rules
- Memory: store design decisions, rationale, and constraints in a memory block per workflow run; persist to artifacts/memory.json for traceability.
- Sources of truth: input requirements doc, existing schema, data dictionary, business rules, and domain glossary.
- Traceability: tag every artifact with input snapshot IDs and agent version.

Tool access and permission rules
- Tools allowed: ERD editor, SQL formatter, DDL generator, data dictionary tool, and versioned artifact store.
- Access controls: agents may read from memory and sources-of-truth; only SQLGenerator and MigrationAgent may write DDL to artifacts and, when approved, production controls.
- Secrets: never embed credentials in DDL or scripts; use secure secret vault references.

Architecture rules
- Modularity: separate agents by responsibility with clear interfaces; avoid cross-contamination of concerns.
- Idempotence and determinism: deterministic outputs for identical inputs.
- Versioning: maintain versioned artifacts with semantic increments.

File structure rules
- artifacts/
  - memory.json
  - models/
  - ddl/
  - migrations/
- docs/
- agents/
  - planner/
  - conceptual-modeler/
  - logical-modeler/
  - physical-modeler/
  - sql-generator/
  - validator/
  - migration/
  - security-auditor/
  - reviewer/
- tests/
- configs/

Data, API, or integration rules
- Data dictionary inputs and business rules must be provided as machine-readable sources.
- Integrations: ERD to relational mapping, and DDL to schema evolution tooling via the SQLGenerator.

Validation rules
- Every artifact must pass syntactic checks, referential integrity checks, and version consistency checks.
- DDL must be safe for staging with non-destructive changes when possible.

Security rules
- Enforce least privilege on DB users; separate duties for design vs. production changes.
- Do not embed secrets; use vault references.
- Audit logs must capture agent actions affecting schemas.

Testing rules
- Unit tests for model translations (conceptual → logical → physical).
- Integration tests for DDL generation against a test database.
- Deployment tests for migration scripts in a staging environment.

Deployment rules
- Promote only after validation and security review; require approval gate before prod migration.

Human review and escalation rules
- Any conflict in constraints or security role requires human review.
- If automated checks fail, escalate to Reviewer and SecurityAuditor.

Failure handling and rollback rules
- If migration fails, rollback to previous version and mark design as unstable.
- Maintain a rollback plan with non-destructive changes whenever possible.

Things Agents must not do
- Do not bypass validation, skip reviews, nor perform production migrations without approvals.
- Do not modify inputs without traceable reason; avoid context drift.
- Do not reuse or copy-paste outputs without re-validation.

Recommended Agent Operating Model

Roles and decision boundaries: Planner leads with requirements; each designer agent performs specific design transformations; a Validator enforces correctness; the Reviewer provides final sign-off. The Orchestrator enforces handoffs, versioning, and escalation. Escalation paths are defined for security or critical design issues that require human input.

Recommended Project Structure

ai-project-root/
├─ artifacts/
│  ├─ memory.json
│  ├─ models/
│  ├─ ddl/
│  └─ migrations/
├─ agents/
│  ├─ planner/
│  ├─ conceptual-modeler/
│  ├─ logical-modeler/
│  ├─ physical-modeler/
│  ├─ sql-generator/
│  ├─ validator/
│  ├─ migration/
│  ├─ security-auditor/
│  └─ reviewer/
├─ tests/
├─ docs/
├─ configs/
└─ scripts/

Core Operating Principles

• Operate deterministically with a single source of truth for each design artifact.
• Respect boundaries between conceptual, logical, and physical design domains.
• Handoff only validated outputs; require task acceptance before progression.
• Maintain comprehensive versioning and traceability for all artifacts.
• Prioritize security, schema integrity, and data quality at every step.
• Demand human review for any production-impacting changes.

Agent Handoff and Collaboration Rules

Planner emits a requirements package; ConceptualModeler generates entities and relationships; LogicalModeler produces schema normalization; PhysicalModeler defines storage and indexes; SQLGenerator provides DDL; Validator checks correctness; SecurityAuditor reviews security; Reviewer approves; MigrationAgent handles deployment plan. Each handoff must include: artifacts produced, input snapshots, validation status, and recommended next step.

Tool Governance and Permission Rules

Commands and edits allowed per role; only SQLGenerator and MigrationAgent can emit production-ready scripts after approvals. Secrets must never be in code; use secure vaults. All external calls should be logged and auditable.

Code Construction Rules

Adhere to project-wide coding standards for agent code, with clear interfaces, idempotent functions, and explicit error handling. Use schema-aware code generation; avoid hard-coding assumptions about data types; prefer parameterized scripts and templates.

Security and Production Rules

Enforce least privilege, rotate credentials, and protect migration paths with approvals. Segregate design-time access from production execution. Validate inputs thoroughly before any DDL generation. Maintain audit trails for all production changes.

Testing Checklist

• Unit tests for each agent transformation (conceptual→logical, logical→physical).
• Integration tests for DDL generation against a test DB instance.
• Migration tests in staging with rollback verification.
• Security tests ensuring no leakage of secrets and proper access controls.
• Regression tests to ensure no design drift across versions.

Common Mistakes to Avoid

• Skipping validation before handoffs; assuming inputs are correct.
• Allowing context drift by mutating inputs without logging changes.
• Over-relying on automated outputs without human review for critical design decisions.
• Ignoring least-privilege and secrets management in production scripts.
• Failing to version artifacts or to record rationale for design decisions.

FAQ

What is this AGENTS.md Template for relational database design?

It provides an operating manual for AI coding agents to design relational schemas, manage normalization, generate DDL, and govern multi-agent handoffs with a safety net of human review.

How many agents are involved and what are their roles?

The main roles include Planner, ConceptualModeler, LogicalModeler, PhysicalModeler, SQLGenerator, Validator, MigrationAgent, SecurityAuditor, Reviewer, and Orchestrator, each with defined responsibilities and clear handoffs.

How do agent handoffs work?

Handoffs occur after validated outputs; each agent passes artifacts, input snapshots, and validation status to the next role, with explicit acceptance criteria required before progression.

How is schema versioning and rollback managed?

Artifacts are versioned; migrations are generated with rollback procedures. If a migration fails, the system reverts to the last stable version and flags for human review.

What are the security and production considerations?

Enforce least privilege, separate design-time from production changes, store secrets in vaults, and require approval gates for production migrations.

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 Sales Pipeline Reviews and Deal Risk Scoring.