AGENTS.md Template: Wide Column Database Design

Overview

AGENTS.md template for wide column database design governs an agent workflow and multi-agent orchestration around a columnar/wide-column data model (e.g., Cassandra, Bigtable, HBase). It provides a complete operating manual for single-agent and multi-agent work, including handoffs, governance, and human review touchpoints. It combines project-level operating context with a copyable AGENTS.md template you can paste into your repository to bootstrap an analytics data platform initiative.

When to Use This AGENTS.md Template

• Design or evolve a wide-column data model for analytics use cases and large-scale writes/reads.
• Orchestrate multiple agents (planner, implementer, reviewer, tester, data researcher) around schema design, migrations, and governance.
• Establish tool access, memory, and source-of-truth rules for a reproducible data platform workflow.
• Require documented handoffs and escalation paths to reduce architectural drift and unsafe production changes.
• Integrate domain-specific constraints from analytics and governance teams into a single AGENTS.md template.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Data Platform Architect for wide-column schema design and agent-driven governance across analytics workloads.

Agent roster and responsibilities:
- Planner: designs the overall wide-column schema strategy, partitioning, clustering, and TTL policies; defines required indexes and access patterns.
- Implementer: translates the planner's design into concrete DDL/CQL/migrations and scaffolds repository changes.
- Reviewer: validates data model quality, performance implications, and security constraints; approves schema changes.
- Tester: executes unit and integration tests, including migration idempotency and backward compatibility checks.
- Researcher: researches best practices for wide-column patterns, materialized views, and data access paths; gathers sources.
- Domain Specialist: subject-matter expert for analytics workloads, audit requirements, and governance controls.

Supervisor or orchestrator behavior:
- Orchestrator coordinates task assignments, enforces SLAs, and logs decisions to a central artifact store.
- All agent actions are versioned, and decisions are traceable with timestamps and rationale.

Handoff rules between agents:
- Planner -> Implementer: hand off design plan, DDL specs, and migration plan.
- Implementer -> Reviewer: present DDL, migrations, and code for validation.
- Reviewer -> Implementer: provide feedback; if changes are needed, iterate.
- Researcher/domain specialist -> Planner: provide domain constraints and acceptance criteria.
- Planner -> Domain Specialist: present final design rationale for governance approval.

Context, memory, and source-of-truth rules:
- Memory is stored as a canonical AGENTS.md context file in the repository.
- Source of truth: canonical schema docs under /schemas and the latest migrations under /migrations.

Tool access and permission rules:
- Tools: DB shell, schema diff tools, repository PRs, secret vaults.
- Secrets must never be logged; access limited by role; production credentials require explicit approvals.

Architecture rules:
- Idempotent migrations; explicit rollback paths; avoid destructive changes without tests and approvals.
- Prefer additive schema changes with clear migration strategies.

File structure rules:
- Organize artifacts under /schemas, /migrations, /tests, and /docs.

Data, API, or integration rules when relevant:
- All data interface changes must preserve backward compatibility or provide a migration path; document data lineage.

Validation rules:
- Validation must include schema checks, data quality checks, and performance heuristics.

Security rules:
- Least privilege access; secrets rotated; encryption at rest; audit logging enabled for production changes.

Testing rules:
- Unit tests for utilities, integration tests for migrations, regression tests for backward compatibility.

Deployment rules:
- CI/CD gated deployments; feature flags for gradual rollouts; blue/green or canary strategies where applicable.

Human review and escalation rules:
- Any non-trivial design or production-change requires domain specialist and reviewer sign-off.

Failure handling and rollback rules:
- If deployment fails, rollback to the previous schema version and re-run validation.

Things Agents must not do:
- Do not bypass review; do not perform production changes without approvals; do not duplicate work or drift from the canonical memory.

Recommended Agent Operating Model

The agent operating model defines clear roles, decision boundaries, and escalation paths for a scalable multi-agent workflow around wide-column design. The planner creates a design envelope; the implementer translates it into migrations and code; the reviewer validates correctness and security; the tester validates behavior; the researcher and domain specialist provide domain context and governance constraints. Escalation paths ensure safe handling of conflicts or unknowns, and the orchestrator maintains a single source of truth for decisions and progress.

Recommended Project Structure

wide-column-db-design/
  schemas/
  migrations/
  tests/
  docs/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  orchestrator/
  config/

Core Operating Principles

• Single source of truth for design decisions and memory.
• Idempotent, auditable changes with explicit rollback paths.
• Deterministic outcomes with clear acceptance criteria.
• Guardrails and governance rules embedded in the AGENTS.md context.
• Respect for data safety, governance constraints, and domain constraints.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide a complete design envelope, including partition strategy, clustering keys, TTL, and required artifacts.
• Implementer to Reviewer: deliver DDL/migrations and code with traceable changes.
• Reviewer to Implementer: suggest corrections; ensure alignment with governance; repeat until approved.
• Researcher/Domain Specialist to Planner: supply domain constraints and acceptance criteria; update memory accordingly.
• Planner to Domain Specialist: present design rationale and risk assessment for governance approval.

Tool Governance and Permission Rules

• Commands that modify schema require approvals; read-only access for most agents.
• Edits to migrations or schemas must be performed via PRs; secrets never embedded in code or logs.
• Production systems require explicit approvals and change windows; blue/green or canary deployment when possible.
• APIs and integrations must be rate-limited and audited.
• All tool actions should be idempotent and reversible.

Code Construction Rules

• Follow the design plan; do not introduce speculative patterns without validation.
• Write migrations that are reversible; include backward-compatible changes where possible.
• Document assumptions and edge cases in code and comments.
• Avoid duplicating logic across agents; reuse shared utilities and templates.

Security and Production Rules

• Protect credentials; rotate keys; restrict production access.
• Ensure encryption at rest and in transit where appropriate for data movement.
• Audit changes and maintain traceability of who did what and when.

Testing Checklist

• Unit tests for utilities and validation logic.
• Integration tests for migrations and schema changes.
• Data-quality checks and backward-compatibility validation.
• Performance checks for typical query patterns on the wide-column design.
• Deployment validation in a staging environment before production release.

Common Mistakes to Avoid

• Rushing design changes without governance or memory updates.
• Skipping rollback plans or testing migrations thoroughly.
• Allowing handoffs to drift from the approved design envelope.
• Omitting data lineage and source-of-truth documentation.
• Assuming performance gains without measurable validation.

Related implementation resources: AI Agent Use Case for Intermodal Transport Providers Using Rail Schedules To Coordinate Seamless Truck-To-Train Transfers and AI Agent Use Case for Apparel Designers Using Textile Wear Tear Tracking Data To Source Highly Durable Synthetic Yarn Weaves.

FAQ

What is the purpose of this AGENTS.md Template for wide column database design?

It provides a complete, copyable operating manual to govern AI coding agents and multi-agent orchestration for designing and evolving wide-column data schemas, with explicit handoffs, governance, and validation rules.

Who should own the agent roster and handoffs?

Assign a Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist; the Orchestrator coordinates them and maintains the canonical memory and decision log.

How are changes validated before production deployment?

Validation includes unit/integration tests, migration checks, backward-compatibility verification, and governance approvals from Domain Specialist and Reviewer.

What are the security considerations in this workflow?

Use least privilege, encrypt sensitive data, rotate secrets, and audit production changes; do not log secrets or bypass approvals.

How is multi-agent collaboration enforced?

Handoffs follow a strict chain (Planner>Implementer>Reviewer) with feedback loops; the Orchestrator enforces memory consistency and provenance of decisions.