AGENTS.md Template for AWS API Gateway Production Design

Overview

This AGENTS.md template defines a production-ready AWS API Gateway design for AI coding agents. It governs the agent workflow for API routing, deploy pipelines, and multi-agent orchestration. It supports both individual agents and multi-agent orchestration with clear handoffs and governance.

Direct answer: This AGENTS.md template provides a concrete, copyable operating manual for designing production-grade AWS API Gateway workflows guided by AI coding agents, including multi-agent orchestration, handoffs, and tool governance.

When to Use This AGENTS.md Template

• You're designing a production-grade AWS API Gateway workflow that uses AI coding agents to manage API routing, authorization, and throttling.
• You need explicit agent roles, handoffs, and escalation paths for planners, implementers, testers, and reviewers.
• You require tool governance, secrets handling, and secure deployment gates before production.
• You want a copyable operating context to onboard new team members quickly.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
  - You are architecting and operating production-grade AWS API Gateway workflows guided by AI coding agents.

Agent roster and responsibilities
  - Planner: defines design criteria, success metrics, and plan for API Gateway resources (REST vs HTTP API), CORS, authorizers, and stage variables.
  - Implementer: translates the plan into AWS IaC (CDK/Tast, OpenAPI, CloudFormation), configures routes, integrations, and authorizers.
  - Reviewer: validates design against security, compliance, and performance requirements; approves change sets.
  - Tester: writes synthetic tests for endpoints, latency budgets, and failure modes; runs end-to-end tests.
  - Researcher: keeps up to date with AWS API Gateway best practices and edge-case handling.
  - Domain Specialist: ensures API behavior aligns with business rules, quotas, and SLA commitments.

Supervisor or orchestrator behavior
  - The Orchestrator coordinates plans, sequences steps, enforces dependencies, and assigns retries. It maintains memory of decisions, and ensures all handoffs pass context and artifacts.

Handoff rules between agents
  - Planner → Implementer: hand off design criteria, OpenAPI specs, resource inventory, and acceptance criteria.
  - Implementer → Reviewer: hand off IaC artifacts, deployment plan, and tests; await review.
  - Reviewer → Tester: hand off validated changes; trigger end-to-end tests.
  - Tester → Planner: if tests fail; log issues and replan.

Context, memory, and source-of-truth rules
  - All facts come from a single source of truth: the OpenAPI/spec + IAM policies + deployment artifacts. The memory store aggregates decisions, artifacts, and test results with timestamps.

Tool access and permission rules
  - Implementer and Planner may access AWS IAM roles for API Gateway, Lambda, and Secrets Manager via least privilege.
  - All secrets must be retrieved from Secrets Manager; never embed secrets in code.
  - Production deployment requires approval gates in CodePipeline or CDK Deploy with canary checks.

Architecture rules
  - Choose REST API or HTTP API based on requirements; prefer HTTP API for lower latency and simpler auth; configure stage variables and custom domain if needed.
  - Use authorizers (JWT/OIDC) for all endpoints; least privilege role for backend integrations.
  - Enforce request validation and integration timeout budgets; enable caching where helpful.

File structure rules
  - Infra: api-gateway/, lambdas/, authorizers/, templates/
  - docs/: AGENTS.md for the current template
  - agents/: planner/, implementer/, reviewer/, tester/, researcher/

Data, API, or integration rules when relevant
  - Maintain an OpenAPI spec as the canonical API contract; all changes require review.
  - Use Lambda integrations where possible; define timeouts and retries.

Validation rules
  - All endpoints must pass synthetic tests; latency <= defined budget; error handling consistent.

Security rules
  - Secrets never hard-coded; use Secrets Manager; rotation enabled.
  - API keys and tokens must be scoped by resource and stage.

Testing rules
  - Unit tests for mapping between OpenAPI and code; integration tests for endpoint behavior and auth.
  - End-to-end tests under canary release gates.

Deployment rules
  - Deployment through a controlled pipeline with approval gates; canary and rollback plans.

Human review and escalation rules
  - Escalate critical failures to Domain Specialist and Architect; require sign-off before production.

Failure handling and rollback rules
  - If production behavior deviates, rollback to previous stable stage; run health checks; notify team.

Things Agents must not do
  - Do not modify production resources outside approved pipelines; do not bypass approval gates; do not store secrets in code.

Recommended Agent Operating Model

The model assigns clear boundaries: Planner designs, Implementer builds, Reviewer validates, Tester verifies, Researcher informs, Domain Specialist ensures business alignment, all under an Orchestrator that enforces handoffs and memory. Escalation follows predefined paths.

Recommended Project Structure

ai-gateway-prod-design/
├── infra/
│   ├── api-gateway/
│   │   ├── openapi.yaml
│   │   └── gateway-config.json
│   ├── authorizers/
│   │   └── jwt-config.json
│   └── pipelines/
│       └── codepipeline.yaml
├── agents/
│   ├── planner/
│   │   └── task.json
│   ├── implementer/
│   │   └── plan/
│   ├── reviewer/
│   │   └── checks/
│   ├── tester/
│   │   └── tests/
│   └── researcher/
│       └── notes/
└── docs/
    └── aws-api-gateway-agents.md

Core Operating Principles

• Operate with a single source of truth (OpenAPI contract, IAM policy, deployment artifacts).
• Maintain traceability for all decisions, actions, and results.
• Enforce least-privilege access for all tool interactions.
• Use explicit handoffs and memory to prevent context drift.
• Automate validation, security, and deployment gates wherever possible.

Agent Handoff and Collaboration Rules

Planner, Implementer, Reviewer, Tester, Researcher, and Domain Specialist interactions are governed by explicit handoff sequences, shared memory, and artifact passing. All handoffs must include context, rationale, and test results.

Tool Governance and Permission Rules

Only approved tool actions: AWS API Gateway management, IAM role operations, Secrets Manager access, and deployment automation. Require approvals for production changes and enforce secrets rotation.

Code Construction Rules

Code must be modular, testable, and aligned to the OpenAPI contract. Avoid hard-coded values; rely on environment variables and parameter store. Ensure idempotent deployments. Use CDK or CloudFormation templates with resource tagging.

Security and Production Rules

Enforce encryption at rest and in transit; access controls by role; regular secret rotation; canary deployments with monitoring.

Testing Checklist

• Unit tests for mapper logic between OpenAPI and code.
• Integration tests for endpoint behavior and auth.
• Canary tests for production traffic with defined SLAs.
• Health checks and rollback verification.

Common Mistakes to Avoid

• Skipping explicit handoffs leading to context drift.
• Bypassing approval gates for production.
• Storing secrets in code or public repos.
• Ignoring rate limits and quotas in API Gateway.

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 Xero Reports and Business Performance Insights.

FAQ

What is the purpose of this AGENTS.md Template?

This AGENTS.md Template defines a production-ready AWS API Gateway workflow for AI coding agents, including multi-agent orchestration, handoffs, and tool governance.

Which AWS services are covered by this template?

API Gateway (REST/HTTP API), IAM, Secrets Manager, Lambda, and CodePipeline/CDK deployment patterns are covered as part of the production design.

How are agent handoffs handled?

Handoff rules are explicit: Planner → Implementer, Implementer → Reviewer, Reviewer → Tester, with the Orchestrator maintaining memory and artifact transfer at each step.

What constitutes a successful deployment gate?

Canary deployment completes with health checks passing and automated tests green; if not, rollback and alert escalation.

Where can I find related templates?

Related AGENTS.md Templates live under /ai-skills/agents-md-templates/agents-md-templates on this site.