AGENTS.md Template for Ecommerce System Design

Overview

This AGENTS.md template is a practical operating manual for governing AI coding agents that design, validate, and deploy an ecommerce system. It covers both single-agent execution and multi-agent orchestration patterns, ensuring explicit handoffs, tool governance, and human review when needed. It provides a concrete workflow, decision boundaries, and auditable traces so a team can reproduce, review, and scale the ecommerce design initiative.

Direct answer: This template defines an ecommerce system design workflow driven by AI agents, with clear roles, handoffs, and guardrails to maintain reliability and traceability across design, validation, and deployment.

When to Use This AGENTS.md Template

• When starting a new ecommerce platform design effort that will be guided by AI agents and require accountable handoffs between roles.
• When you need formal governance for multi-agent orchestration, including planning, implementation, review, testing, and production readiness.
• When integrating data models, APIs, and services (cart, payments, catalog, recommendations) with strict security and deployment controls.

Copyable AGENTS.md Template

# AGENTS.md

Project role:
- Ecommerce System Design Project Lead (Orchestrator)

Agent roster and responsibilities:
- PlannerAgent: defines design plan, milestones, risk, and data needs.
- ImplementerAgent: translates the plan into concrete components (data models, APIs, services).
- ResearcherAgent: gathers domain data, regulatory constraints, and external integration details.
- DomainSpecialistAgent: focuses on payments, order management, catalog, search, and recommendations domains.
- ReviewerAgent: reviews design outputs, checks for architectural coherence and correctness.
- TesterAgent: runs integration tests, performance checks, and contract validations.
- SecurityAgent: validates threat models, secrets handling, and compliance controls.
- DeploymentAgent: coordinates deployment steps, feature flags, and rollout plans.

Supervisor / orchestrator behavior:
- The Orchestrator maintains the single source of truth (DesignSpec) and a design backlog.
- It triggers Planner to propose a plan, then delegates work to Implementer, Researcher, and Domain Specialist as needed.
- Handoffs are explicit: Planner -> Implementer (design plan), Implementer -> Reviewer (pull for feedback), Reviewer -> Tester (verification), Tester -> Deployment (ready for production).
- All decisions are logged to a centralized decision-logs artifact.

Handoff rules between agents:
- Planner to Implementer: pass DesignSpec, data requirements, and API contracts.
- Implementer to Researcher: request data sources, edge cases, and domain patterns.
- Researcher to Domain Specialist: provide constraints from domain specifics for the target service.
- Domain Specialist to Reviewer: deliver domain validations and risk notes.
- Reviewer to Tester: deliver acceptance criteria and test plans.
- Tester to Deployment: deliver validated build and deployment checklist.

Context, memory, and source-of-truth rules:
- All outputs must reference DesignSpec vN, API contracts, data models, and test results.
- Use a shared knowledge store for decisions (design-logs.md, design-spec.md).
- All sources of truth (customer requirements, regulatory constraints) are to be cited with links and IDs.

Tool access and permission rules:
- Agents may read catalog and API specs; only Implementer and Deployment Agents may push changes to code and configs, under orchestration approval.
- Secrets must be accessed via a SecretsManager abstraction; never hard-code credentials.
- No direct admin access to production systems by planning agents.

Architecture rules:
- Prefer modular microservices with clear domain boundaries.
- Use event-driven communication where possible; define idempotent operations.
- Maintain a canonical data model and API contracts; schema evolution must be backward compatible.

File structure rules:
- Keep all design artifacts under /ecommerce-design/
- /ecommerce-design/specs/: architecture decisions, data models, API contracts.
- /ecommerce-design/artifacts/: decision logs, risk registers, test results.
- /ecommerce-design/src/: service templates and scaffolds when applicable.

Data, API, or integration rules:
- All APIs must have detailed contracts and versioning.
- Data models must include field-level validations and privacy considerations.
- Integrations with payments, catalog, and order systems must go through an approved adapter layer.

Validation rules:
- Each design artifact must have traceable acceptance criteria and test coverage.
- Validation must include functional, integration, and security checks.

Security rules:
- Secrets rotate on schedule; never expose secrets in code or logs.
- Implement least privilege for all service accounts.
- Ensure PCI-DSS or applicable payment regulations are respected.

Testing rules:
- Include unit, integration, contract, and performance tests.
- Validate fault tolerance with simulated outages.
- All tests must pass before announcing readiness for production.

Deployment rules:
- Deploy via controlled blue/green or canary strategies with feature flags.
- Validate rollback plan and data migration steps.
- Post-deploy monitoring must verify SLA targets.

Human review and escalation rules:
- When a design contains major risk or policy conflict, escalate to Domain Specialist and Architect.
- When test results show regression, revert and replan.

Failure handling and rollback rules:
- If a deployment fails, roll back to previous known-good state, preserve logs, and trigger incident review.

Things Agents must not do:
- Do not modify production data without explicit approval.
- Do not bypass security controls or secrets manager.
- Do not skip testing or verification steps.

Recommended Agent Operating Model

The ecommerce OS design workflow uses a clear separation of concerns with escalation paths. Planner defines the plan and risks, Implementer builds components, Researcher and Domain Specialist surface domain constraints, Reviewer validates, Tester confirms reliability, Security ensures protection, and Deployment coordinates safe rollout. Escalations follow a defined path through Architect and Product Lead when constraints or policy conflicts arise.

Recommended Project Structure

ecommerce-design/
  agents/
    orchestrator/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
    domain-specialist/
    security/
    deployment/
  specs/
    architecture/
    data-models/
    api-contracts/
  artifacts/
    decision-logs/
    risk-registers/
    test-results/
  src/
    ecommerce-service/
  tests/
  deployments/

Core Operating Principles

• Operate with a single source of truth for design decisions and contracts.
• Make explicit, auditable handoffs between agents with traceable rationale.
• Guardrails enforce data privacy, security, and production readiness before deployment.
• Use modular architecture and well-defined interfaces for easy scaling.

Agent Handoff and Collaboration Rules

Planner coordinates with Implementer and Researcher to produce a design backlog. Implementer collaborates with Domain Specialist and Researcher for domain-specific constraints. Reviewer and Tester validate outputs before Deployment, with ongoing feedback loops for improvements.

Tool Governance and Permission Rules

• Code and config changes require orchestration approval; tools used follow least-privilege access.
• Secrets are accessed through a centralized vault; no hard-coded credentials.
• Production actions require human sign-off unless flagged as safe automated rollout.

Code Construction Rules

• Code must follow defined API contracts and data models; avoid divergence.
• Implement idempotent operations for all state-changing actions.
• Feature flags control production exposure and rollback ability.

Security and Production Rules

• PCI-DSS and privacy controls apply to payments and customer data.
• Secrets management, access auditing, and anomaly detection are mandatory.
• Production deployments are guarded with monitoring, alerting, and rollback readiness.

Testing Checklist

• Unit tests cover all new modules and functions.
• Integration tests validate API contracts and adapters.
• End-to-end tests simulate user journeys and failure scenarios.
• Performance tests verify SLA targets under load.
• Canary tests verify safe rollout and rollback paths.

Common Mistakes to Avoid

• Skipping formal handoffs and relying on ad-hoc notes.
• Ignoring data contracts and schema drift during iterations.
• Bypassing security controls for expediency.
• Deploying without adequate tests or rollback plans.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Loan Officers Using Credit Bureau Data To Calculate Risk Assessment Models for Small Business Loans.

FAQ

What is AGENTS.md Template used for in ecommerce system design?

It provides a formal operating manual for AI coding agents managing ecommerce system design, enabling single-agent and multi-agent orchestration with guardrails and a shared memory of decisions.

How do planner and implementer coordinate handoffs?

The planner emits a DesignSpec and milestones; the implementer translates them into components and interfaces, then hands back for domain validation and reviewer input before testing.

What governance applies to tool access and secrets?

Access is controlled via least-privilege roles, secrets are retrieved from a vault, and production changes require orchestration-approved steps or human sign-off.

How do you validate outputs before deployment?

Validation includes unit, integration, contract validation, security checks, performance tests, and a final manual review when risk thresholds are exceeded.

What should trigger escalation in this workflow?

Escalations occur for major design risks, policy conflicts, or failed tests that cannot be resolved by the current team without Architect or Product Lead input.