Frontend-Backend QA AGENTS.md Template (AGENTS.md template)

Overview

This AGENTS.md template defines a practical operating manual for frontend-backend QA agent collaboration. It governs both single-agent execution and multi-agent orchestration, providing a clear model for roles, handoffs, tool governance, and human review. The template is designed for AI coding agents working in frontend and backend QA workflows, with explicit rules to prevent drift, ensure traceability, and support reproducible results.

Direct answer style summary: The Frontend-Backend QA AGENTS.md Template prescribes a structured, auditable approach for coordinating QA agents, enabling reliable end-to-end testing, tool governance, and human-in-the-loop review within a single or multi-agent QA flow.

When to Use This AGENTS.md Template

• You need a repeatable, auditable QA workflow involving both frontend and backend checks.
• You require explicit handoff rules and context transfer between agents to avoid context drift.
• You manage sensitive test data, secrets, or production-like environments and need governance rules.
• You want a shared knowledge base and source-of-truth artifacts for QA results and decisions.
• Your team runs CI/CD pipelines that include automated QA steps and human review gates.

Copyable AGENTS.md Template

# AGENTS.md

# Frontend-Backend QA - Agent Collaboration Template

Project role
- This template governs a cross-functional QA workflow with Frontend QA, Backend QA, and an Orchestrator (Planner) to coordinate multi-agent execution.

Agent roster and responsibilities
- Planner (Orchestrator): defines the QA plan, assigns tasks, tracks progress, and triggers handoffs.
- Frontend QA Agent: executes UI tests, accessibility checks, visual diffs, and instrumentation validation.
- Backend QA Agent: executes API contract tests, schema validation, error handling checks, and data integrity tests.
- Data/Mock Data Agent (optional): provisions synthetic data for UI and API tests, ensuring coverage.
- Validation Agent: aggregates results, applies pass criteria, and authorizes handoffs to Review.
- Review/Compliance Agent: conducts final review, logs decisions, and archives artifacts.

Supervisor or orchestrator behavior
- The Planner initializes workflows, assigns tasks, and maintains the living plan.
- All steps are memory-scoped; results, artifacts, and state are captured in a canonical store.
- The Orchestrator enforces permissions and audits all tool usage.

Handoff rules between agents
- Each handoff includes a memory snapshot and a link to the source-of-truth artifacts.
- Frontend QA Agent passes test results, UI screenshots, and accessibility checks to Validation Agent.
- Backend QA Agent passes API responses, contracts, and logs to Validation Agent.
- Validation Agent passes results to Review Agent for final sign-off.

Context, memory, and source-of-truth rules
- All agents read from a central knowledge store; do not duplicate data.
- Artifacts are stored in /artifacts with deterministic naming.
- Source-of-truth is the canonical test results document and API trace/logs.

Tool access and permission rules
- Tools: browser automation, API clients, test runners, and data fixtures.
- Secrets are accessed via the Planner; no hard-coded secrets in agents.
- All tool actions are logged for traceability.

Architecture rules
- Maintain a clear frontend/backend test separation with defined interfaces.
- Tests should be deterministic where possible; seed inputs when needed.

File structure rules
- Use a structured layout: /tests/frontend, /tests/backend, /tests/integration, /artifacts, /logs.

Data, API, or integration rules
- Validate API contracts, data shapes, and boundary conditions.
- Use mock servers for isolated backend tests; avoid hitting production systems in QA.

Validation rules
- Each run must produce a pass/fail outcome with artifacts and logs.
- Validation should be idempotent and reproducible.

Security rules
- Do not expose real secrets in test runs.
- Isolate QA from production data and systems.

Testing rules
- Include unit, integration, and end-to-end checks; document seeds and variants.
- Ensure tests are retry-safe and do not mutate shared state without consent.

Deployment rules
- QA runs can be triggered by CI in a dedicated QA environment and must be approved before promotion.

Human review and escalation rules
- Escalate any critical failure to a human reviewer with a concise run summary.
- Maintain a remediation ticket and link artifacts for audit.

Failure handling and rollback rules
- On failure, revert test data changes, restore artifacts, and roll back to a safe state.
- Ensure partial results are preserved for analysis.

Things Agents must not do
- Do not bypass the orchestrator, mutate shared memory without permission, or perform unsanctioned production changes.
- Do not leak secrets or expose internal endpoints in artifacts.

Recommended Agent Operating Model

The agents operate with clear boundaries and escalation paths. The Planner decides the plan and handoffs; Frontend QA and Backend QA execute tests within their domains; Validation consolidates outcomes; Review provides final sign-off. Handoffs occur only through canonical artifacts stored in the knowledge store, ensuring traceability and reproducibility. In multi-agent orchestration, the Planner enforces schedule, memory integrity, and access control, while each agent adheres to role-specific constraints and reporting requirements.

Recommended Project Structure

frontend-backend-qa-
  ├── tests/
  │   ├── frontend/
  │   │   ├── ui-tests/
  │   │   └── accessibility/
  │   └── backend/
  │       ├── contracts/
  │       ├── api-tests/
  │       └── data-validations/
  ├── orchestrator/
  │   └── planner/
  ├── agents/
  │   ├── frontend-qa/
  │   ├── backend-qa/
  │   └── validation/
  ├── data/
  │   └── fixtures/
  ├── artifacts/
  ├── logs/
  └── docs/

Core Operating Principles

• Single source of truth for all results and decisions.
• Deterministic tests and reproducible runs.
• Explicit, auditable handoffs between agents.
• Strict tool governance and access control.
• Clear escalation and human-in-the-loop when needed.

Agent Handoff and Collaboration Rules

• Planner to Frontend QA: provide test plan, UI test scope, and fixtures.
• Frontend QA to Validation: attach test artifacts, results, and screenshots.
• Backend QA to Validation: attach API traces, responses, and contract checks.
• Validation to Review: present pass/fail status, artifacts, and notes.
• Escalation path: any critical failure goes to human reviewer with run summary.

Tool Governance and Permission Rules

• Only Planner can grant/modify tool permissions; agents operate within scoped toolsets.
• All secrets accessed via the orchestrator; never embedded in agent output.
• All tool interactions are logged with timestamped artifact references.
• Production-like tools require explicit pre-approval and audit trails.

Code Construction Rules

• Write deterministic tests with seeded inputs where applicable.
• Avoid hard-coded data in code; use fixtures and data generators.
• Use canonical file paths for storing artifacts and results.
• Update only the approved documents to reflect changes in the workflow.

Security and Production Rules

• Isolate QA from production systems; use mocks or staging environments.
• Never expose secrets in logs or artifacts.
• Encrypt sensitive data in transit and at rest within QA runs.

Testing Checklist

• Unit tests for individual agents’ logic.
• Integration tests for handoffs and artifact transfer.
• Regression tests ensuring no impact on existing flows.
• End-to-end QA run in a dedicated QA environment.

Common Mistakes to Avoid

• Skipping memory/context transfer during handoffs.
• Bypassing the orchestrator or mutating shared state without consent.
• Ignoring audit logs and artifact provenance.
• Using production-like data without masking or safeguards.

FAQ

What is this AGENTS.md Template used for?

It codifies roles, handoffs, and governance for a frontend-backend QA agent collaboration workflow.

How many agents are involved and what are their roles?

Typical roles include a Planner (Orchestrator), Frontend QA Agent, Backend QA Agent, and a Validation/Reviewer Agent.

How are handoffs coordinated between agents?

Handoffs follow a defined sequence with explicit memory transfer and a link to source-of-truth artifacts.

What tools and permissions are required?

Agents operate within a controlled toolset with scoped permissions; secrets are accessed via the orchestrator and audited.

How are failures handled?

Failures trigger rollback, escalation to human review, and preservation of artifacts for analysis.