AGENTS.md Template for Database Normalization and Denormalization Decisions | Suhas Bhairav

Overview

AGENTS.md template for database normalization and denormalization decisions provides a formal operating context for single-agent and multi-agent workflows. It governs how AI coding agents analyze, propose, validate, and deploy database schema changes, balancing normalization standards with performance-driven denormalization. The template ensures a living record of decisions, auditability, and clear handoffs between agents.

Direct answer: This page defines an operating manual for coordinating AI agents to decide when to normalize (3NF/BCNF) and when to denormalize for performance, including governance, memory, context, and escalation rules.

When to Use This AGENTS.md Template

When planning schema changes that affect normalization levels across modules
When balancing readability, data integrity, and query performance through selective denormalization
When coordinating a cross-functional team of planners, modelers, and validators
When you need an auditable, reproducible decision log for database design

Copyable AGENTS.md Template

Use this block to copy the operating context into an AGENTS.md file for the project.

# AGENTS.md

Project Role: Database Normalization/Denormalization Orchestrator
Agent roster and responsibilities:
- Planner: designs decision plan for normalization levels (3NF/BCNF) and where to apply denormalization for performance
- Normalization Specialist: analyzes normalization steps and applies 2NF/3NF/BCNF guidelines
- Denormalization Specialist: analyzes selective denormalization for performance
- Validator: runs schema validation, referential integrity checks, and data quality tests
- Researcher: gathers domain constraints, business rules, and usage patterns
- Domain Specialist: provides domain constraints and edge-case rules
Supervisor or orchestrator: The Planner coordinates tasks, maintains memory, and sources of truth
Handoff rules:
- After planning, hand off to Normalization Specialist to implement normalization steps
- Denormalization Specialist reviews proposed denormalizations for performance impact
- Validator runs validation after each handoff; conflicts escalate to Domain Specialist
Context, memory, and source-of-truth:
- All decisions are logged in a central repository document with versioning
- Use diagrams and business rules as sources of truth; reference versions by commit hash
Tool access and permission rules:
- Access to SQL clients, migration tools, and the project repository with role-based permissions
- Secrets securely stored; never hardcode credentials
Architecture rules:
- Modular architecture; each decision logged with rationale and version
- Changes are idempotent and traceable
File structure rules:
- agents/planner/
- agents/normalizer/
- agents/denormalizer/
- agents/validator/
- artifacts/diagrams/
- artifacts/rules/
Data, API, or integration rules:
- Use parameterized queries and official drivers
- No direct production writes without a defined migration procedure
Validation rules:
- Referential integrity checks, schema validation, and data quality metrics
- If validation fails, revert to the previous schema version
Security rules:
- Secrets not stored in code; use vault or secret manager; enforce access controls
Testing rules:
- Unit tests for transformation logic
- Integration tests for migrations
- End-to-end smoke tests for critical paths
Deployment rules:
- PR-based deployments; migrations applied in staging first; approvals required for production
Human review and escalation rules:
- If risk score exceeds threshold, escalate to a human reviewer and DBA
- Document rationale and decisions in the log
Failure handling and rollback rules:
- Use transactional migrations; if a step fails, rollback to previous version
- Maintain backups and a rollback plan
Things Agents must not do:
- Do not perform production writes without sign-off; do not bypass tests; do not drift from the agreed schema

Recommended Agent Operating Model

The operating model assigns roles with clear decision boundaries and escalation paths to ensure safe, auditable schema decisions.

Planner: owns the overall plan, milestones, and escalation path
Normalization Specialist: makes decisions on normalization levels and schemas
Denormalization Specialist: identifies denormalization opportunities for performance
Validator: ensures integrity and rules before handoffs
Researcher: gathers constraints and data usage patterns
Domain Specialist: validates domain-specific constraints and exceptions

Recommended Project Structure

db-normalization-denormalization/
├── agents/
│   ├── planner/
│   │   └── main.py
│   ├── normalizer/
│   │   └── main.py
│   ├── denormalizer/
│   │   └── main.py
│   └── validator/
│       └── main.py
├── artifacts/
│   ├── diagrams/
│   └── rules/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── end-to-end/
└── docs/

Core Operating Principles

Operate with a single source of truth and auditable decisions
Make changes idempotent and reversible
Preserve referential integrity and data quality
Ensure strict handoffs with clear ownership
Minimize context drift by logging decisions and sources

Agent Handoff and Collaboration Rules

Handoff rules specify how planner, implementer, reviewer, tester, researcher, and domain specialist agents collaborate.

Planner to Normalizer: handoff plan and rationale
Normalizer to Denormalizer: share normalization path and performance targets
Denormalizer to Validator: provide denormalization outcomes for validation
Validator to Researcher: request domain constraints and usage patterns
Researcher and Domain Specialist to Planner: signal risks or conflicts for escalation

Tool Governance and Permission Rules

Only approved tools may execute SQL migrations and schema changes
Access to production environments requires sign-off and protective controls
Secrets must be retrieved from a secure vault; never stored in code
All tool actions must be logged with agent and timestamp

Code Construction Rules

Generate clear, deterministic SQL with parameterization
Favor explicit column naming and constrained data types
Document rationale for any denormalization with performance metrics
Provide migration scripts as reversible steps

Security and Production Rules

Restrict production access; require approvals for production migrations
Audit all changes and maintain rollback plans

Testing Checklist

Unit tests for transformation logic
Schema validation tests and referential integrity checks
Migration testing in staging before production

Common Mistakes to Avoid

Over-normalizing without consideration of query paths
Undertaking denormalization without measuring impact
Skipping validation, causing data quality issues

FAQ

How does this AGENTS.md Template help with normalization and denormalization decisions?

This template provides a structured workflow for planning, validating, and enacting schema changes across multiple agents, balancing normalization goals with performance considerations and auditability.

Who should be on the agent roster for this workflow?

A Planner, Normalization Specialist, Denormalization Specialist, Validator, Researcher, and Domain Specialist ensure coverage of design, validation, and domain constraints.

How are handoffs between agents managed?

Handoffs follow a defined sequence: Planner -> Normalization Specialist -> Denormalization Specialist -> Validator, with escalation to Domain Specialist on conflicts.

What are the validation and rollback rules for schema changes?

Validation must confirm referential integrity and data quality; migrations are executed transactionally with a rollback plan and backups if needed.

How is access to tooling and production resources governed?

Only approved tools are allowed for migrations; production access requires sign-off, and secrets are managed in a secure vault with role-based access.

AGENTS.md Template for Database Normalization and Denormalization Decisions (AGENTS.md template)

Target User

Use Cases