AGENTS.md Template for Production System Design Reviews

Overview

Direct answer: This AGENTS.md Template defines a production-grade operating manual for system design reviews using AI coding agents and multi-agent orchestration. It codifies roles, handoffs, tool governance, and human review to ensure consistent, auditable outcomes in production environments.

This AGENTS.md template explains how single agents and multi-agent teams collaborate on complex system design reviews, the decision boundaries, and escalation paths. It provides concrete rules, memory and source-of-truth strategy, and a reusable project-level operating context for engineering teams.

When to Use This AGENTS.md Template

• Before greenfield or major refactor migrations to production systems requiring architectural validation.
• When multiple domains (security, reliability, scalability, data, observability) must be evaluated with consistent criteria.
• To standardize the handoffs between planner, architect, implementer, reviewer, tester, and domain specialist agents.
• To enforce tool governance and approval gates before changes reach production.
• To create auditable traceability for decisions and change requests in a single source of truth.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Production System Design Review Lead (PSDR) – orchestrates the review workflow and ensures alignment with production governance.

Agent roster and responsibilities
- Planner: defines scope, constraints, and success criteria; creates the initial review plan.
- Architect: evaluates high-level and subsystem architecture against reliability, scalability, and security requirements.
- Evaluator: validates design decisions against constraints such as latency budgets, MTTR targets, and capacity planning.
- Validator: verifies compliance with security, data governance, and regulatory requirements; performs risk assessment.
- Scribe: records decisions, rationale, and action items in the design documentation.
- Auditor: performs post-review audits and ensures traceability to source-of-truth artifacts.

Supervisor or orchestrator behavior
- The PSDR orchestrator maintains a single source of truth, triggers agent handoffs at predefined milestones, and enforces gate approvals before accepting changes into the design repository.
- All outputs must be versioned and timestamped; summary outputs are stored for each milestone.

Handoff rules between agents
- Handoff occurs after Planner delivers the scope and plan; Architect takes ownership for technical evaluation; Evaluator and Validator provide risk scoring; Scribe records findings; Auditor signs off.
- Any blocking risk requires a re-run of the relevant checks and re-hand-off with updated evidence.

Context, memory, and source-of-truth rules
- Persisted context must include architecture diagrams, constraints, and referenced artifacts (design docs, CI/CD policies, data contracts).
- Use a single canonical source of truth (design repo, architecture decision records, security policies) to prevent drift.

Tool access and permission rules
- Agents may query repository APIs, CI/CD dashboards, issue trackers, and monitoring systems with read access; write access is strictly controlled and requires supervisor approval.
- Secrets must never be hard-coded; retrieval requires a secure vault and approved workflow.

Architecture rules
- Adhere to established architectural patterns (microservices, event-driven design) and ensure resilience, observability, and scalability requirements are met.

File structure rules
- Place all design artifacts under design-reviews/{project_name}/, with subfolders for plans, diagrams, evidence, and decisions.

Data, API, or integration rules when relevant
- Reference data contracts, API schemas, and integration points; ensure compatibility with production data flows and security boundaries.

Validation rules
- Validate against non-functional requirements (latency, throughput, failure rate, MTTR).
- Confirm security and privacy constraints are satisfied.

Security rules
- Enforce least-privilege access to tools; ensure secrets rotate on schedule; conduct threat modeling and risk scoring.

Testing rules
- Include unit, integration, and contract tests for critical design decisions; verify with staging deployments where possible.

Deployment rules
- Do not deploy changes directly from AGENTS.md; changes must pass review gates and be merged through CI/CD with approvals.

Human review and escalation rules
- Escalate high-severity risks to the CTO or production governance board; all escalations must be documented with rationale.

Failure handling and rollback rules
- Define rollback plans, data migration safety nets, and rollback criteria for each design decision.

Things Agents must not do
- Do not bypass approvals, modify production configs directly, or perform unreconciled changes to source-of-truth artifacts.

Recommended Agent Operating Model

The recommended model assigns defined roles with clear decision boundaries and escalation paths. The PSDR acts as the central planner and arbiter; domain specialists provide expert input on domain-specific risks; the orchestrator ensures handoffs and gate approvals are properly executed. Escalation paths include: auto-escalate to production governance if security or reliability risks exceed thresholds, or request human review if ambiguity remains after iterations.

Recommended Project Structure

design-reviews/
  └─ production-system/
      ├─ 01-plans/            # initial plan, milestones, success criteria
      ├─ 02-architectures/      # diagrams, ADRs, decisions
      ├─ 03-evidence/           # evidence, checks, test results
      ├─ 04-narratives/          # rationale, tradeoffs, risk notes
      ├─ 05-handoffs/            # handoff records and approvals
      └─ 06-audits/              # post-review audits and sign-offs
  └─ templates/               # common templates used across reviews

Agents:
  - planner.md
  - architect.md
  - evaluator.md
  - validator.md
  - scribe.md
  - auditor.md

Orchestrator:
  - psdr-orchestrator/  # coordinates plan, handoffs, and gates

Tools:
  - ci/  # integration with CI/CD for gating
  - repos/  # versioned design artifacts
  - docs/   # supporting documentation

Core Operating Principles

• Maintain a single source of truth for all design decisions.
• Use repeatable, auditable workflows with explicit handoffs.
• Ensure security, reliability, and compliance are baked into every design decision.
• Limit tool execution and access to approved gates and roles.
• Document decisions with evidence and traceability.

Agent Handoff and Collaboration Rules

• Planner hands off to Architect with the plan and constraints.
• Architect hands off to Evaluator and Validator after assessment.
• Validator hands off to Scribe for documentation and to Auditor for sign-off.
• Auditor reviews artifacts and returns for remediation if gaps exist.
• Disputes trigger escalation to PSDR and, if needed, production governance.

Tool Governance and Permission Rules

• Commands to modify design artifacts require supervisor approval.
• API calls to production services require secrets management and approved scopes.
• All edits to design docs are versioned and reviewed.
• Gates enforce security and compliance checks before promotion.

Code Construction Rules

• Follow ADRs and design patterns; avoid ad hoc architecture changes.
• Write maintainable, testable design description artifacts.
• Use deterministic naming and consistent metadata for all design items.

Security and Production Rules

• Apply threat modelling and risk scoring to every design decision.
• Least-privilege access for all tools; rotate credentials regularly.
• Do not expose production credentials in design artifacts.

Testing Checklist

• Unit tests for critical design components and API contracts.
• Integration tests for production-like environments.
• Validation of security, data governance, and privacy controls.
• Regression checks to ensure no design drift.
• Review and sign-off on all gates before deployment.

Common Mistakes to Avoid

• Skipping step-by-step handoffs and bypassing approvals.
• Drift from canonical design artifacts and ADRs.
• Overlooking data governance and security risks.
• Treating AGENTS.md as a casual note rather than an operating manual.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Rental Applications and Document Checks.

FAQ

What is the purpose of this AGENTS.md Template for production system design reviews?

It provides a structured operating manual for AI driven design reviews, enabling multi-agent orchestration, tool governance, and human review in production systems.

Who should use this AGENTS.md Template?

Engineering leaders, platform teams, SREs, architects, and product engineers responsible for production architecture validation and governance.

What are the required agent roles in this workflow?

Planner, Architect, Evaluator, Validator, Scribe, and Auditor, coordinated by the PSDR orchestrator.

What happens if a risk is flagged during review?

The orchestrator logs the risk, halts gate progression, and escalates to human review or production governance as appropriate.

What constitutes a complete handoff?

All evidence, design decisions, rationales, and approvals are transferred to the next role with links to source artifacts and ADRs.