AGENTS.md Template for Microservices Architecture Reviews

Overview

Direct answer: This AGENTS.md Template governs a microservices architecture review workflow using AI coding agents, enabling coordinated multi-agent orchestration, tool governance, and human review. It provides a single source of truth and operating context for both single-agent and multi-agent execution across planner, architect, implementer, reviewer, researcher, and domain specialist roles.

This template documents the agent roles, decision boundaries, escalation paths, and acceptance criteria needed to audit microservices, ensure secure interactions with services, and maintain architectural integrity during changes.

When to Use This AGENTS.md Template

During a formal microservices architecture review to assess reliability, scalability, data consistency, and security across services.
When coordinating a multi-agent workflow that includes planning, architectural review, implementation, testing, and validation.
When establishing tool governance, secrets handling, and an auditable decision history for architecture decisions.
When you need a copyable, project-level operating context that teams can share and reproduce.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Microservices Architecture Review Lead
Agent roster:
- Planner: defines review scope, milestones, and handoff checkpoints.
- Architect: evaluates service boundaries, data flows, contracts, and tech choices.
- Implementer: proposes changes to services and infrastructure in scope.
- Tester: validates changes through tests and canary deployments.
- Researcher: gathers telemetry, metrics, and external references.
- Domain Specialist: provides cross-domain constraints and governance guidance.

Supervisor / Orchestrator:
- Oversees multi-agent coordination, enforces handoffs, and ensures context is preserved across agents.
- Validates outputs before progression to the next stage.

Handoff rules:
- Planner ➜ Architect when scope and architecture decisions require redesign.
- Architect ➜ Implementer when concrete changes are ready for implementation.
- Implementer ➜ Tester when changes are available for validation.
- Tester ➜ Reviewer when validation passes or when issues require rework.
- Researcher ➜ any agent when new data is discovered; update shared context.

Context, memory, and source-of-truth rules:
- Maintain a single source of truth for decisions, inputs, and outputs.
- All outputs must reference source data and telemetry.
- History is versioned and traceable to commits or PRs.

Tool access and permission rules:
- Use only approved tools with scoped permissions.
- Secrets must never be exposed in logs or messages.
- Production system access requires supervisor approval and audit trail.

Architecture rules:
- Respect service boundaries and domain-driven design constraints.
- Minimize cross-service coupling; favor explicit contracts.
- Prefer backward-compatible changes and feature flags for risk control.

File structure rules:
- Keep architecture decisions and rationale in docs/architecture/
- Place service-specific changes under services/ & infra/ as applicable.

Data, API, or integration rules:
- Always include API contracts, schemas, and versioning.
- Ensure data migrations are rolled out gradually with backward compatibility.

Validation rules:
- Tests cover behavioral and contract validity.
- Metrics and tracing validate performance and reliability goals.

Security rules:
- Enforce least privilege, secret management, and robust authentication/authorization.
- Audit all changes with attribution to the responsible agent.

Testing rules:
- Include unit, integration, and end-to-end tests; require canary validation for production changes.

Deployment rules:
- Fetch approved changes from the orchestrator; perform staged rollouts and rollbacks if failures occur.

Human review and escalation rules:
- All critical decisions require human oversight at gates defined in the planner.
- Escalate to a domain lead if non-deterministic risk arises.

Failure handling and rollback rules:
- Abort on critical failures; rollback using versioned artifacts and feature flags.

Things Agents must not do:
- Do not bypass approval gates.
- Do not access production data without authorization and masking.
- Do not create irreversible changes without a rollback plan.

Recommended Agent Operating Model

The operator acts as a governance layer with clearly defined roles and decision boundaries. Planner defines scope and milestones; Architect evaluates service boundaries and data flows; Implementer proposes changes; Tester validates changes; Researcher provides telemetry; Domain Specialist enforces governance constraints. Escalation paths route issues to the supervisor or domain lead. Decisions are recorded in a shared memory store and versioned artifacts are produced at every handoff.

Recommended Project Structure

microservices-review/
├── docs/
│   └── architecture/
│       └── decisions.md
├── services/
│   ├── order-service/
│   │   ├── src/
│   │   └── Dockerfile
│   ├── payment-service/
│   │   ├── src/
│   │   └── Dockerfile
│   └── inventory-service/
│       ├── src/
│       └── Dockerfile
├── infra/
│   ├── k8s/
│   │   └── manifests/
│   └── shared/
└── reviews/
    ├── planner/
    ├── architect/
    ├── implementer/
    ├── tester/
    └── researcher/

Core Operating Principles

Single source of truth for all decisions and outputs.
Explicit, auditable handoffs with preserved context and references.
Least privilege and secret management for all tools and services.
Early detection of architectural drift and proactive governance.
Versioned artifacts and reproducible workflows for every review cycle.

Agent Handoff and Collaboration Rules

Planner defines scope and triggers handoffs when architectural decisions require redesign.
Architect produces design changes and passes artifacts to Implementer with clear acceptance criteria.
Implementer implements changes and hands off to Tester with validation metrics.
Tester validates changes; upon success, hands to Reviewer; upon failure, returns to Planner or Architect for adjustments.
Researcher updates context when new telemetry or external references are found and shares with all roles.
Domain Specialist ensures governance constraints are respected in every step.

Tool Governance and Permission Rules

All tool calls are scoped and auditable; no hard-coded credentials in code or logs.
Secrets must be retrieved from a secure vault and never echoed in outputs.
Production tooling changes require supervisor approval and an audit trail.
Access to service internals is restricted to roles with explicit permission.
External API calls are gated by policies and rate limits; failures trigger safe fallbacks.

Code Construction Rules

Code changes must be accompanied by architecture rationale and tests.
Backwards compatibility and feature flags are required for public APIs when changing contracts.
Documentation and diagrams must reflect current architecture decisions.
All changes must be traceable to the AGENTS.md template outputs and handoffs.

Security and Production Rules

Enforce least privilege; use role-based access control for all services.
Mask PII/PHI in logs and telemetry; store secrets securely.
Audit all changes; enable traceability from planner to production.
Canary deployments with automatic rollback on failure.

Testing Checklist

Unit tests for all service components; contract tests for API boundaries.
Integration tests verifying inter-service contracts and data flow.
End-to-end tests with realistic workloads and canary validation.
Performance and resilience tests to ensure SLAs are met.
Security tests including secret handling and access controls.

Common Mistakes to Avoid

Skipping governance and proceeding with production changes without approval.
Overly coupled services that violate bounded contexts.
Insufficient test coverage across contract boundaries.
Unclear handoffs leading to ambiguous responsibility and drift.
Exposing secrets in logs or in code repositories.

FAQ

What is this AGENTS.md Template for Microservices Architecture Reviews?

It provides a project-level operating context for AI coding agents to audit, reason about, and coordinate microservices architecture reviews using a reproducible, multi-agent workflow.

Who should use this AGENTS.md Template?

Developers, platform teams, engineering leaders, and architecture reviewers who run microservices evaluations and multi-agent workflows.

How does multi-agent orchestration work in this workflow?

A Planner defines scope and milestones; an Architect reviews structure and contracts; an Implementer proposes changes; a Tester validates changes; a Researcher gathers telemetry; a Domain Specialist enforces governance. Handoffs preserve context and outputs are versioned.

What are the handoff rules between planner, implementer, reviewer, tester, researcher, and domain specialist?

Handoffs occur at defined checkpoints: Planner ➜ Architect for design decisions, Architect ➜ Implementer for implementation, Implementer ➜ Tester for validation, Tester ➜ Reviewer for approval, Researcher keeps context updated and shares findings; Domain Specialist ensures governance constraints are met at each stage.

What security and governance rules apply?

Least privilege access, secret management, auditable decision history, and mandatory human approval for production changes. All tool usage and data handling must respect security policies.

Target User

Use Cases