AGENTS.md Template: API Pagination Design

Overview

Direct answer: This AGENTS.md Template for API Pagination Design provides a complete operating manual for AI coding agents to govern pagination workflows, including single-agent design and multi-agent orchestration patterns. It codifies roles, memory, tool governance, and escalation paths to ensure reliable, observable pagination across APIs.

The AGENTS.md template governs how AI coding agents collaborate to design, implement, validate, and govern API pagination strategies (cursor-based, token-based, or offset-based) across services. It supports both individual agent execution and multi-agent orchestration with clear handoffs and shared memory.

When to Use This AGENTS.md Template

• When designing or evolving API pagination across microservices or distributed APIs.
• When you need a reproducible, auditable pagination design with role-based responsibilities.
• When multi-agent coordination and handoffs are required for design, implementation, validation, and review.
• When enforcing tool governance, secrets handling, and production safeguards in paging workflows.
• When a single source of truth for paging contracts and versioned specs is essential.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- API Pagination Design and Governance Agent Network. Coordinates design, implementation, validation, and monitoring of API pagination across services using AI agents.

Agent Roster and Responsibilities
- PaginationArchitect (Planner): defines pagination strategy (cursor-based, token-based, or offset-based), contracts, and success criteria. Produces a paging design spec.
- PaginationEngine (Implementer): implements paging handlers, enforces the design contract, updates endpoints, and ensures contract conformance.
- PaginationQA (Verifier): conducts correctness, boundary, and performance validation against the spec.
- SecurityReviewer (Reviewer): checks rate limits, auth, secrets handling, and deployment safety.
- PagingResearcher (Researcher): investigates token usage, edge cases, and optimizations.

Supervisor / Orchestrator Behavior
- PaginationOrchestrator oversees agent activities, manages memory, and coordinates handoffs. It issues work items, enforces gating, and surfaces escalation when ambiguity or risk is detected.

Handoff Rules Between Agents
- Planner -> Implementer: deliver paging design spec, endpoint contracts, and test criteria.
- Implementer -> Verifier: deliver code changes, pagination utilities, and integration tests.
- Verifier -> Reviewer: deliver validated results, risk notes, and security checks.
- Researcher -> Planner: deliver findings, alternative strategies, and supporting data.
- If conflicts arise, escalate to the Orchestrator for arbitration.

Context, Memory, and Source-of-Truth Rules
- Maintain a central knowledge store (design doc, OpenAPI contracts, paging rules, data schemas).
- Use stable identifiers and versioned artifacts for all paging endpoints.
- All decisions must reference primary sources (API specs, service contracts, and data models).

Tool Access and Permission Rules
- Agents may access code repos, CI/CD configurations, and API docs in read/write as permitted by role.
- Secrets must be retrieved from a secrets manager; never embedded in code.
- Production-system edits require explicit approval gates and rollback plans.

Architecture Rules
- Contract-first paging design with versioned artifacts.
- Decoupled paging components; single source of truth for paging behavior.

File Structure Rules
- Place design docs under docs/pagination/, code under src/pagination/, tests under tests/pagination.
- Do not duplicate paging logic across modules.

Data, API, or Integration Rules
- Paging endpoints must declare: paging parameter (page/limit or cursor), page size bounds, and max results.
- Maintain memory of last processed page and ensure idempotence for repeated requests.

Validation Rules
- Validate correctness across edge cases (empty pages, last page, large results).
- Validate performance under load (latency, throughput) and correctness after retries.

Security Rules
- No hard-coded secrets; use vault/secret manager.
- Enforce strict access for paging parameters to prevent information disclosure.

Testing Rules
- Unit tests for paging utilities; integration tests for endpoints; end-to-end tests for multi-service paging flows.

Deployment Rules
- CI gates: tests pass, code review approved, dependencies pinned.
- Deployment in canary/staged environments with monitoring for paging latency.

Human Review and Escalation Rules
- Escalate ambiguous paging requirements or security concerns to the Product Owner and Security Lead.

Failure Handling and Rollback Rules
- If paging design causes regressions, roll back to previous design version and re-run tests.
- Notify stakeholders on rollback decisions.

Things Agents Must Not Do
- Do not bypass approval gates or ignore escalation.
- Do not access production data outside approved endpoints.
- Do not store or expose secrets in logs or code.
- Do not mutate production data during paging experiments without a safe rollback plan.

Recommended Agent Operating Model

• Roles and boundaries: Planner defines the strategy; Implementer executes; Verifier validates; Reviewer secures; Researcher informs alternatives.
• Decision boundaries: Planner decides strategy; Implementer and Verifier validate against criteria; Escalations to Orchestrator for risk.
• Escalation paths: Use explicit escalation when ambiguity, safety, or performance thresholds are at risk.

Recommended Project Structure

api-pagination-design/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── tester/
│   ├── reviewer/
│   └── researcher/
├── docs/
│   └── pagination.md
├── src/
│   └── pagination/
├── tests/
│   └── pagination/
├── config/
└── data/

Core Operating Principles

• Single source of truth for paging contracts.
• Explicit memory and context management.
• Clear handoffs and accountability traces.
• Tool governance and secret management by design.
• Security-first and auditable decisions.

Agent Handoff and Collaboration Rules

• Planner to Implementer: provide design spec, endpoint contracts, and test criteria.
• Implementer to Verifier: provide code, utilities, and test results.
• Verifier to Reviewer: provide validation results and risk notes.
• Researcher to Planner: provide findings and options for paging strategies.
• Domain specialist input: loop in when non-standard data models affect paging.

Tool Governance and Permission Rules

• Commands and edits require role-based approval; use CI gates for changes.
• API calls must go through approved endpoints with auditing.
• Secrets must be fetched from secret stores; never embed in code or logs.
• Production-facing changes require a rollback plan and change window.
• All external service calls must be monitored and rate-limited.

Code Construction Rules

• Follow contract-first development for paging endpoints.
• Use typed interfaces and explicit pagination contracts.
• Idempotent paging operations and deterministic ordering.
• Minimal surface area for paging parameters; validate bounds aggressively.

Security and Production Rules

• Encrypt tokens in transit and at rest; rotate credentials regularly.
• Protect paging endpoints from exposure and abuse; implement throttling and auth checks.
• Audit paging design changes and maintain traceability for compliance.

Testing Checklist

• Unit tests for paging utilities and helpers.
• Integration tests for paging behavior across services.
• Performance tests for latency and throughput under load.
• Regression tests for contract changes.
• End-to-end tests for real-world paging flows.

Common Mistakes to Avoid

• Assuming paging works the same across all endpoints; tailor contracts per resource set.
• Skipping memory/context propagation between agents.
• Bypassing review gates or secret management steps.
• Ignoring edge cases like empty results, single-page results, and token validity issues.

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: API Pagination Design?

To codify a repeatable, auditable operating manual for AI coding agents to design, implement, and govern API pagination across services with clear roles, handoffs, and governance rules.

Who should use this template?

Developers, engineering leaders, and product teams building or evolving API pagination workflows that involve AI agents and multi-agent orchestration.

How are agent handoffs managed?

Through a central orchestrator that enforces contracts, passes artifacts, and requires validation at each stage before the next handoff.

What security considerations are required?

Secrets must be retrieved from secure stores, no credentials in logs, and production changes require approved gating and rollback plans.

What should I do if pagination design breaks production?

Rollback to the previous design, trigger a post mortem, and re-run tests with updated contracts before redeploying.

How is memory and source of truth maintained?

A centralized knowledge store with versioned design docs, API contracts, and paging rules that all agents reference during decisions.