Public API Platform Design AGENTS.md Template

Overview

AGENTS.md template for public API platform design provides a complete operating manual for AI coding agents engaged in designing, validating, and governing a public API platform. It governs both single-agent work and multi-agent orchestration, including architecture decisions, contract and schema validation, security compliance, doc generation, and deployment handoffs. Direct answer: This template defines the standardized workflow, roles, and governance needed to design a scalable public API platform using AI agents and orchestrators.

It formalizes how agents reason, remember, and hand off work, how tool access is controlled, and how decisions are escalated to human review when necessary. It also includes explicit failure handling, rollback rules, and a no-surprises rule set to prevent context drift and architecture drift during ongoing API development.

When to Use This AGENTS.md Template

• You're designing or evolving a public API platform and need repeatable, auditable AI-guided design workflows.
• You require clear handoffs between planner, implementer, reviewer, tester, researcher, and domain specialist agents.
• You want strict tool governance, secrets management, and production-change controls for AI-generated changes.
• Your team relies on shared memory, sources of truth, and traceable decisions across iterations.
• You need a single source of project operating context that can be pasted into AGENTS.md to start a new API design initiative.

Copyable AGENTS.md Template

# AGENTS.md

Project: Public API Platform Design
Supervisor/Orchestrator: Platform Design Orchestrator (PD-O)

Agent roster:
- planner: API architecture planning, schema decisions, contract design
- implementer: code generation, SDK and gateway wiring
- reviewer: security, compliance, and quality gate
- tester: integration, end-to-end, contract tests
- researcher: standards, docs, and reference implementations
- domain specialist: authentication, authorization, networking, quota, rate limits

Supervisor/Orchestrator behavior:
- Maintains single source of truth for design decisions; coordinates handoffs; enforces tool governance; triggers human review when risk is detected.
- Monitors progress, detects context drift, and resets tasks if the memory window is exceeded.
- Applies rollback rules on failed deployments or failed validation results; logs rationale for all escalations.

Handoff rules between agents:
- Planner ➜ Implementer: provide design artifacts, code skeletons, and endpoint contracts.
- Implementer ➜ Reviewer: submit output with validation summary and risk notes.
- Reviewer ➜ Tester: approve test plan and test data; provision test environments.
- Tester ➜ Planner: report failures and propose remediation; loop until acceptance criteria met.
- Researcher ➜ Domain Specialist: hand off standards, examples, or external references; domain specialist validates applicability.

Context, memory, and source-of-truth rules:
- Memory stores design decisions, contracts, and test results with versioned references.
- Source of truth: OpenAPI specs, contract tests, security policies, and docs are the canonical references.
- All non-committal notes are stored as task-scoped memories; avoid embedding long-term assumptions without citation.

Tool access and permission rules:
- Only PD-O and assigned agents can access production service keys; secrets rotation must be logged and audited.
- API calls to live systems require approval gates; read-only access is the default for planning tasks.
- All file edits must be committed via a formal PR workflow with code review.

Architecture rules:
- Use a modular API gateway, clear separation between surface API and internal services, and well-defined versioning.
- Maintain backward compatibility where possible; deprecate features with a documented sunset plan.
- Document all architectural decisions in the AGENTS.md and linked artifacts.

File structure rules:
- Keep design artifacts under api-design/ with endpoints, schemas, contracts, docs, and tests.
- Do not mix concerns; isolate gateway, service implementations, and clients.

Data, API, or integration rules:
- Use OpenAPI 3.x for contracts; ensure schemas are aligned with internal models.
- Validate against contract tests before merging design changes.
- Apply rate limiting and quotas at the gateway layer; reflect in docs.

Validation rules:
- All API design decisions must pass security, performance, and compatibility validations.
- Document validation results and any trade-offs.

Security rules:
- Never expose secrets in code or docs.
- Enforce least privilege for agents; rotate keys regularly.
- Require authentication for privileged actions and audits for changes to production paths.

Testing rules:
- Include unit, integration, contract, and end-to-end tests; tests must be green before promotion.
- Use mock services for isolated tests; provide test data contracts.

Deployment rules:
- Changes to the public API surface require staging deploys and a security review.
- All changes must go through a PR-based workflow; automated checks must pass.

Human review and escalation rules:
- Escalate critical design risks to the human architect ownership; all escalations are logged with rationale.
- Maintain a weekly design review cadence; document decisions and open items.

Failure handling and rollback rules:
- If a design decision causes production disruption, revert to last known-good contract and issue a remediation ticket.
- Ensure migration plans are in place before deprecations.

Things Agents must not do:
- Do not bypass approvals or skip tests; do not modify production in an uncontrolled manner.
- Do not introduce architectural drift or context drift without updating the source-of-truth artifacts.
- Do not rely on private data in prompts or share secrets via messages.

Recommended Agent Operating Model

The recommended operating model assigns clear roles, decision boundaries, and escalation paths for planning, implementing, validating, and deploying a public API platform. The orchestrator handles cross-agent coordination, memory hygiene, and risk scoring, while each agent specializes in a design domain (architecture, security, docs, tests, domain-specific concerns). Escalations are designed to keep the workflow auditable and reversible when needed.

Recommended Project Structure

api-design/
├── contracts/         # OpenAPI contracts, schemas, and contract tests
├── schemas/           # Data models and schema definitions
├── docs/              # Reference docs, onboarding, and examples
├── gateway/           # API gateway configuration and policies
├── services/          # Microservice implementations (stubs for design)
├── clients/           # SDKs and client examples
├── tests/             # Automated tests (unit, integration, contract, e2e)
├── infra/             # Infrastructure-as-code and environment setups
└── agents/            # Agent-specific templates and orchestration config
    ├── planner/
    ├── implementer/
    ├── reviewer/
    ├── tester/
    ├── researcher/
    └── domain-specialist/

Core Operating Principles

• Always include a documented source of truth and versioned decisions.
• Keep agent memory bounded and auditable; avoid long unreferenced context.
• Enforce tool governance and secret handling with audit trails.
• Prefer explicit handoffs and reversible changes; avoid silent edits to production paths.
• Ensure security, privacy, and compliance are foundational, not bolt-ons.

Agent Handoff and Collaboration Rules

Rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents ensure clean collaboration:

• Planner creates architecture and contracts; hands off alongside a validated OpenAPI fragment.
• Implementer transforms designs into code and SDK scaffolding; passes to Reviewer with a validation note.
• Reviewer validates security, compliance, and quality gates; approves or requests remediation.
• Tester runs contract, integration, and e2e tests; reports pass/fail with reproducible steps.
• Researcher ensures standards alignment and supplies references; Domain Specialist validates domain constraints.

Tool Governance and Permission Rules

• API calls to live systems require approval gates and read-only access for planning tasks.
• Edits to design artifacts require PRs and code reviews; secrets must never be stored in code.
• Production changes require staging validation, security review, and observable rollback plans.
• All tools used by agents must have access controls, rotation, and audit logging.

Code Construction Rules

• Generate modular, well-documented code; avoid tight coupling between services.
• Follow OpenAPI-first design; keep contracts in sync with implementations.
• Idempotent operations for design changes; deterministic code generation.
• Avoid duplicating logic across agents; share reusable utilities via a common library.

Security and Production Rules

• Never embed credentials; use encrypted secrets vaults and rotation policies.
• Enforce least privilege for all agents; document all elevated actions.
• Implement audit trails for all production changes; require human review for sensitive deployments.

Testing Checklist

• Unit, contract, integration, and end-to-end tests must pass before promotion.
• Test data contracts and edge-case API usage; validate error handling paths.
• Run security, performance, and compatibility tests; verify backward compatibility.

Common Mistakes to Avoid

• Skipping PR reviews or bypassing tests for speed.
• Allowing context drift or architecture drift without updating source-of-truth artifacts.
• Over-provisioning agents or exposing secrets in prompts or logs.

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 public API platform design?

This template defines a repeatable operating manual for AI coding agents to design, validate, and govern a public API platform, enabling multi-agent orchestration with clear handoffs and governance.

How do agents handoff when designing a public API platform?

Handoffs follow a structured flow: Planner -> Implementer -> Reviewer -> Tester, with Researcher and Domain Specialist providing domain-specific inputs as needed; all handoffs include artifacts, rationale, and acceptance criteria.

What are the tool governance rules for this workflow?

Tools require approvals for production changes, secrets are rotated and never embedded in code, and edits go through PRs with auditable logs and access controls.

How is memory and source-of-truth managed?

Memory stores task-specific context; source-of-truth artifacts include OpenAPI contracts, security policies, and testing results, versioned and referenced in every decision.

What does a proper testing and deployment sequence look like?

Tests must cover unit, contract, integration, and end-to-end scenarios; deployment to staging requires security review and a rollback plan before production.