DynamoDB Production Architecture AGENTS.md Template

Overview

AGENTS.md Template for DynamoDB Production Architecture defines an operating model for AI coding agents and multi-agent orchestration around a DynamoDB production workflow. It governs the planner, implementer, reviewer, tester, researcher, and domain specialist roles, and it codifies handoffs, memory and source-of-truth rules, tool governance, and escalation paths. This page provides a copyable AGENTS.md template you can paste into your project to establish a consistent, auditable agent operating context.

Direct answer: This template yields a reproducible, governance-driven agent workflow for DynamoDB production architectures that can operate with a single agent or a coordinated multi-agent team, including explicit handoffs and security controls.

When to Use This AGENTS.md Template

• To codify an end-to-end DynamoDB production workflow where AI coding agents manage schema design, access patterns, and operational governance.
• When you need explicit agent handoffs, memory rules, and a single source of truth for data models, IAM policies, and deployment steps.
• To enable repeatable, auditable processes for DynamoDB deployments, migrations, and incident responses with human review at decision points.

Copyable AGENTS.md Template

Paste the block below into your repository as AGENTS.md to establish project-level operating context for single-agent or multi-agent DynamoDB workflows.

# AGENTS.md

Project Role: DynamoDB Production Architecture Agent System (single-agent or multi-agent) responsible for endpoint design, data models, access patterns, performance tuning, and governance in a DynamoDB production environment.

Agent roster and responsibilities:
- Planner: designs data model, access patterns, partition keys, indexes, TTL usage, and eventual consistency requirements for DynamoDB production.
- Implementer: translates planner decisions into code, infrastructure changes, and DynamoDB configurations.
- Reviewer: validates data models, access patterns, security controls, and deployment plans before execution.
- Tester: creates and runs unit, integration, and load tests, including DynamoDB read/write workloads and failure scenarios.
- Researcher: stays current with DynamoDB best practices, capacity planning, and cloud patterns relevant to the workflow.
- Domain Specialist: provides domain-specific requirements, data governance constraints, and compliance rules.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates tasks across agents, enforces memory context, and ensures a single source of truth for DynamoDB schema, indexes, and access policies. It triggers handoffs when criteria are met and maintains traceability.

Handoff rules between agents:
- Planner > Implementer: when design is validated and ready for implementation.
- Implementer > Reviewer: upon completion of code/infrastructure changes.
- Reviewer > Tester: after approval on quality, security, and compliance checks.
- Tester > Orchestrator: when tests pass or a rollback is required.
- Researcher > Domain Specialist: for policy or constraint updates.

Context, memory, and source-of-truth rules:
- All decisions live in a config/repo-based source of truth. Memory must be scoped by a versioned context tied to a DynamoDB deployment cycle. The canonical data model, IAM policies, and deployment steps are the source of truth.
- Use a shared memory store for transient task state; persist long-term decisions in the config repo.

Tool access and permission rules:
- Agents have least-privilege access to DynamoDB tables, IAM roles, and supporting services. Secrets stored in a vault or Secrets Manager. No credential leakage.

Architecture rules:
- DynamoDB tables must follow best practices: partition keys that support access patterns, GSIs where needed, TTL where appropriate, and proper backup and restore strategies. Consider global tables for multi-region workloads.

File structure rules:
- Maintain a small, predictable repo layout:
  config/
  models/
  infra/
  scripts/
  tests/
  docs/

Data, API, or integration rules:
- Use AWS SDK v3 for DynamoDB interactions. Validate data against schema definitions. Where APIs or data streams are involved, document interfaces in the config repo.

Validation rules:
- All changes must pass unit and integration tests; deployment requires a green signal from reviewers; data-model changes require migration validation.

Security rules:
- Enforce IAM least privilege, encryption at rest (DynamoDB), encryption in transit, and VPC endpoints for AWS services. Secrets must never be hard-coded.

Testing rules:
- Include unit tests for data-layer helpers, integration tests for DynamoDB interactions, and load tests that simulate peak DynamoDB traffic.

Deployment rules:
- Use CI/CD with canary or blue/green deployments. Rollback procedures must be defined and auditable.

Human review and escalation rules:
- All production changes require human review at critical decision points. If a test fails, escalate to a domain specialist and revert if necessary.

Failure handling and rollback rules:
- Implement circuit breakers for DynamoDB failures; preserve previous stable state and provide a rollback path to the last known-good configuration.

Things Agents must not do:
- Do not bypass approvals, modify production data directly, or disclose credentials. Do not execute uncontrolled changes without tests and reviews.

Recommended Agent Operating Model

The agent operating model for DynamoDB production architecture defines clear boundaries and escalation paths. Planner decides on data models and access patterns, Implementer executes, Reviewer validates, Tester confirms, Researcher informs, and Domain Specialist provides constraints. Handoffs are deterministic: Planner → Implementer → Reviewer → Tester → Orchestrator. If tests fail or security is violated, escalate to Domain Specialist and revert as needed.

Recommended Project Structure

dynamodb-prod-arch/
├── config/
│   ├── models/
│   └── policies/
├── infra/
├── models/
├── scripts/
├── tests/
├── docs/
└── workflows/

Core Operating Principles

• Single source of truth for DynamoDB schemas, indexes, and access policies.
• Least privilege for all agents; secrets are vaulted.
• Deterministic handoffs with audit trails.
• Idempotent, testable changes with rollback paths.
• Clear separation between planning, implementation, validation, and operations.

Agent Handoff and Collaboration Rules

• Planner documents design decisions and acceptance criteria before Implementer begins work.
• Implementer executes changes and updates configuration and scripts with traceable commits.
• Reviewer checks for correctness, security, and compliance; approves or requests changes.
• Tester runs unit and integration tests, including DynamoDB workload simulations; reports results.
• Researchers and Domain Specialists provide guidance on constraints, data governance, and business rules as needed.

Tool Governance and Permission Rules

• Operations must use least-privilege IAM roles; no broad admin access.
• Secrets stored securely; never embedded in code or scripts.
• All tool calls to DynamoDB or AWS services must be auditable and reversible.
• Approval gates required for production deployments and schema migrations.

Code Construction Rules

• All changes are implemented as versioned, testable modules with clear interfaces.
• Data models must include validation rules and migration paths for schema changes.
• Infrastructure changes must be expressed via declarative templates and reviewed.
• Documentation and comments must reflect the current design decisions and tradeoffs.

Security and Production Rules

• Encrypt data at rest and in transit; enforce access controls via IAM and VPC endpoints.
• Limit DynamoDB table access to specific roles and resources; isolate production resources from dev.
• Monitor for anomalous activity; auto-respond to potential data exposure.

Testing Checklist

• Unit tests for data-layer helpers and validators.
• Integration tests for DynamoDB operations and index/query correctness.
• Load tests simulating peak traffic and failure modes.
• End-to-end tests including deployment and rollback paths.

Common Mistakes to Avoid

• Bypassing reviews or approvals for production changes.
• Ignoring migration risks or failing to test data migrations.
• Exposing credentials or granting overly broad permissions.
• Overcomplicating data models that hamper performance or maintenance.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template for DynamoDB?

It defines a repeatable operating manual for single-agent or multi-agent DynamoDB production workflows with governance, handoffs, and human review.

Which agent roles are defined in this template?

Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist, plus an Orchestrator for coordination.

How are handoffs governed in multi-agent orchestration?

Handoffs follow a deterministic flow: Planner → Implementer → Reviewer → Tester → Orchestrator, with escalation paths for failures or blocking issues.

What governance rules are included?

Tool access, secrets, IAM permissions, deployment approvals, and audit trails are codified to prevent unsafe or unreviewed changes.

How should security be enforced?

Least privilege, encryption at rest and in transit, and secure secret management are mandatory in all configurations and scripts.