AGENTS.md Template for Modular Monolith Architecture Design

Overview

Direct answer: This AGENTS.md template provides a complete operating manual for modular monolith architecture design, enabling AI coding agents to collaborate in a multi-agent orchestration pattern with clear handoffs, governance, and human review points.

The AGENTS.md template governs the agent workflow for modular monoliths, detailing agent roles, decision boundaries, context management, source of truth rules, and how tools and services are accessed in a safe, auditable manner. It supports both single-agent work and multi-agent coordination across modular components.

When to Use This AGENTS.md Template

• Use when designing a modular monolith with a shared kernel and orchestrated module interactions
• When explicit agent handoffs and a central source of truth are required
• When governance, security, and rollback rules must be codified
• When you need repeatable project structure and deployment rules for AI coding agents

Copyable AGENTS.md Template

Copy this block to establish the project-level operating context for modular monolith tasks.

# AGENTS.md
Project: Modular Monolith Architecture Design
Agent roster and responsibilities:
- planner: designs architecture plan for modular monolith, identifies module boundaries, defines interfaces.
- implementer: implements module scaffolding, wiring between modules, and module-level APIs.
- reviewer: reviews architecture conformance, code quality, and security constraints.
- researcher: gathers domain knowledge for module requirements and interaction semantics.
- tester: creates module and integration tests to validate interfaces and constraints.
- operator: coordinates deployment and runtime monitoring.

Supervisor or orchestrator behavior:
- The supervisor coordinates tasks, enforces memory propagation, and validates handoffs against the source of truth.

Handoff rules between agents:
- Planner -> Implementer: provides module specs, interfaces, and shared kernel expectations.
- Implementer -> Reviewer: shares code, tests, and conformance notes.
- Researcher/domain specialist -> Planner: provides domain constraints and decision policies.
- Implementer -> Operator: shares deployment details and runbooks.
- Reviewer -> Planner: captures feedback and issues.

Context, memory, and source-of-truth rules:
- Memory: per-task context stored in a central repository with versioning; sources include API specs and module docs.
- Tools: use a defined toolset with access controls; secrets are retrieved from a vault.

Tool access and permission rules:
- Allowed: code editor, terminal, API calls to permitted services
- No direct access to production databases; use data masking for tests
- Secrets: stored in vault; never printed in logs

Architecture rules:
- Kernel shared by modules; modules own isolated data and behavior; minimal cross-module coupling; events via an internal bus

File structure rules:
- Organize by modules; a conventional layout is modules/{module-name}/api, modules/{module-name}/implementation, modules/{module-name}/tests, infra/, shared/

Data, API, or integration rules:
- Interfaces are versioned; contracts are in a central docs folder; API calls are audited

Validation rules:
- Unit tests for each module; integration tests for module interfaces; contract tests for module APIs

Security rules:
- Role-based access; secrets management; encryption in transit and at rest; audit trails

Testing rules:
- Mock dependencies; deterministic tests; test data management; reproducible test runs

Deployment rules:
- Gradual rollout; canaries; migration validation; rollback plan

Human review and escalation rules:
- Architects as final arbiters for high-risk changes; escalation path documented

Failure handling and rollback rules:
- Circuit breakers; blue-green deployments; rollback scripts; data integrity checks

Things Agents must not do:
- Do not bypass tests; do not access production data; do not modify security policies without approval; do not share secrets

Recommended Agent Operating Model

The agents operate within a clearly defined boundary: Planner defines the architecture, Implementer builds modules, Reviewer enforces quality, and Operator handles deployment and runtime. Domain Specialist and Researcher provide domain-specific guidance and data. Escalations follow a fixed path to architects when risk is identified.

Recommended Project Structure

Workflow-specific directory tree for modular monoliths.

modules/
  user/
    api/
    domain/
  product/
    api/
    domain/
  order/
    api/
    domain/
kernel/
  interfaces/
  events/
infra/
  db/
  messaging/
docs/
tests/

Core Operating Principles

• Single source of truth for architecture decisions
• Clear module boundaries and interfaces
• Defensive coding and contract-first design
• Auditable actions and traceable decisions
• Security-first by default

Agent Handoff and Collaboration Rules

• Planner communicates module specs to Implementer
• Implementer provides code, tests, and interface conformance to Reviewer
• Researcher and Domain Specialist supply domain constraints to Planner
• Reviewer validates changes before deployment
• Operator coordinates deployment and runtime monitoring

Tool Governance and Permission Rules

• Execute commands only within approved tools
• Editors and runners must respect secrets management
• All production access requires approval gates

Code Construction Rules

• Follow contract-first design; version interfaces
• Avoid hard-coded values; use config management
• Write tests for all modules; maintain linters and type checks

Security and Production Rules

• RBAC and least privilege
• Encrypt data in transit and at rest
• Audit logs for all changes

Testing Checklist

• Unit tests for each module
• Integration tests for inter-module calls
• Contract tests and schema validation
• End-to-end tests for critical flows

Common Mistakes to Avoid

• Overlapping responsibilities and blurred module boundaries
• Skipping contract tests
• Unsafe handoffs without source-of-truth alignment
• Escalations ignored until late

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

FAQ

What is the purpose of this AGENTS.md Template for Modular Monolith Architecture Design?

It provides a structured operating manual for coordinating AI coding agents in a modular monolith, including handoffs, governance, and human review points.

Who should use this template?

Engineering leaders, platform teams, and AI practitioners overseeing modular monolith projects.

How are agent handoffs enforced?

Handoffs are governed by explicit rules and a centralized source of truth; planners assign tasks, implementers execute, and reviewers validate.

Where is the source of truth stored for this workflow?

In a central, versioned repository containing module interfaces, data contracts, and decision records with traceable references.

What security practices are required?

RBAC, secrets management, encryption in transit and at rest, audit trails, and controlled production access with approvals.

How do you validate changes in production?

Use canaries, migration checks, monitoring, and rollback scripts to detect drift and recover safely.