AGENTS.md Template for Cassandra Production Architecture

Overview

This AGENTS.md Template for Cassandra Production Architecture defines the operating context for AI coding agents in a production Cassandra cluster. It governs both a single-agent workflow and multi-agent orchestration, enabling clear decision boundaries, handoffs, and governance across deployment, operation, and change management.

Direct answer: use this AGENTS.md Template to establish a reproducible, auditable agent workflow around Cassandra provisioning, maintenance, and incident response, with explicit roles, memory, and source-of-truth rules for every step.

When to Use This AGENTS.md Template

• Defining the agent roster and responsibilities for Cassandra production architecture.
• Governing handoffs between planners, implementers, reviewers, testers, researchers, and domain specialists.
• Enforcing tool governance, secret handling, and secure access to Cassandra tooling (nodetool, cqlsh, sstableloader).
• Providing a project-level operating context for reproducible changes, migrations, and upgrades.
• Documenting memory and source-of-truth rules to prevent context drift during multi-agent workflows.

Copyable AGENTS.md Template

Paste this block into your repository to initialize the Cassandra production architecture agent workflow.

# AGENTS.md

Project Role
- This template defines an operating model for AI coding agents managing Cassandra production architecture across provisioning, maintenance, and incident handling.

Agent Roster and Responsibilities
- Planner: designs the change plan (cluster sizing, topology, backup strategy) and sequences steps for the Implementer.
- Implementer: executes infrastructure and database changes (Kubernetes/CaaS provisioning, Cassandra config, schema migrations).
- Reviewer: validates changes against policy, security, and operational constraints before deployment.
- Tester: runs validation, load tests, and recovery drills in a staging or canary environment.
- Researcher: investigates data model implications, repair strategies, and performance tuning.
- Domain Specialist: DBA and Cassandra-expert advisor for complex schema or repair scenarios.

Supervisor / Orchestrator Behavior
- The Orchestrator coordinates all agents, enforces memory rules, and maintains the single source of truth (SoT) for decisions, outputs, and artifacts.
- All actions emit observable events to the SoT and audit log.

Handoff Rules Between Agents
- Planner → Implementer: handoff plan artifacts, environment details, and success criteria.
- Implementer → Tester: handoff after changes are applied with validation tests results.
- Tester → Reviewer: handoff after test results and risk assessment.
- Researcher / Domain Specialist → Planner: provide findings for next iteration.

Context, Memory, and Source-of-Truth Rules
- Central SoT stores decisions, rationale, and artifact versions.
- All agent memory must be referenced to the SoT; avoid ad-hoc memory buffers.
- Use Git commits and a metadata store to capture decisions and approvals.

Tool Access and Permission Rules
- Agents may use kubectl, nodetool, cqlsh, and deployment tooling with least privilege.
- Secrets must be retrieved from a vault; do not hard-code keys.
- Production access requires approval gate; only approved agents may touch production resources.

Architecture Rules
- Cassandra cluster topology with replication across datacenters, RF≥3, and appropriate compaction strategies.
- Change management follows blue/green or canary deployment where applicable.
- Health checks rely on nodetool and custom health endpoints.

File Structure Rules
- Use a conventional repository layout:
  /configs
  /deployments
  /scripts
  /docs
  /tests
  /memory
  /orchestrator
  /agents
- Do not introduce unrelated tooling folders.

Data, API, or Integration Rules
- All data-plane changes go through the AGENTS.md controlled pipeline.
- Database access via controlled APIs or CLIs; avoid direct ad-hoc queries in production.

Validation Rules
- Every change must have a plan, tests, and rollback criteria.
- Validation must include data integrity, performance thresholds, and repair validity.

Security Rules
- Enforce least privilege, secret rotation, and auditing of all changes.
- Production credentials must never be exposed in logs or artifacts.

Testing Rules
- Unit tests for change logic, integration tests for cluster changes, end-to-end tests for failure scenarios.
- Run disaster-recovery drills and schema upgrade tests in staging.

Deployment Rules
- Use canary or blue/green deployments when upgrading Cassandra components or schemas.
- Rollback plan must be executable with one-click revert.

Human Review and Escalation Rules
- Any production change requires human review and, if applicable, escalation to on-call domain experts.
- In emergencies, follow the rollback and kill-switch procedures.

Failure Handling and Rollback Rules
- Predefine backout steps, snapshot points, and verification checks.
- If validation fails, revert to the previous artifact version and notify stakeholders.

Things Agents Must Not Do
- Do not bypass the Orchestrator or the SoT.
- Do not perform unsanctioned production changes.
- Do not leak secrets or credentials in artifacts or logs.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support Cassandra production architecture with multi-agent coordination. The Planner designs the plan; Implementer executes; Tester validates; Reviewers approve; Researchers and Domain Specialists provide specialized guidance. Escalation paths connect the on-call engineer to the domain expert for complex migrations or repairs.

Recommended Project Structure

cassandra-production-architecture/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  orchestrator/
  memory/
  configs/
  deployments/
  scripts/
  tests/
  docs/

Core Operating Principles

• Single source of truth for all decisions and artifacts.
• Explicit handoffs with verifiable completion criteria.
• Least-privilege access for all tools and secrets.
• Idempotent operations with clear rollback paths.
• Clear separation of concerns among agent roles.

Agent Handoff and Collaboration Rules

• Planner produces a concrete plan with environment, versions, and risk assessment.
• Implementer executes plan and reports back with artifacts and test results.
• Tester validates against predefined acceptance criteria before proceeding.
• Reviewer signs off the change and records approval in the SoT.
• Researcher and Domain Specialist provide guidance when complex issues arise.

Tool Governance and Permission Rules

• Access to cluster tooling requires approved roles and gating.
• Secrets must be retrieved from a secure vault and rotated regularly.
• Production changes require an on-call escalation path and audit logging.
• All API calls and database edits must be versioned and auditable.

Code Construction Rules

• Write clear, deterministic scripts with explicit input/output contracts.
• Annotate changes with rationale and risk evaluation.
• Do not hard-code environment-specific values; use config-driven approaches.

Security and Production Rules

• Enforce encryption at rest and in transit for Cassandra data.
• Limit direct access to production nodes; perform changes through orchestrated pipelines.
• Audit all changes and retain logs for at least 90 days.

Testing Checklist

• Unit tests for scripts and change logic.
• Integration tests for Cassandra provisioning and deprovisioning paths.
• Migration and rollback verification in staging canary.
• Performance and load tests to meet SLA.

Common Mistakes to Avoid

• Skipping formal handoffs or missing acceptance criteria.
• Bypassing the SoT or architecting without governance.
• Using insecure secrets or logging credentials in artifacts.
• Over-restricting tests and blocking essential validation.

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 Xero Reports and Business Performance Insights.

FAQ

What is this AGENTS.md Template for Cassandra production architecture?

It provides a copyable, project-level operating manual for AI coding agents to govern Cassandra production workloads, with roles, handoffs, and governance rules for single-agent and multi-agent orchestration.

How does multi-agent orchestration work here?

Multiple agent roles (Planner, Implementer, Tester, Reviewer, Researcher, Domain Specialist) coordinate through a central Orchestrator that enforces memory rules, source-of-truth, and auditable handoffs.

What are the key handoff moments?

Plan completion from Planner to Implementer; change execution from Implementer to Tester; validation from Tester to Reviewer; findings loop back to Planner as needed.

How is data integrity and security enforced?

Through least-privilege access, vault-managed secrets, encrypted data in transit/at rest, and auditable actions recorded in the SoT.

What happens on failure or rollback?

Rollback steps are predefined with backout points,, and a canary or blue/green strategy to restore a known-good state with audit trails.