AGENTS.md Template: Distributed Transaction Design

Overview

Direct answer: This AGENTS.md Template provides a complete operating manual for distributed transaction design using AI coding agents, enabling both single-agent operation and multi-agent orchestration with explicit handoffs and governance.

It codifies the workflow, roles, state, and rules that guide AI coding agents from planning through execution, validation, and recovery in distributed systems.

When to Use This AGENTS.md Template

• Design a new distributed transaction workflow (Saga, TCC, or two-phase commit) with AI agents.
• establish an agent-based orchestration model with clear handoffs and governance.
• document source-of-truth, memory, and validation rules for auditability in multi-service transactions.
• coordinate multiple AI agents across services with a durable state and rollback capabilities.

Copyable AGENTS.md Template

# AGENTS.md
Project role: Distributed transaction design agent team

Agent roster and responsibilities:
- Planner/Orchestrator: defines the transaction steps, sequencing, and recovery strategy.
- Implementer(s): executes local service calls and state changes required by each step.
- Reviewer: validates outputs against invariants and business rules.
- Tester: runs unit and integration tests, including fault and rollback scenarios.
- Researcher: investigates failure modes, edge cases, and performance constraints.
- Domain Specialist: provides domain-specific constraints and policies.

Supervisor or orchestrator behavior:
- The orchestrator maintains a durable, auditable state store of all steps, decisions, and outcomes.
- It validates preconditions, triggers the next step, and enforces idempotent operations.
- On failure, it determines compensating actions and engages the appropriate agents.

Handoff rules between agents:
- On step completion, artifacts and state must be handed to the next designated agent with a clear context snapshot.
- If a step fails, trigger compensating actions and revert changes before advancing.

Context, memory, and source-of-truth rules:
- All decisions are recorded in a source-of-truth store; memory is append-only and immutable.
- Agents must reference the canonical source for inputs, outputs, and proofs.

Tool access and permission rules:
- Agents have scoped access to APIs and databases; secrets are retrieved from a secure vault.
- All tool usage is auditable; do not reuse credentials or leak secrets in logs.

Architecture rules:
- Stateless agent processes with external durable state; avoid long-lived in-memory state between steps.
- Use idempotent operations and unique transaction identifiers.

File structure rules:
- Workflows live under workflows/distributed-transaction-design/ with per-role subfolders.
- Avoid duplicating logic; centralize common helpers in shared libraries only when identity and permission consistency is preserved.

Data, API, or integration rules:
- Ensure idempotent REST/gRPC calls; validate data schemas; map responses to canonical models.
- Maintain strong typing and explicit error handling for partial failures.

Validation rules:
- Pre- and post-conditions for every step; invariants must hold after each successful step.

Security rules:
- Do not log sensitive data; store secrets in vaults; enforce least privilege on every API call.

Testing rules:
- Include unit tests for each step, integration tests for cross-service flows, and end-to-end tests for the full saga.
- Inject faults to validate compensation paths and rollback.

Deployment rules:
- Use feature flags for new transaction patterns; support safe rollback to a previous transaction state.

Human review and escalation rules:
- Escalate to a human reviewer if automatic compensation fails or data integrity is at risk.

Failure handling and rollback rules:
- Implement compensating actions; ensure the system can revert to the last known good state.

Things Agents must not do:
- Do not bypass the orchestrator; do not perform destructive actions without explicit approval or validation.
- Do not leak secrets in logs or outputs.

Recommended Agent Operating Model

Roles and decision boundaries: Planner orchestrates the flow; Implementers execute actions; Reviewers validate; Testers verify; Researchers and Domain Specialists refine constraints.

Escalation paths: If a failure cannot be resolved by compensation, escalate to human review; all escalations must be logged.

Recommended Project Structure

workflows/
  distributed-transaction-design/
    planner/
    orchestrator/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
    state/
    validations/
    tests/
    docs/

Core Operating Principles

• Single source of truth for all decisions and state changes.
• Idempotent steps with deterministic retries.
• Clear, documented handoffs between agents with context snapshots.
• Audit trails for all actions and decisions.
• Principled failure handling with compensating actions and rollback.

Agent Handoff and Collaboration Rules

Planner to Implementer: provide step definitions, preconditions, and expected outcomes. Implementer to Reviewer: provide results and artifacts; Reviewer approves or requests changes. Researcher to Domain Specialist: surface constraints and edge cases. Domain Specialist to Planner: update constraints; Planner revalidates.

Tool Governance and Permission Rules

• Only authorized agents may execute API calls or modify data stores; all calls are audited.
• Secrets and credentials are stored in a vault; do not log them or reveal them in messages.
• Production systems require explicit approvals and traceable change records.

Code Construction Rules

• All steps must be idempotent; use transaction identifiers and unique keys.
• Avoid side effects on retries; validate inputs before every operation.
• Write deterministic outputs for each step; do not introduce nondeterminism.

Security and Production Rules

Encrypt data in transit and at rest; apply least privilege; monitor for anomalies; ensure robust rollback and recovery.

Testing Checklist

• Unit tests for each transaction step; contract tests for API interactions.
• Integration tests validating cross-service orchestration and compensation.
• End-to-end tests simulating partial failures and full rollbacks.
• Regression tests for schema changes and protocol updates.

Common Mistakes to Avoid

• Omitting explicit handoff boundaries between agents.
• Assuming compensation is always possible; handle irreversible steps carefully.
• Logging secrets or over-logging sensitive data.
• Skipping security reviews or ignoring audit requirements.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and AI Use Case for Gym Franchises Using Excel To Analyze Membership Peak Check-In Times and Adjust Staffing Levels.

FAQ

What is the purpose of this AGENTS.md Template?

It defines a repeatable operating manual for distributed transaction design using AI coding agents, enabling both single-agent and multi-agent orchestration.

Which agent roles are defined?

Planner/orchestrator, Implementer(s), Reviewer, Tester, Researcher, and Domain Specialist where needed.

How are handoffs handled?

Handoff rules specify when artifacts pass between agents, how state is transferred, and what validations must pass before progression.

What about security and secrets?

Secrets are stored in a secure vault; agents never expose keys; all API calls are audited.

How is failure handled?

The template includes rollback and compensating actions, with automatic or human escalation if automatic recovery fails.