AGENTS.md Template for Couchbase Production Architecture

Overview

This AGENTS.md template governs Couchbase production architecture workflows using single-agent and multi-agent orchestration. It provides a clear operating manual for provisioning, scaling, backup, and recovery, with explicit handoffs, memory, source-of-truth, and tool governance rules to ensure safe, auditable changes in production systems.

Direct answer: It formalizes roles, decision boundaries, and collaboration patterns so that AI coding agents can operate predictably within a production-capable Couchbase environment.

When to Use This AGENTS.md Template

• Use when implementing Couchbase production workflows requiring guardrails, handoffs, and auditable traces.
• Use for both single-agent and multi-agent orchestration with a shared ClusterState source-of-truth.
• Use to standardize cluster provisioning, XDCR configuration, backups, scaling, and failover readiness.
• Use to enforce tool governance, secret handling, and secure deployment practices.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Couchbase Production Architecture Orchestrator

Agent roster and responsibilities
- Planner: defines objectives, constraints, schedules, and dependencies for cluster provisioning, scaling, backups, and failover readiness.
- Implementer: applies changes to the Couchbase production environment in an idempotent, auditable manner.
- Reviewer: validates changes against architecture, security, and compliance requirements.
- Tester: runs unit, integration, and disaster-recovery tests in staging or controlled production-like environments.
- Researcher: collects telemetry, logs, metrics, and evidence to inform decisions.
- Domain Specialist: Couchbase domain expert responsible for XDCR, bucket, index, security posture, and data resilience.

Supervisor or orchestrator behavior
- The orchestrator coordinates roles, enforces handoffs, updates ClusterState, and ensures memory of context and decisions is current.

Handoff rules between agents
- Planner -> Implementer: provide plan, constraints, and acceptance criteria.
- Implementer -> Reviewer: submit changes for validation against safety and architecture rules.
- Reviewer -> Tester: hand off validated changes for testing.
- Tester -> Planner: report failures or request clarifications; Planner may replan.

Context, memory, and source-of-truth rules
- Primary source-of-truth is a versioned ClusterState document stored in the repository; all agents read/write through the orchestrator.
- Memory must reflect latest approved state, test results, and risk assessments.

Tool access and permission rules
- Agents may read the ClusterState, query metrics, and apply changes through approved APIs and IaC prompts.
- Secrets must be retrieved from a secure store and never logged or exposed in outputs.

Architecture rules
- Keep changes idempotent and auditable; use deterministic naming for clusters, buckets, and indexes.
- Separate control plane from data plane; respect network segmentation and least privilege.

File structure rules
- All workflow definitions live under a versioned folder in the repository; avoid ad-hoc scripts outside the defined structure.

Data, API, or integration rules when relevant
- Validate all input data against schema contracts; use read-after-write verification for critical operations.

Validation rules
- All changes must pass pre-flight checks, schema validations, and access control verifications before execution.

Security rules
- Never log secrets; rotate credentials regularly; enforce least privilege for all agents.

Testing rules
- Include unit tests for each agent, integration tests for workflows, and end-to-end tests for production-like scenarios.

Deployment rules
- Deploy in controlled steps with feature gates; require explicit approval for production-wide changes.

Human review and escalation rules
- All risky actions require human sign-off; escalate failures to on-call owners with traceable audit trails.

Failure handling and rollback rules
- Implement rollback procedures to restore previous ClusterState; enable canary or blue-green deployment for sensitive changes.

Things Agents must not do
- Do not bypass Planner; do not perform production changes without approval; do not expose secrets; do not drift from architecture rules.

Recommended Agent Operating Model

The operating model assigns clear responsibilities to each agent role and defines decision boundaries. The planner sets the objective and constraints; the implementer executes changes to the Couchbase production environment; the reviewer validates; the tester confirms quality and disaster-readiness; the researcher informs decisions with telemetry; the domain specialist handles Couchbase-specific concerns. Escalation paths ensure safe handoffs when conflicts arise or risk is detected.

Recommended Project Structure

project-root/
  infra/
    couchbase/
      clusters/
      backups/
      security/
  workflows/
    couchbase-production/
      orchestrations/
      inventories/
      policies/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
  scripts/
  tests/
  docs/

Core Operating Principles

• Single source of truth and deterministic actions.
• Idempotent changes with explicit pre-flight validation.
• Clear, reproducible handoffs between planner, implementer, reviewer, tester, and domain expert agents.
• Separation of concerns between control and data planes.
• Auditable decisions with traceable outcomes.

Agent Handoff and Collaboration Rules

Handoff rules specify when and how agents interact during Couchbase production workflows. Planner and Domain Specialist provide context to Implementer; Implementer updates Reviewer; Reviewer triggers Tester; results loop back to Planner for refinements. All handoffs require state synchronization to ClusterState.

Tool Governance and Permission Rules

Commands, edits, API calls, and secret access must follow least-privilege policies, require approvals for production changes, and be auditable. Secrets must be retrieved securely; logs must not contain sensitive data. All tool interactions must surface only the approved outputs to the orchestrator.

Code Construction Rules

• Code is deterministic and idempotent; changes are reviewed before applying to production.
• All scripts and configurations live in version control with clear README and contracts.
• Use explicit error handling and meaningful rollbacks for failed operations.

Security and Production Rules

• Enforce network segmentation, RBAC, and secret management; limit blast radius for failures.
• Audit trails for all production changes; enforce required approvals for deployments.

Testing Checklist

• Unit tests for agent logic; integration tests for orchestration paths.
• Staging-like end-to-end tests for provisioning, scaling, backup, and restore.
• Validation of security controls and access permissions.

Common Mistakes to Avoid

• Skipping pre-flight validations or bypassing planner constraints.
• Uncontrolled drift from the defined architecture rules.
• Leaking secrets through logs or outputs.
• Overlapping handoffs that create ambiguity in ownership.

Related implementation resources: AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages and AI Use Case for Xero Reports and Business Performance Insights.

FAQ

What is the purpose of this Couchbase-specific AGENTS.md Template?

It provides a formal, copyable operating manual for orchestrating Couchbase production workflows with defined agent roles, handoffs, and governance rules, enabling reliable single-agent and multi-agent collaboration.

How does multi-agent orchestration work in this template?

Planner creates objectives and constraints; Implementer applies changes; Reviewer validates; Tester verifies; Researcher informs decisions; Domain Specialist handles Couchbase specifics. The orchestrator coordinates handoffs and maintains a single ClusterState source of truth.

What are the key handoff rules between roles?

Planner → Implementer with plan and constraints; Implementer → Reviewer for validation; Reviewer → Tester for testing; Tester → Planner for feedback and refinements.

How are secrets and production access controlled?

Secrets are retrieved from a secure store; no secrets are logged or exposed. Access is governed by least privilege roles and explicit approvals for production actions.

How does this template handle failure and rollback?

Failures trigger a defined rollback path to the previous ClusterState; changes can be rolled back via controlled procedures and, where possible, canary or staged rollouts.