AGENTS.md Template for Next.js Production Architecture

Overview

Direct answer: This AGENTS.md template defines the operating context for AI coding agents within a Next.js production architecture, enabling both single-agent workflows and multi-agent orchestration. It specifies roles, handoffs, memory, tool governance, and human review to ensure safe, monitored production delivery.

When to Use This AGENTS.md Template

Use this template when you are setting up a Next.js production project that relies on AI coding agents for development tasks, integration work, and code validation. It helps teams coordinate across planner, implementer, reviewer, tester, researcher, domain specialist, and orchestrator roles.

When starting a new Next.js production architecture project that leverages AI agents for planning and execution.
When establishing clear agent handoff rules and governance for secure tool usage.
When you need a single source of truth for project context, constraints, and memory.
When you require a repeatable operating model for multi-agent coordination and handoffs.

Copyable AGENTS.md Template

Below is a complete, copyable AGENTS.md block that you can paste into your repository as project-level operating context for single-agent and multi-agent work.

# AGENTS.md
Project role: Platform Lead
Agent roster:
  - Planner: defines objectives, success criteria, milestones, and coordinates the roster.
  - Implementer: builds features, integrates Next.js production architecture components, writes code and tests.
  - Researcher: gathers domain knowledge, validates external integrations, and collects data samples.
  - Domain Specialist: ensures domain constraints, compliance, and routing rules are respected.
  - Reviewer: reviews code and agent behavior for quality and safety.
  - Tester: runs tests, monitors outputs, and validates acceptance criteria.
  - Orchestrator: supervises multi-agent collaboration, memory, and handoffs; enforces governance.
Supervisor or orchestrator behavior:
  - Maintains a shared memory store of context, decisions, and evidence.
  - Logs decisions with rationale and timestamps.
  - Enforces tool governance, permission checks, and escalation when needed.
Handoff rules between agents:
  - Planner -> Implementer on approved plan.
  - Implementer -> Reviewer after code and tests, then Tester.
  - Researcher/Domain Specialist -> Implementer as needed for data or constraints.
  - Orchestrator validates handoffs, updates memory, and signals next phase.
Context, memory, and source-of-truth rules:
  - Context lives in a central memory store and is sharded by task.
  - Source of Truth is the Git history, PRs, CI logs, and issue tracker.
  - Memory updates are appended, immutable unless explicitly revised via plan.
Tool access and permission rules:
  - Access to Git, secrets vault, environment variables, and deployment gates are role-based.
  - API keys are accessed via secret manager with rotation policy.
  - Production access requires final approval from Reviewer and Orchestrator.
Architecture rules:
  - Next.js app using App Router with TypeScript, SSR, and incremental static regeneration where appropriate.
  - Clear separation between frontend, API routes, and data services.
  - Observability through logging, tracing, and alerting.
File structure rules:
  - Only relevant folders for the Next.js production architecture and agent orchestration.
  - No duplicate work; reuse shared components and utilities.
Data, API, or integration rules when relevant:
  - All external calls are authenticated and logged.
  - Rate limiting, retries, and backoff policies are enforced.
Validation rules:
  - Validation by unit tests, type checks, linting, and end-to-end checks where feasible.
Security rules:
  - Secrets never commit to VCS; rotate secrets; principle of least privilege; audit trails.
Testing rules:
  - Unit tests for components and hooks; integration tests for API boundaries; end-to-end tests when possible.
Deployment rules:
  - Deploy via PR gates to staging; require human sign-off for production.
Human review and escalation rules:
  - If failures occur, escalate to Orchestrator and Domain Specialist; enable rollback via Git.
Failure handling and rollback rules:
  - Revert commits, re-run tests, and revalidate before production.
Things Agents must not do:
  - Bypass tests, deploy without approval, access production data beyond scope, or modify secrets in-flight.

Recommended Agent Operating Model

Summary: Each role has explicit decision boundaries, escalation paths, and collaboration patterns to ensure safe multi-agent execution in a Next.js production environment.

Planner: designs objectives, success criteria, constraints, and plan correctness checks; authority to adjust milestones requires approvals.
Implementer: develops code aligned to plan; seeks Planner input for ambiguities; must publish test results and traces.
Researcher: validates data and external integrations; maintains knowledge about data formats and constraints; escalates when data is questionable.
Domain Specialist: ensures domain-specific rules and regulatory considerations are followed; provides domain-context constraints to Implementer.
Reviewer: reviews code, checks for security and reliability; ensures compliance with architecture rules.
Tester: validates behavior in staging; records acceptance criteria and edge cases.
Orchestrator: coordinates across agents, enforces governance, maintains memory, handles escalations and rollbacks.

Recommended Project Structure

root/
  apps/
    nextjs-prod/
      app/
      src/
        pages/
        components/
        lib/
        services/
  agents/
    planner/
    implementer/
    researcher/
    domain-specialist/
    reviewer/
    tester/
  orchestrator/
  infra/
    cloud/
  configs/
  scripts/
  tests/
  docs/

Core Operating Principles

Operate with a single source of truth; record decisions, context, and evidence in memory and logs.
Follow explicit handoff rules; never improvise handoffs without orchestrator validation.
Respect tool governance and secrets management; never expose secrets in logs or code.
Prefer deterministic results; stub non-deterministic calls in tests.
Prioritize security and production-readiness; validate before deployment.

Agent Handoff and Collaboration Rules

Rules by role (where relevant):

Planner -> Implementer: handoff plan with milestones, success criteria, and context.
Implementer -> Reviewer: share code, tests, and traces; wait for approval.
Reviewer -> Orchestrator: escalate if security or architecture concerns arise.
Researcher -> Implementer: provide validated data and integration constraints.
Domain Specialist -> Implementer: ensure domain-specific constraints are applied.
Orchestrator -> All: broadcast next action, enforce memory updates and access controls.

Tool Governance and Permission Rules

Commands permitted: git, node, npm/yarn, curl, and permitted internal CLIs; no direct database writes.
File edits restricted to agents with write access; changes go through PRs and approvals.
APIs and external services must be accessed via controlled endpoints with rate limits and logging.
Secrets stored in vault; no secrets in code; rotation required on schedule.
Production deployments gated by reviewer sign-off and orchestrator approval.

Code Construction Rules

Use TypeScript with strict mode; Next.js App Router; shared utilities in a/ and lib/.
Follow project-wide linting and formatting rules; unit tests accompany new code.
API surfaces designed with clear input/output contracts; include type definitions.
Do not duplicate logic across services; extract to shared modules.
All feature work must be validated against acceptance criteria in AGENTS.md.

Security and Production Rules

Secrets never appear in logs or client bundles.
Access to staging/production requires least privilege and audit trails.
Code must pass security checks; dependency scanning; vulnerability remediation.
Data localization and privacy controls as appropriate to domain.

Testing Checklist

Unit tests for components and hooks; integration tests for API boundaries.
End-to-end tests in staging; performance tests where applicable.
Linting, type checks, and CI checks as gatekeepers before deployment.

Common Mistakes to Avoid

Skipping handoffs; failing to update memory after decisions.
Exposing secrets or bypassing review gates.
Ambiguity in acceptance criteria or plan changes without revalidation.
Over-fitting the template to a non-Next.js architecture.

FAQ

What is the purpose of this AGENTS.md Template in Next.js production architecture?

This template provides a detailed operating manual for AI coding agents, outlining roles, handoffs, rules, and governance to support a safe, audited multi-agent workflow in a Next.js production environment.

How do agents hand off responsibilities?

Handoff is governed by explicit criteria: plan completion, artifacts, and memory updates; the orchestrator validates and updates the shared memory before the next phase.

How is memory and source of truth managed?

Context is stored in a centralized memory store; source-of-truth includes Git history, PRs, CI logs, and trackers; updates are immutable unless revised via the plan.

How are secrets and production access managed?

Secrets live in a vault with rotation; production access requires role-based approvals and separation of duties; logs audit all access.

What constitutes production readiness and deployment?

Code in production must pass tests, be reviewed, and receive final human sign-off before deployment to staging or production.

Target User

Use Cases