AGENTS.md Template for Test Generation and QA Automation Agents

Overview

AGENTS.md template for test generation and QA automation agents defines how to coordinate AI coding agents to generate tests and automate QA tasks. It governs the test generation workflow and multi-agent orchestration for both single-agent and multi-agent deployments.

Direct answer: This AGENTS.md Template provides a formal operating manual to coordinate test generation and QA automation with a roster of agents, handoff rules, tool governance, and security guidelines.

When to Use This AGENTS.md Template

• When you need automated test generation for modern codebases using AI coding agents.
• When you require QA automation coordination across multiple agents, runtimes, and CI pipelines.
• When you want a single source of truth for responsibilities, handoffs, and validation criteria.
• When you need repeatable project-level operating context to onboard new agents quickly.

Copyable AGENTS.md Template

# AGENTS.md
Project role: QA Automation Architect
Agent roster:
- Planner Agent: defines tests from requirements and selects target test types
- TestCaseGenerator Agent: creates explicit test cases from the plan
- TestExecutor Agent: runs test suites in CI and reports results
- QA Reviewer Agent: validates quality, coverage, and traceability
- Orchestrator: coordinates plan generation, handoffs, and progress

Handoff rules:
- Planner -> TestCaseGenerator: share plan details, acceptance criteria, and test types
- TestCaseGenerator -> TestExecutor: share generated test cases and environment requirements
- TestExecutor -> QA Reviewer: share execution results and coverage metrics
- QA Reviewer -> Orchestrator: escalate issues and request rework if needed

Context, memory, and source-of-truth:
- Use a single source of truth: repository of tests, requirements, and CI results
- Maintain memory of past decisions in a shared memory store scoped to the project
- All outputs must reference source artifacts (requirements, design docs, issue trackers)

Tool access and permission rules:
- Access to repository, CI/CD, test frameworks, and artifact storage
- Secrets stored in a vault and rotated per policy
- No direct access to production systems from agents; use approved gateways

Architecture rules:
- Agent roles are composable and stateless; state is persisted via orchestrator memory
- Every test artifact must be traceable to a requirement and a plan
- Use a shared orchestrator to avoid deadlocks and race conditions

File structure rules:
- agents/planner/
- agents/generator/
- agents/executor/
- agents/reviewer/
- orchestrator/
- tests/
- data/

Data, API, or integration rules:
- Use explicit data mocks in generator tests when real data is unavailable
- API calls must go through a controlled gateway with audit logging

Validation rules:
- All generated tests must pass CI checks and map to acceptance criteria
- Coverage metrics must be produced and stored with results

Security rules:
- Do not leak secrets in logs or artifacts
- Enforce least-privilege access for all agents

Testing rules:
- Include unit tests for the generator, integration tests for orchestration, and end-to-end QA

Deployment rules:
- Deploy changes to the test harness via approved pipelines; avoid manual edits in production branches

Human review and escalation rules:
- All non-deterministic or high-risk test changes require human review
- Escalate to a QA engineer if results are inconclusive or flaky

Failure handling and rollback rules:
- If a run fails, revert to the last known-good test set and re-run after hotfix
- Maintain an audit trail of rollbacks

Things Agents must not do:
- Do not bypass validation checks
- Do not modify production data without approval
- Do not perform unsupervised production changes

Recommended Agent Operating Model

Roles and decision boundaries specific to test generation and QA automation: Planner defines what to test; Generator creates tests; Executor runs tests; Reviewer validates results; Orchestrator maintains schedule and handles handoffs. Escalations go to a designated human QA engineer or engineering manager when criteria are not met.

Recommended Project Structure

project-root/
├── agents/
│   ├── planner/
│   │   └── plan.md
│   ├── generator/
│   │   ├── generate_tests.py
│   │   └── prompts/
│   ├── executor/
│   │   └── run_tests.sh
│   ├── reviewer/
│   │   └── review_tests.md
│   └── data-ops/
│       └── data/
├── orchestrator/
│   └── orchestrator.py
├── tests/
│   └── generated/
├── data/
│   └── fixtures/
├── configs/
│   └── ci.yaml
└── docs/

Core Operating Principles

• Single source of truth for requirements, plans, and test artifacts
• Deterministic handoffs with explicit criteria and acceptance criteria
• Clear ownership and escalation paths for all agents
• Auditability and traceability of every test artifact to its origin

Agent Handoff and Collaboration Rules

• Planner communicates plan and acceptance criteria to Generator
• Generator returns concrete test cases and test steps to Executor
• Executor reports results and metrics to Reviewer and Orchestrator
• Reviewer signs off on readiness or requests rework
• Orchestrator coordinates all handoffs and handles failures

Tool Governance and Permission Rules

• Commands must be executed by approved agents via orchestrator gates
• Edits to test artifacts require review and CI validation
• All secrets are stored securely; no printed secrets
• Production systems are never touched by test-generation agents
• External services use scoped credentials and audit logs
• All actions require an explicit approval gate for non-deterministic changes

Code Construction Rules

• Tests must be deterministic where possible and reproducible
• Use modular test generation patterns and reusable helpers
• All generated tests include metadata linking to requirements
• Avoid duplicating test logic across agents; reuse shared utilities
• Documentation and inline comments must be present

Security and Production Rules

• Limit data exposure in tests; redact sensitive fields
• Enforce secrets-management and rotation policies
• Use infrastructure-as-code for test harness deployments
• Isolate test environments from production resources

Testing Checklist

• Unit tests for generator and planner components
• Integration tests for orchestrator and API calls
• End-to-end tests that validate handoffs and results propagation
• CI pipeline runs with artifact preservation

Common Mistakes to Avoid

• Skipping validation on generated tests
• Overlapping responsibilities among agents
• Unclear handoff criteria or missing acceptance tests
• Bypassing human review for critical changes

FAQ

What is this AGENTS.md Template for?

It defines the operating context for test generation and QA automation agents, including roles, handoffs, and governance in a reproducible template.

Can this template be used for single-agent workflows?

Yes. The template supports single-agent execution with a simplified planner and executor, while preserving orchestration patterns for multi-agent setups.

How are agent handoffs managed?

Handoffs follow explicit rules and criteria maintained by the orchestrator, with artifacts and acceptance criteria passed between agents.

What are the security considerations?

Secrets are stored in a vault, access is restricted by role, and logs are redacted to avoid leaking sensitive data.

How do I validate generated tests?

Validation includes CI checks, test-to-requirement traceability, and coverage metrics before deployment to any environment.