AGENTS.md Template: Code Review Agent Workflows

Overview

Direct answer: This AGENTS.md Template provides a complete operating manual for AI coding agents conducting code review, covering single-agent and multi-agent orchestration, with explicit roles, memory, tool access, governance, and escalation rules.

When to Use This AGENTS.md Template

• You need a formal operating context for automated code reviews integrated with PR processes.
• You are coordinating multiple agents (planner, implementer, reviewer, tester, researcher) on a codebase.
• You require strict tool governance, secrets handling, and production safety gates for review outcomes.
• You want clear handoff rules, escalation paths, and a single source of truth for review decisions.

Copyable AGENTS.md Template

Copy this block into AGENTS.md to anchor the project’s agent workflow and governance. It is the single source of truth for code review agent behavior.

# AGENTS.md

# Project: Code Review Agent Workflow

## 1) Agent Roles
- Planner: defines review scope, gathers changes, identifies impacted modules, and sequences tasks.
- Implementer: applies changes in the codebase, updates documentation, and records rationale.
- Reviewer: performs static analysis, security checks, linting, and semantic review.
- Tester: runs unit tests, integration tests, and CI checks; validates PR results.
- Researcher: fetches guidelines, standards, and references; updates policy notes.
- Domain Specialist (optional): provides context for domain-specific rules when needed.

## 2) Supervisor / Orchestrator Behavior
- The Orchestrator enforces the plan, tracks memory, and gates handoffs between agents.
- It logs decisions with PR context, stores outputs in a memory store, and triggers escalation if quality gates fail.
- All artifacts are versioned and timestamped; decisions are auditable.

## 3) Handoff Rules
- Planner -> Implementer: pass scope, diffs, and rationale.
- Implementer -> Reviewer: pass changed files, tests, and notes.
- Reviewer -> Orchestrator: pass verdict and remediation plan.
- Orchestrator -> Human Review: if quality gates fail or security flags trigger escalation.

## 4) Context, Memory, and Source of Truth
- Context: PR ID, repository, branch, commit SHAs, and CI results.
- Memory: a structured store keyed by PR, preserving history and decisions.
- Source of Truth: the PR diff, commit messages, test results, and CI reports.

## 5) Tool Access and Permission Rules
- Tools: Git, CI system, code search, lints, security scanners, artifact stores.
- Access: scoped tokens with least privilege; secrets are never hard-coded.
- Production actions require explicit human approval gates.

## 6) Architecture Rules
- Single source of truth for review outputs; outputs are immutable once approved.
- Agents must not mutate production code without review.
- All changes must flow through the code review pipeline and be auditable.

## 7) File Structure Rules
- Do not place review outputs outside the designated review directory.
- Use conventional folders: reviews/, diffs/, docs/, tests/ to store artifacts.

## 8) Data, API, or Integration Rules
- Data sources: PR metadata, repository commits, test results, lint outputs.
- APIs: GitHub/GitLab REST APIs for PR data; CI APIs for test status.
- Integrations must honor rate limits and pagination.

## 9) Validation Rules
- Each agent must emit a structured report with inputs, actions, and outputs.
- All outputs must pass syntax and policy checks before handoff.
- Memory must be updated with the latest decision and justification.

## 10) Security Rules
- Do not expose secrets in logs or artifacts.
- Rotate tokens periodically; use environment-scoped credentials.
- Production-related actions require human approval gates.

## 11) Testing Rules
- Unit tests for individual agent decisions.
- Integration tests that simulate full PR review cycles.
- End-to-end tests in a staging environment with real PR data.

## 12) Deployment Rules
- Deploy changes to the review engine via a controlled pipeline.
- Rollback plan must exist for failed reviews or policy violations.

## 13) Human Review & Escalation Rules
- Escalate to a human reviewer if a critical security flag is raised or if the reviewer cannot resolve a conflict.
- Provide a clear remediation plan to humans and log the decision.

## 14) Failure Handling & Rollback Rules
- If an agent misapplies a fix, revert changes in the PR branch and re-run tests.
- Notify the team and create a follow-up task for remediation.

## 15) Things Agents Must Not Do
- Do not bypass review gates or merge without approval.
- Do not introduce data leakage in logs or artifacts.
- Do not perform non-deterministic actions without traceable justification.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths for code review agents. The Planner designs the review scope, the Implementer applies changes, the Reviewer validates quality, and the Orchestrator enforces governance and handles escalation. Domain Specialists provide context when domain-specific rules apply. Escalation paths to human review are clearly defined for security or policy violations.

Recommended Project Structure

ai-review-workflow/
  agents/
    planner/
    implementer/
    reviewer/
    tester/
    researcher/
  orchestrator/
  memory/
  tools/
  data/
  docs/
  tests/
  configs/

Core Operating Principles

• Always maintain a single source of truth for PR reviews.
• Use explicit, auditable handoffs between agents.
• Enforce tool governance and never expose secrets in logs.
• Require human review for unsafe or high-risk changes.
• Keep outputs deterministic and reproducible across runs.

Agent Handoff and Collaboration Rules

• Planner communicates scope and diffs to Implementer in a structured summary.
• Implementer reports changes and rationale to Reviewer with a link to diffs.
• Reviewer validates outputs and sends verdict to Orchestrator with remediation steps.
• Orchestrator logs all handoffs and triggers escalation if thresholds are exceeded.
• Researchers and Domain Specialists intervene only when guidance is required or policies update.

Tool Governance and Permission Rules

• Use scoped tokens for Git, CI, and code search. Do not reuse tokens across tools.
• Secrets must be retrieved from a secure vault; never hard-coded.
• All code changes must pass lint, tests, and security checks before any merge.
• Handoffs must include a rationale and evidence from tooling outputs.

Code Construction Rules

• Code changes must be minimal, localized, and well-documented.
• Follow project-specific style guides and lint rules; changes must be reviewable.
• Avoid duplicating logic; prefer reusable helper functions with tests.

Security and Production Rules

• Protect production credentials; use environment-scoped secrets.
• Enforce approval gates for any production-ready change.
• Audit trails must capture who, what, when, and why for every action.

Testing Checklist

• Unit tests for each agent decision path.
• Integration tests for PR review flow.
• End-to-end tests with synthetic PR data in a staging repo.

Common Mistakes to Avoid

• Skipping validation before handoffs.
• Overly complex handoffs that obscure traceability.
• Hard-coding secrets or bypassing approvals.

FAQ

What is this AGENTS.md Template for Code Review?

This template defines how AI coding agents conduct code review, including roles, handoffs, memory, tool governance, and escalation rules.

Who owns memory and source-of-truth in this workflow?

The memory store is keyed by PR context and linked to the repository, CI results, and artifacts; the source of truth is the PR diff, commit messages, and test results.

How are agent handoffs handled in multi-agent scenarios?

Handoffs are explicit: planner to implementer, implementer to reviewer, reviewer to orchestrator, with an auditable log and remediation plan when needed.

What are the security considerations?

Secrets rotate, tools use scoped tokens, and production actions require human approval gates; avoid leaking credentials in logs.

How do I validate outputs from agents?

Require structured outputs, static checks, unit tests, linting, and CI checks; ensure traceability to code changes.