AGENTS.md Template for Monolith to Microservices Migration

Overview

The AGENTS.md Template for Monolith to Microservices Migration defines a repeatable, AI aided workflow to break a monolith into independently deployable services using AI coding agents. It governs both single agent execution and multi-agent orchestration, establishing a clear operating context, boundaries, and handoffs across planner, implementer, reviewer, tester, researcher, and domain specialist agents.

Direct answer: this page provides a complete AGENTS.md Template that you can copy into your project as a living operating manual to coordinate agent work, governance, and handoffs for migration at scale.

When to Use This AGENTS.md Template

• Planning a phased monolith to microservices migration with explicit service boundaries
• Coordinating multiple AI agents across design, implementation, validation, and deployment
• Enforcing tool governance, security, and production controls during migration
• Capturing a project level operating context that teams can reproduce for future migrations

Copyable AGENTS.md Template

# AGENTS.md

Project role: Migration Lead coordinating AI coding agents to perform a monolith to microservices migration with multi agent orchestration.

Agent roster and responsibilities:
- Planner Agent: designs migration strategy, defines service boundaries, creates milestone plan.
- Implementer Agent: builds each microservice according to contracts, writes APIs, and integrates with gateways.
- Reviewer Agent: performs design review, code quality checks, and architectural conformance.
- Tester Agent: runs contract tests, integration tests, performance tests, and end-to-end validation.
- Researcher Agent: gathers domain knowledge, data mapping, and migration risk assessment.
- Domain Specialist Agent: handles domain constraints (security, payments, data consistency).

Supervisor or orchestrator behavior:
- The Orchestrator coordinates task assignments, sequences handoffs, enforces governance gates, records decisions, and maintains memory of context and decisions.
- It ensures agents stay within their boundaries and escalate when blockers arise.

Handoff rules between agents:
- Planner -> Implementer: share service scope, contracts, migration milestones, and constraints.
- Implementer -> Reviewer: share implemented interfaces, contracts, and code landmarks for review.
- Reviewer -> Implementer: provide actionable feedback and required changes.
- Implementer -> Tester: hand off build artifacts, test results, and risk notes.
- Tester -> Planner: summarize test results and remediation plan.
- Researcher/Domain Specialist -> Planner: supply domain insights and risk mitigations.

Context, memory, and source-of-truth rules:
- All decisions are stored in the central knowledge base and linked to design docs, contracts, and tests.
- Source of truth is the repository and contract definitions stored in a centralized docs folder.
- Agents must reference the latest design docs and API contracts before taking action.

Tool access and permission rules:
- Agents may read all docs and contracts; write access to service code and deployment configs is restricted to Implementer and CI gates.
- Secrets and production credentials reside in a vault; access controlled by role and approvals.

Architecture rules:
- Each microservice has a single responsibility; APIs are contract-first with OpenAPI or gRPC as applicable.
- Shared libraries reside in a dedicated shared area; avoid cross service tight coupling.
- Service registry and versioning are enforced; backward compatible contracts are required for migrations.

File structure rules:
- services/{service-name}/
  - src/
  - tests/
  - contracts/
  - README.md
- gateway/
- shared/
- infra/
- docs/
- scripts/

Data, API, or integration rules:
- Use OpenAPI contracts for RESTful interfaces, and document event schemas for messaging.
- Data migrations are versioned and reversible; maintain data mapping in the docs folder.

Validation rules:
- Contract tests, integration tests, and end-to-end tests must pass before progressing to production.
- All changes require review and approval gates.

Security rules:
- Secrets must never be embedded in code; use a vault for all credentials.
- Production changes require security review, threat modeling, and access controls.

Testing rules:
- CI must run unit, integration, and contract tests; performance tests where applicable.

Deployment rules:
- Prefer blue/green or canary deployment for microservices; roll back on failure.

Human review and escalation rules:
- Any deviation from architecture, or any failed gating test, triggers escalation to the Migration Lead and Security Lead.

Failure handling and rollback rules:
- If migration step fails critically, revert to the previous monolith state and restore data consistency.

Things Agents must not do:
- Do not bypass tests, skip reviews, or deploy directly to production without gates.
- Do not modify contracts without approval; avoid context drift.

Recommended Agent Operating Model

Roles and decision boundaries: Planner defines the migration strategy and boundaries; Implementer executes against contracts; Reviewer validates architecture and quality; Tester validates through tests; Researcher and Domain Specialist supply domain knowledge and constraints. Escalation paths go to the Migration Lead and a Governance Board when blockers emerge or policy violations occur.

Recommended Project Structure

monolith-to-microservices/
├── services/
│   ├── authentication-service/
│   │   ├── src/
│   │   ├── tests/
│   │   └── contracts/
│   ├── catalog-service/
│   │   ├── src/
│   │   ├── tests/
│   │   └── contracts/
│   └── order-service/
│       ├── src/
│       ├── tests/
│       └── contracts/
├── gateway/
├── shared/
├── infra/
│   ├── k8s/
│   └── ci/
├── scripts/
└── docs/

Core Operating Principles

• Operate with contract first principles and clear service boundaries.
• Favor incremental migration with reversible steps and observable metrics.
• Maintain strong separation of concerns between planning, implementation, and validation.
• Preserve data integrity and security throughout the migration.
• Document decisions and keep the knowledge base up to date.

Agent Handoff and Collaboration Rules

Planner coordinates with Implementer for scope transfer; Implementer hands off to Reviewer for architecture validation; Reviewer ensures changes meet quality gates before Tester runs tests; Researcher and Domain Specialist provide domain knowledge to all agents as needed.

Tool Governance and Permission Rules

Access control is role based; production changes require approvals; secrets are vaulted; all tool usage is auditable; external service calls follow contract definitions and governance gates.

Code Construction Rules

Follow contract first design, implement per service boundaries, write tests for each contract, and avoid over coupling. Use semantic versioning and maintainable code style. Do not bypass tests or review gates.

Security and Production Rules

Encrypt data in transit and at rest; use vault for credentials; enforce least privilege; production changes require security review; monitor for anomalous activity.

Testing Checklist

• Unit tests for each service and module
• Contract tests for API surfaces
• Integration tests across service boundaries
• End-to-end tests with migration scenarios
• Performance and resilience tests
• Security and compliance tests

Common Mistakes to Avoid

• Skipping contract-first design and assuming implementation details are fine
• Uncontrolled coupling between services
• Undocumented data migrations and edge cases
• Skipping governance gates or security reviews

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template?

It defines a working context for AI coding agents to coordinate a monolith to microservices migration, including roles, handoffs, and governance.

How does multi-agent orchestration work in this template?

A Planner designs the migration plan, Implementers build services, Reviewers validate, Testers verify, Researchers provide domain knowledge, and Domain Specialists resolve constraints. An Orchestrator coordinates handoffs.

What are the handoff rules between planner and implementer?

Planner passes service scope, contracts, and migration milestones to Implementer. Implementer returns progress, artifacts, and blockers to Planner.

How is security and secrets managed during migration?

Secrets are stored in a vault, access is role based, production access requires approval gates, and all changes pass through security review.

How do we validate the new microservices architecture and rollback if needed?

Use contract tests, integration tests, and end-to-end tests; have a rollback plan to revert to monolith if critical failures occur; blue/green or canary deployments.