Microservices vs Monolith Decision Prompt

Use this prompt when an engineering team must make a binding, documented decision between a monolithic architecture and a microservices-based approach for a new system or a migration. The prompt is designed for staff engineers and technical architects who need a structured Architecture Decision Record (ADR) that future maintainers can search, understand, and challenge. It forces explicit consideration of team topology, deployment complexity, data consistency, operational maturity, and migration path—factors that generic pros-and-cons lists ignore. The output is not a recommendation in a vacuum; it is a decision-forcing document that requires organizational context as input and refuses to produce an architecture recommendation without it.

This prompt is not a generic comparison generator. Do not use it when you need a quick blog-post-style summary of microservices versus monoliths, when the decision has already been made and you only need to backfill documentation, or when the team lacks the authority to act on the outcome. It is also inappropriate for purely academic exercises where no real system will be built. The prompt explicitly checks for missing context—such as team size, regulatory constraints, or data consistency requirements—and will flag gaps rather than fabricate assumptions. If your goal is a lightweight technology comparison without organizational weight, use the sibling Technical Comparison and Difference Prompts instead.

Before running this prompt, gather concrete inputs: current team structure and Conway's Law implications, expected deployment frequency, data consistency and latency requirements, operational tooling maturity, and any hard constraints from compliance or existing platform standards. The prompt will use these to produce an ADR with sections for context, decision, considered alternatives, trade-offs, and consequences. After generation, treat the output as a draft for human review. The ADR should be challenged by peers, validated against your architecture principles using the sibling ADR Validation Against Architecture Principles Prompt, and stored in a version-controlled ADR repository. If the prompt flags missing context, resolve those gaps before accepting the output—an ADR built on incomplete context is worse than no ADR at all.

The prompt below is designed to be pasted directly into your AI harness. It forces the model to act as a staff engineer producing a decision record, not a generic comparison article. Every section of the output—context, decision, considered alternatives, trade-offs, consequences, and migration path—is explicitly requested. The prompt includes placeholders for your specific organizational context, because a useful ADR must reflect your team's topology, operational maturity, and business constraints, not generic best-practice lists.

markdownCopy
You are a staff engineer documenting an architecture decision for your organization's ADR repository. Your task is to produce a complete Architecture Decision Record in Markdown format comparing a microservices approach against a monolithic approach for [SYSTEM_NAME].

## Required Inputs
- System description: [SYSTEM_DESCRIPTION]
- Current architecture (if any): [CURRENT_ARCHITECTURE]
- Team topology: [TEAM_TOPOLOGY]
- Operational maturity level: [OPERATIONAL_MATURITY]
- Business constraints: [BUSINESS_CONSTRAINTS]
- Expected scale and growth trajectory: [SCALE_EXPECTATIONS]
- Regulatory or compliance requirements: [COMPLIANCE_REQUIREMENTS]
- Timeline pressure: [TIMELINE_PRESSURE]

## Output Schema
Produce a single Markdown document with the following sections. Do not omit any section.

### ADR-[NNNN]: [TITLE]
**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Date:** [YYYY-MM-DD]
**Deciders:** [DECIDER_LIST]

### Context
Describe the forces at play: technical, business, organizational, and operational. Include the problem we are solving and why this decision is needed now. Reference specific constraints from the inputs above.

### Decision
State the chosen approach clearly: microservices, monolith, modular monolith, or a phased hybrid. Be specific about boundaries if microservices are chosen, or module boundaries if a monolith is chosen. Do not hedge.

### Considered Alternatives
For each alternative not chosen, provide:
- A one-sentence summary of the alternative
- Why it was considered viable
- Why it was rejected, tied to specific constraints from the Context section

Include at minimum: the opposite of the chosen decision, and at least one hybrid or intermediate option.

### Trade-Offs
A table with columns: Trade-Off | Chosen Approach | Rejected Approach(es) | Mitigation
Cover at minimum: deployment complexity, data consistency, team autonomy, operational overhead, development velocity, debugging complexity, cost, and scaling characteristics.

### Consequences
#### Positive
List specific, measurable positive outcomes expected from this decision.

#### Negative
List specific risks, costs, or limitations introduced by this decision.

#### Mitigations
For each negative consequence, describe the concrete mitigation step.

### Migration Path (if applicable)
If moving from [CURRENT_ARCHITECTURE] to the chosen approach, describe:
- Phases with success criteria for each phase
- Strangler fig pattern or equivalent incremental approach
- Rollback triggers and rollback plan
- Affected teams and systems

### References
- Link to related ADRs, design docs, incident postmortems, or external sources

## Constraints
- Use the organization's actual team topology and operational maturity; do not assume a FAANG environment unless specified.
- If operational maturity is low, favor simplicity and explicitly call out the operational investment required for microservices.
- If regulatory requirements exist, address data locality, auditability, and deployment boundary implications.
- Do not produce a generic "microservices are good for scale, monoliths are good for startups" comparison. This must be a specific decision for [SYSTEM_NAME] given the inputs.
- If the decision is a phased approach, define clear gates between phases.
- Every claim about scaling, cost, or velocity must be traceable to an input constraint.

To adapt this prompt for your own use, replace every square-bracket placeholder with real values before execution. The most critical placeholders are [TEAM_TOPOLOGY] and [OPERATIONAL_MATURITY], because they determine whether microservices are a realistic option or an operational risk. If your team is three engineers with no container orchestration experience, the prompt will surface that tension in the Trade-Offs and Consequences sections. If you omit these placeholders, the model will default to generic advice that won't survive a peer review. After generation, validate that every claim in the Consequences section is traceable to an input constraint—this is your primary eval check before committing the ADR.

This prompt is designed to be called programmatically from a documentation pipeline, not as a one-off chat interaction. The typical integration point is a CI job triggered on PR merge to an architecture decision record (ADR) repository, a CLI command like adr propose --type deployment-strategy, or an internal architecture review bot that comments on design docs. The harness must supply structured context—team size, operational maturity, data consistency requirements, and current system boundaries—rather than relying on the model to infer these from a free-text brain dump.

Wrap the prompt in a function that accepts a typed input object matching the placeholders: [TEAM_CONTEXT] (size, distribution, expertise), [SYSTEM_BOUNDARIES] (current components and their responsibilities), [CONSTRAINTS] (latency budgets, data consistency needs, regulatory requirements), [OPERATIONAL_MATURITY] (CI/CD state, observability, incident response), and [MIGRATION_PATH] (current state and acceptable transition windows). Validate all required fields before calling the model. On the output side, parse the response against a schema that requires decision, considered_alternatives (array with at least two entries), trade_offs (object mapping quality attributes to impact), consequences, and migration_steps. If the model returns malformed JSON or omits a required section, retry once with a repair prompt that includes the parse error and the original schema. After two failures, surface the raw output for human review rather than silently accepting a partial ADR.

Model choice matters here. Use a model with strong structured output support and a large context window—this prompt works best with GPT-4o, Claude 3.5 Sonnet, or equivalent. Enable structured output mode (JSON mode or tool calling with a strict schema) rather than relying on free-text parsing. Log every invocation with the input hash, model version, output schema compliance status, and whether human review was required. For high-stakes decisions—anything affecting production data consistency, security boundaries, or compliance posture—always require a human approver to sign off before the ADR is merged. The harness should block automated merge until an approved reviewer has acknowledged the record. Do not treat this prompt as a decision-maker; treat it as a structured first draft that accelerates human architectural judgment.