AGENTS.md Template for Serverless Architecture Planning

Overview

The AGENTS.md template is a structured, copyable operating manual for AI coding agents to plan and execute a serverless architecture project. It governs the serverless design workflow, supports both single agent work and multi agent orchestration, and establishes clear rules to prevent architecture drift.

Direct answer: It defines roles, rules, and escalation paths to coordinate a multi agent serverless planning effort with a single source of truth.

When to Use This AGENTS.md Template

• When starting a serverless architecture project that uses AI coding agents for design, validation, and implementation.
• To establish cross agent responsibilities and handoff points before any code is written.
• When governance is required for tool access, secrets, and deployment of serverless components.

Copyable AGENTS.md Template

Below is a copyable AGENTS.md block you can paste into your project repo. It defines the project role, agent roster, supervisor behavior, handoffs, and rules specific to serverless planning.

# AGENTS.md

Project: Serverless Architecture Planning for [Your Project]

Objective
  - Provide a formal operating model for AI coding agents that plan, design, validate, and deploy a serverless stack using Lambda, API Gateway, Step Functions, and managed data stores.

Agent roster and responsibilities
  - Planner: defines objectives, success criteria, scope, and constraints; harmonizes business goals with technical feasibility.
  - Architect: designs the serverless stack (functions, state machines, APIs, data models); defines non functional requirements.
  - Implementer: builds serverless components, configures permissions, and codifies patterns in infrastructure as code.
  - Cost Analyst: estimates and optimizes runtime, storage, and data transfer costs; flags budget risks.
  - Security Reviewer: enforces least privilege, secret management, and compliance checks.
  - QA Tester: validates function behavior, SLAs, and integration points; ensures spec conformance.
  - Orchestrator: central supervisor that coordinates all agents, maintains context, and enforces memory rules.
  - Documentation Agent: records decisions, rationale, and traceable artifacts in the repository.

Supervisor or orchestrator behavior
  - Orchestrator coordinates tasks, enforces context synchronization, and stores a canonical memory of decisions.
  - All agents reference a shared source of truth and do not bypass orchestrator decisions.

Handoff rules between agents
  - Planner -> Architect when architecture outline is approved.
  - Architect -> Implementer when design is documented and ready for implementation.
  - Implementer -> QA Tester when features are ready for validation.
  - QA Tester -> Orchestrator when tests reveal risks or blockers; escalation to Security Reviewer as needed.
  - Orchestrator can trigger Human Review if policy or compliance flags arise.

Context, memory, and source-of-truth rules
  - Use a central repository as the source of truth (docs and IaC) and a memory store for in flight context.
  - All decisions and rationale are recorded in the project docs; avoid relying on ephemeral chat history.
  - Data models, APIs, and integration contracts are versioned and stored in the docs folder.

Tool access and permission rules
  - Agents inherit least privilege IAM roles; secrets are retrieved from a secret manager at runtime.
  - Do not hard code credentials; rotate secrets; access keys are scoped to the task and time window.
  - All API keys and credentials must be auditable and attached to approvals.

Architecture rules
  - Event driven, with clear boundaries between functions; idempotent and retryable; state stored in a durable store.
  - Use serverless primitives: Lambda for compute, API Gateway for APIs, Step Functions for orchestration, DynamoDB/S3 for state and artifacts.
  - Prefer declarative IaC with versioned templates; all changes require pull requests and reviews.

File structure rules
  - infrastructure/  (IaC templates and deployment scripts)
  - functions/       (serverless function code)
  - data/            (data models and seeds)
  - tests/           (unit and integration tests)
  - docs/            (AGENTS.md, decisions, contracts)
  - scripts/         (utility scripts)

Data, API, or integration rules when relevant
  - Define data contracts and API specs up front; share OpenAPI or similar contracts in docs.
  - Use environment specific configurations; never embed production secrets in code.
  - Record integration points and versioned endpoints in the docs.

Validation rules
  - Every function must have unit tests and contract tests; integration tests cover end-to-end flow.
  - Static analysis and linting run on CI; IaC is validated before deployment.

Security rules
  - Enforce encryption at rest and in transit; rotate secrets regularly; limit public exposure.
  - IAM roles are strictly scoped to required actions; monitor for policy drift.

Testing rules
  - CI runs unit, integration, and end-to-end tests; canary releases for production serverless components.

Deployment rules
  - Deploy using CI/CD pipelines with approvals; use canary or blue/green strategies for production updates.

Human review and escalation rules
  - PRs must pass reviews from security and architecture before merge; escalations go to Orchestrator and if needed to Human Review.

Failure handling and rollback rules
  - Implement retry policies and circuit breakers; support rollback by reverting IaC state and reconstructing on failure.

Things Agents must not do
  - Do not deploy to production without approval; do not reveal secrets; do not bypass governance; do not drift from the documented context.

# End AGENTS.md

Recommended Agent Operating Model

Roles, boundaries, and escalation paths for a serverless architecture planning workflow. This model clarifies decision rights and how agents coordinate to produce a correct serverless design and its implementation, while enabling safe escalation when risks arise.

Recommended Project Structure

infrastructure/
functions/
data/
tests/
docs/
scripts/

Core Operating Principles

• Single source of truth for decisions and contracts.
• Clear, enforceable handoffs between agents.
• Least privilege and secret management by default.
• Idempotent, auditable, and testable changes.
• Early validation and incremental rollout of serverless components.

Agent Handoff and Collaboration Rules

Planner hands off to Architect; Architect hands off to Implementer; Implementer passes to QA; QA escalates to Orchestrator or Security Reviewer as needed. Domain specialists can be consulted for API contracts or cost optimization.

Tool Governance and Permission Rules

Define who can edit IaC, who can deploy, how secrets are accessed, and how approvals are granted. All tool usage must be auditable and reversible.

Code Construction Rules

Follow serverless best practices: small, focused functions; stateless design; explicit retries; explicit timeouts; observable logging.

Security and Production Rules

Minimum viable security, encryption, secret management, and access control. Production changes require documented approvals and canary deployment with rollback strategies.

Testing Checklist

• Unit tests for each function
• Contract/integration tests for APIs
• End-to-end workflow tests with state machines
• CI checks for IaC and configurations

Common Mistakes to Avoid

• Bypassing planner to implementer without architecture sign off
• Hard coding secrets or using broad IAM permissions
• Ignoring state management and idempotency in serverless flows
• Unclear handoffs causing context drift

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 Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the purpose of this AGENTS.md Template for serverless architecture planning?

This AGENTS.md Template defines the operating model for AI coding agents in a serverless planning workflow, enabling multi agent orchestration, clear handoffs, and a single source of truth.

Who should use this AGENTS.md Template?

Product teams, platform engineers, and engineering leaders implementing serverless architectures with AI agents should use it to align roles and governance.

How does multi-agent orchestration work here?

The template specifies an orchestrator and role-specific agents (Planner, Architect, Implementer, Reviewer) with explicit handoffs and shared context.

How are handoffs and escalation handled?

Handoffs follow a defined path: Planner -> Architect -> Implementer, with Reviewer and Human Review as escalation paths when risk or blockers arise.

What are the security and deployment considerations?

It enforces least privilege, secret management, audit trails, and controlled deployment via CI/CD and canary releases for serverless components.