Frontend Performance Optimization AGENTS.md Template

Overview

This AGENTS.md template documents a frontend performance optimization workflow governed by AI coding agents. It supports both single-agent execution and multi-agent orchestration, where planners, implementers, reviewers, researchers, testers, and domain specialists collaborate to reduce runtime, improve Core Web Vitals, and meet performance budgets. It provides a clear operating context that reduces drift and accelerates delivery while preserving tool governance and human review where needed.

Direct answer: Use this AGENTS.md template to codify roles, handoffs, constraints, memory, and decision rules for frontend performance optimization across single-agent and multi-agent scenarios.

When to Use This AGENTS.md Template

• Launching a performance initiative with a defined budget (e.g., CPI, LCP, TBT targets).
• Coordinating multiple agents (planner, implementer, reviewer, researcher, tester, domain specialist) to optimize a frontend feature or page.
• Establishing governance around tooling, metrics, data sources, and deployment gating for performance changes.
• Capturing project-level operating context for repeatable frontend optimization workflows.

Copyable AGENTS.md Template

# AGENTS.md

## Project: Frontend Performance Optimization

### 1) Project role
- Goal: Achieve measurable frontend performance improvements within defined budgets (LCP, CLS, TTI, TBT).
- Scope: Optimize initial render and interactive performance for a specific page or feature, with reproducible steps and safety checks.

### 2) Agent roster and responsibilities
- Planner/Architect: defines performance budget, success criteria, and orchestration plan. Creates task queue for Implementer.
- Implementer: applies code changes, bundling, lazy loading, image optimization, and caching strategies to meet budgets.
- Researcher: collects performance data, sources best practices, and ensures alignment with Web Vitals guidance.
- Reviewer: validates changes against budgets, audits Lighthouse/Real User Metrics, and reviews for regressions.
- Tester: runs automated tests, CI checks, and visual regressions.
- Domain Specialist: provides expertise on Core Web Vitals, interaction readiness, and accessibility implications of performance changes.

### 3) Supervisor or orchestrator behavior
- The Planner maintains the runbook and priorities; the Orchestrator triggers work, handles handoffs, and coordinates reviews.
- Handoff points: Planner -> Implementer after budget agreement; Implementer -> Reviewer after changes; Reviewer -> Tester before deployment.
- Escalation: if budgets cannot be met within constraints, escalate to a product or platform lead.

### 4) Handoff rules between agents
- Trigger: when a target budget or metric is agreed, Planner assigns Implementer tasks with acceptance criteria.
- Transfer: Implementer commits changes and generates Lighthouse/metrics report; Reviewer validates results; if passing, Tester runs CI tests.
- Reentry: if failures occur, return to Planner for re-plan.

### 5) Context, memory, and source-of-truth rules
- Source of truth: package.json, webpack/rollup config, Lighthouse audits, Web Vitals data, CI logs, and bug trackers.
- Memory: summarize decisions in a canonical AGENTS.md block per feature/page; store in repo under /ai-skills/agents-md-templates/planner/ or /ai-skills/agents-md-templates/ Implementer/ as appropriate.
- Context limits: keep only relevant targets (domains, routes, and assets involved in the optimization).

### 6) Tool access and permission rules
- Implementer has write access to code and build configs in the feature branch.
- Reviewers and domain specialists have read access to code, audits, and metrics; they may comment and request changes but should not push to main.
- Secrets: never store secrets in code; use repo-scoped or vault-based secrets with access gates.

### 7) Architecture rules
- Prefer perf budgets and gradual changes; apply performance budgets for each feature.
- Avoid global rewrites; incrementally optimize critical paths with measurable gains.
- Ensure accessibility and UX consistency are preserved during optimizations.

### 8) File structure rules
- Keep agent logs, budgets, and results in a clearly named folder per feature: /ai-skills/agents-md-templates/[planner|implementer|reviewer|tester|researcher|domain]/[feature-id].
- Centralize performance data under /performance or /metrics folders.
- Do not add unrelated folders or unused tech.

### 9) Data, API, or integration rules
- Pull performance data from Lighthouse, WebPageTest, and Real User Monitoring where available.
- Do not expose production API keys in code or commits.
- Validate API changes do not worsen performance.

### 10) Validation rules
- All changes must demonstrate improvement against the defined budgets with documented evidence.
- Run automated Lighthouse audits, VOC/CLS checks, and regression tests.
- Results must be stored in the designated metrics folder.

### 11) Security rules
- Access controls must restrict deployment to approved branches; require PR reviews for production changes.
- Do not bypass security checks or approvals.

### 12) Testing rules
- Include unit tests for critical components, integration tests for lazy-loading/route-based code splitting, and perf regression tests.
- Tests must pass in CI before merge.

### 13) Deployment rules
- Deploy only after successful review and automated tests.
- Use canaries for production changes affecting performance; monitor KPIs before full rollout.

### 14) Human review and escalation rules
- Human review is required for all changes affecting user-visible performance budgets.
- Escalate any decision that risks user experience or budget violations.

### 15) Failure handling and rollback rules
- If a deployment degrades performance beyond thresholds, rollback to previous release and reopen issue with findings.
- Maintain rollback scripts and documented steps.

### 16) Things Agents must not do
- Do not push changes that regress performance budgets.
- Do not bypass reviews or security gates.
- Do not reuse stale data without reconciling source-of-truth.
- Do not perform production changes without canaries and proper approvals.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to support both single-agent and multi-agent orchestration for frontend performance optimization. The Planner sets goals and budgets; Implementer executes changes; Researcher and Domain Specialist provide data and expertise; Reviewer and Tester validate and gate changes before deployment. If a decision lies outside defined budgets or requires product impact assessment, escalate to leadership. Multi-agent coordination uses explicit handoffs with objective acceptance criteria and a shared memory of decisions.

Recommended Project Structure

frontend-performance-optimization/
├── agents/
│   ├── planner/
│   │   └── README.md
│   ├── implementer/
│   │   └── README.md
│   ├── reviewer/
│   │   └── README.md
│   ├── tester/
│   │   └── README.md
│   ├── researcher/
│   │   └── README.md
│   └── domain-specialist/
│       └── README.md
├── performance/
│   ├── budgets.json
│   ├── metrics/
│   │   ├── lighthouse.json
│   │   └── web-vitals.json
├── src/
│   ├── components/
│   │   └── ...
│   ├── hooks/
│   │   └── ...
│   └── pages/
│       └── ...
├── scripts/
│   └── perf-ci.sh
├── tests/
│   └── perf/
└── docs/
    └── AGENTS.md

Core Operating Principles

• Clear ownership and traceable decisions.
• Data-driven optimization with measurable budgets.
• Explicit handoffs and gating for multi-agent workflows.
• Reproducibility and auditable results in metrics and logs.
• Security, privacy, and production-readiness baked into every step.

Agent Handoff and Collaboration Rules

• Planner to Implementer: deliver a task with acceptance criteria and performance budgets.
• Implementer to Reviewer: submit changes and performance evidence (Lighthouse, Core Web Vitals).
• Reviewer to Tester: approve test plan and CI checks before deployment.
• Researcher/Domain Specialist: provide data, guidance, and risk flags, especially for budgets and accessibility implications.
• All agents must request clarification if requirements are ambiguous; avoid silent assumption drift.

Tool Governance and Permission Rules

• Commands to measure performance require explicit approval and must log results.
• Code edits require PRs and code reviews; no direct pushes to main.
• API calls and secrets must be accessed via secure vaults; never store in code.
• Production system changes require canaries, monitoring, and rollback plans.
• Handoffs must include a changelog and rationale for the performance budget decision.

Code Construction Rules

• Prioritize code-splitting, lazy loading, and image optimization for the targeted page/feature.
• Maintain visual and functional parity; performance gains must not degrade UX accessibility.
• Annotate performance budgets in code and in the AGENTS.md memory logs.
• Keep changes isolated to the intended feature scope; avoid broad refactors without validation.

Security and Production Rules

• Deploys gated by PR reviews and automated tests; canaries must be observed before global rollout.
• Secrets must be rotated and stored securely; never embed in code or AGENTS.md blocks.
• Audit trails for performance changes should be preserved for compliance and rollback.

Testing Checklist

• Automated unit tests for modified components; no functional regressions.
• Integration tests for new code-splitting and lazy-loading behavior.
• Performance tests showing improvement against budgets (LCP, CLS, TBT).
• End-to-end tests validating user-visible correctness remains intact.
• Canary and rollback checks in staging before production deployment.

Common Mistakes to Avoid

• Over-optimizing without measurable gains; always prove with metrics.
• Drifting away from budgets or failing to update memory and sources of truth.
• Skipping reviews or bypassing security gates.
• Introducing regressions in UX or accessibility for minor perf wins.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for frontend performance optimization?

It codifies roles, rules, and decision boundaries so AI coding agents can collaborate to improve frontend performance with measurable, auditable results.

Who are the agents and what are their responsibilities?

Planner defines budgets and strategy; Implementer applies optimizations; Researcher gathers data; Domain Specialist advises on Web Vitals; Reviewer validates; Tester tests; all collaborate through explicit handoffs.

How are handoffs between agents managed?

Handoffs occur at predefined milestones with acceptance criteria, results evidence, and a memory log. If criteria aren’t met, agents escalate and replan.

What are the security and production rules?

Only gated, reviewed changes reach production; secrets are kept out of code; canaries and monitoring guard production changes with rollback procedures ready.

How do you validate performance improvements?

Use Lighthouse audits, Core Web Vitals metrics, and real-user monitoring data; compare against budgets; ensure no UX regressions.

What should I do if something goes wrong?

Rollback to the previous release, investigate root cause, and reopen the issue with findings; adjust budgets or memos as needed.