AGENTS.md Template for Kong API gateway design

Overview

Direct answer: This AGENTS.md template defines roles, responsibilities, and governance for AI coding agents to design Kong API gateway configurations, enabling both single-agent work and multi-agent orchestration.

The AGENTS.md template establishes a project-level operating context for Kong gateway design. It captures the agent roster, supervision model, handoff rules, memory and source-of-truth management, tool access, architecture decisions, and production safeguards to support reliable, auditable automation.

When to Use This AGENTS.md Template

• Starting a Kong API gateway design project that requires formal operating context for AI agents.
• Coordinating a multi-agent workflow (planner, implementer, tester, reviewer, researcher, domain expert) for routes, services, plugins, and policies.
• Enforcing tool governance, security, and approval gates before deployment to staging or production.
• Onboarding new teams with a copyable template for consistent agent behavior.
• Auditing agent actions and maintaining a single source of truth across Kong configs and OpenAPI specs.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Kong Gateway Design for microservices; defines agent responsibilities, workflow, and governance for AI agents operating a Kong API gateway design project.

Agent roster and responsibilities:
- Planner: defines gateway topology, route and plugin strategy, and policy decisions.
- Implementer: translates the plan into Kong declarative config (kong.yaml, routes.yaml, services.yaml, plugins.yaml).
- Reviewer: validates correctness, security, and compliance of configurations and policies.
- Tester: executes validation tests, simulates traffic, and verifies route/plugin behavior.
- Researcher: gathers API specs (OpenAPI), upstream services, and domain requirements.
- Domain Specialist: provides domain-level policies (security, rate limits, access control).
- Security Auditor: reviews secrets handling, access controls, and production safety.
- Ops/Deployment: manages staging/prod promotion, CI/CD gates, and rollback procedures.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates plan creation, ensures context transfer between agents, triggers validation, and aggregates artifacts. It enforces memory updates and source-of-truth synchronization.

Handoff rules between agents:
- Planner → Implementer: provide detailed config mapping and asset inventory.
- Implementer → Reviewer: deliver diffs, config samples, and test results.
- Reviewer → Tester: publish test plan and sign-off criteria.
- Researcher involvement when API specs or upstream changes occur.
- Domain Specialist involvement at policy decisions or new control requirements.

Context, memory, and source-of-truth rules:
- Context: persistent problem framing, goals, and constraints are stored in memory.
- Memory: outputs, decisions, and versions are written to memory/[project-id].
- Source-of-truth: Kong declarative config, OpenAPI specs, and deployment policies serve as the canonical references.

Tool access and permission rules:
- Kong Admin API access is allowed only in non-production (staging) environments unless approved for prod.
- Secrets must be retrieved from secure vaults; no secrets stored in code or AGENTS.md blocks.
- External services access is constrained by environment policies and token scopes.

Architecture rules:
- Use declarative Kong config with modular plugins for each route/service.
- Enforce TLS, mTLS where applicable; avoid plaintext credentials in configs.
- Route matching and service definitions must be explicit and versioned.

File structure rules:
- All configuration and policy assets live under a version-controlled directory; avoid unrelated files.

Data, API, or integration rules:
- Use OpenAPI specs for upstream APIs; keep API shapes stable and versioned.
- Validate against OpenAPI contracts before generating Kong routes.

Validation rules:
- Lint config files; run config tests against a Kong in a disposable environment; ensure idempotent applies.

Security rules:
- Do not commit credentials; rotate tokens; restrict Admin API exposure; enforce least privilege.

Testing rules:
- Unit tests for config generation, integration tests with Kong in staging, and end-to-end tests for route and plugin behavior.

Deployment rules:
- Gate deployments through a staged CI/CD flow with approval, automated tests, and rollback capability.

Human review and escalation rules:
- If tests fail or policy drift occurs, raise escalation to Domain Specialist and Security Auditor before proceeding.

Failure handling and rollback rules:
- Apply changes idempotently; have a rollback plan to revert to last known good configuration in case of failure.

Things Agents must not do:
- Do not bypass tests or approvals; do not hard-code secrets; do not make production changes without sign-off; do not drift from canonical OpenAPI specs or Kong config.

Recommended Agent Operating Model

The agent operating model defines distinct roles, decision boundaries, and escalation paths to enable effective multi-agent orchestration for Kong API gateway design. The Planner creates a design blueprint and gates acceptance; the Implementer translates blueprint into Kong declarative config; the Reviewer validates against policy and security; the Tester confirms behavior under simulated traffic; the Researcher and Domain Specialist provide API specs and policy guidance; the Security Auditor validates risk controls; and Ops/Deployment handles promotion and rollback. Escalations route through the Orchestrator when blockers occur or when policy exceptions are needed.

Recommended Project Structure

kong-gateway-project/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   ├── domain-specialist/
│   ├── security-auditor/
│   └── ops-deployment/
├── configs/
│   ├── kong-declarative-config.yaml
│   ├── routes.yaml
│   ├── services.yaml
│   └── plugins.yaml
├── memory/
├── docs/
├── scripts/
└── tests/

Core Operating Principles

• Operate with a single source of truth for all Kong configurations and API specs.
• Ensure changes are traceable, auditable, and reversible.
• Enforce least-privilege access to all tools and environments.
• Keep memory state explicit; avoid implicit context leakage between agents.
• Respect domain-specific policies early in design to reduce rework.

Agent Handoff and Collaboration Rules

• Planner to Implementer: hand off design artifacts, topology decisions, and a mapping from routes/services to config files.
• Implementer to Reviewer: share generated config, diffs, and test results; include rationale for changes.
• Reviewer to Tester: provide acceptance criteria and test plan alignment.
• Researcher to Domain Specialist: deliver API specs, security considerations, and policy references.
• Domain Specialist to Implementer: translate domain policies into config and plugins where relevant.
• All handoffs require updated memory and a refreshed source-of-truth reference.

Tool Governance and Permission Rules

• Access to Kong Admin API is restricted by environment; prod requires formal approvals.
• Secrets must be retrieved from a secured vault; never embedded in code or templates.
• Config changes must be reviewed and signed off before deployment to staging or production.
• CI/CD gates must enforce tests, linting, and policy checks prior to promotion.

Code Construction Rules

• Use declarative Kong configuration in kong.yaml with explicit route/service/plugin definitions.
• Version configuration files and track changes in memory and config repository.
• Keep OpenAPI specs up to date and align routes with spec definitions.
• Avoid duplicating route definitions; reuse plugins via modular templates where possible.

Security and Production Rules

• Enforce TLS; disable insecure protocols; restrict Admin API access.
• Rotate all credentials; use secret stores and short-lived tokens where feasible.
• Perform runtime security checks (rate limiting, IP allowlists, bot protection) in staging before prod.

Testing Checklist

• Unit tests for config generation and schema validity.
• Integration tests with Kong in a disposable environment.
• End-to-end tests for route matching, plugin behavior, and policy enforcement.
• Smoke tests after deployment to staging; rollback plan ready.

Common Mistakes to Avoid

• Skipping validation or security checks in preference to speed.
• Bypassing handoffs or failing to preserve source-of-truth during migrations.
• Injecting secrets into code or templates.
• Overly complex plugin chains that reduce observability and increase risk.

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 Kong API gateway design?

It defines a formal operating manual for AI coding agents to work together on Kong gateway design, ensuring consistent behavior, governance, and traceability.

How many agents are involved and what are their roles?

Planner, Implementer, Reviewer, Tester, Researcher, Domain Specialist, Security Auditor, and Ops/Deployment have defined responsibilities for end-to-end workflow.

How are handoffs and escalation handled between agents?

Handoffs follow a predefined choreography with explicit context transfer; escalations route through the Orchestrator when blockers occur or policy exceptions are needed.

What security and access controls apply in this workflow?

Secrets are stored securely; Admin API access is restricted by environment; prod deployments require approvals; no secrets are stored in code.

How is validation and testing performed before deployment?

Unit tests for config generation, integration tests with Kong in staging, and end-to-end tests for route and plugin behavior are required before deployment; production requires sign-off.