AGENTS.md Template for Web Vitals Optimization

Overview

Direct answer: This AGENTS.md template provides a complete operating manual for AI coding agents that orchestrate web vitals optimization, enabling single-agent execution as well as multi-agent collaboration to improve Core Web Vitals (LCP, CLS, FID). It defines roles, rules, and governance to keep the workflow auditable, safe, and scalable.

The template governs an agent workflow that sequences planning, implementation, data collection, validation, and review, with explicit handoffs and memory every step of the way. It supports both autonomous single-agent actions and coordinated multi-agent orchestration to optimize performance for critical pages and user journeys.

When to Use This AGENTS.md Template

• Starting a web vitals optimization initiative with AI coding agents
• Coordinating planning, implementation, research, testing, and review across multiple agents
• Establishing governance and escalation paths for production-ready improvements
• Creating a reusable operating manual for future web performance work

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Web Vitals Optimization with AI Coding Agents

Agent roster and responsibilities:
- Planner: defines targets (LCP, CLS, FID budgets) and overall experiment plan
- Implementer: applies fixes (code changes, resource sizing, lazy loading, etc.)
- Researcher: collects metrics data sources and proposes hypotheses
- Tester: validates fixes against tests and device sets
- Reviewer: reviews changes for regressions and quality
- Domain Specialist: frontend/UX expert for critical pages

Supervisor or Orchestrator:
- Orchestrator Agent coordinates rosters, schedules tests, carries context, and enforces handoffs

Handoff rules between agents:
- Each handoff includes context, results, sources, and next action
- Implementer cannot proceed without Planner sign-off for the next action
- Researcher to Implementer handoffs must include data sources and hypotheses

Context, memory, and source-of-truth rules:
- Memory stored in /data/vitals/latest.json and a persistent artifact in /reports/vitals
- Source of truth: Lighthouse, WebPageTest, and RUM data; annotate findings with timestamps

Tool access and permission rules:
- Tools: Lighthouse, Chrome UX Report API, WebPageTest, CDP (read-only unless approved)
- Secrets stored in a vault; never log secrets

Architecture rules:
- Modular agents with explicit inputs/outputs; orchestrator enforces boundaries
- Each agent runs in isolation with deterministic outputs

File structure rules:
- All artifacts under web-vitals-optimization/
- data/vitals/ for metrics, reports/ for outputs, configs/ for settings

Data, API, or integration rules when relevant:
- Use Lighthouse for core metrics; PageSpeed Insights for supplementary data
- Do not rely on a single data source without cross-checking

Validation rules:
- Every fix must pass a composite score threshold before promotion

Security rules:
- Production changes require approval; secrets are stored securely and never logged

Testing rules:
- Unit tests for scripts, integration tests for data flows, end-to-end testing for page loads

Deployment rules:
- Deploy with feature flag; rollback to last stable if metrics worsen

Human review and escalation rules:
- Any production change requires human review; escalate on CI failure

Failure handling and rollback rules:
- If metrics worsen, revert to the last stable artifact, revalidate, and re-run the plan with adjusted parameters

Things Agents must not do:
- Do not bypass approvals; do not modify production without explicit authorization
- Do not disclose secrets; do not drift away from the defined context

Recommended Agent Operating Model

Agents have defined roles and decision boundaries with escalation paths to ensure safe governance of web vitals improvements.

• Planner decides goals and acceptance criteria
• Implementer executes fixes within approved scope
• Researcher gathers data and validates hypotheses
• Tester verifies changes across scenarios
• Reviewer ensures no regressions and alignment with UX goals
• Domain Specialist advises on frontend implications
• Orchestrator manages handoffs and memory persistence

Recommended Project Structure

web-vitals-optimization/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── researcher/
│   ├── tester/
│   └── reviewer/
├── configs/
├── data/
├── scripts/
├── reports/
└── docs/

Core Operating Principles

• Clear ownership and explicit handoffs
• Single source of truth for metrics and decisions
• Defensive approvals and escalation when needed
• Guardrails against context drift and architecture drift

Agent Handoff and Collaboration Rules

Define who can handoff to whom and under what conditions. Planner > Implementer; Researcher > Implementer; Implementer > Tester; Tester > Reviewer; Domain Specialist consults as needed.

Tool Governance and Permission Rules

• Commands must be explicit and auditable
• Code edits require review and approval
• APIs calls require scope restrictions; secrets stored securely
• Production access requires multi-person approval

Code Construction Rules

• Code changes must be small, reversible, and well-documented
• All metrics queries should be versioned and reproducible
• Avoid duplicating logic across agents

Security and Production Rules

• Never print secrets; rotate credentials periodically
• Use feature flags for production rollout
• Implement strict access controls for production resources

Testing Checklist

• Unit tests for scripts and utilities
• Integration tests for metrics collection
• End-to-end tests for page loads with synthetic users

Common Mistakes to Avoid

• Skipping approvals and bypassing governance
• Context drift across handoffs
• Architecture drift from the defined template

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 Xero Reports and Business Performance Insights.

FAQ

What is this AGENTS.md Template for Web Vitals Optimization?

It provides a copyable, project-scoped operating manual for AI coding agents to optimize Core Web Vitals through multi-agent orchestration and governance.

Who should use this template?

Developers, platform teams, and engineering leaders responsible for web performance and agent-based automation.

How are agent handoffs managed?

Handoffs include context, results, sources, and next actions; planner approval is required before Implementer proceeds; Researcher to Implementer handoffs include data sources and hypotheses.

What about security and production?

Production changes require approval; secrets are stored securely and never logged; use feature flags for rollout.

What happens on failure?

If metrics worsen, revert to the last stable artifact, revalidate, and re-run the plan with adjusted parameters.