Service Boundary Decision Record Template Prompt

This prompt is for architects and engineering leads who need to document a service boundary decision with full context, options considered, trade-offs, and rationale. Use it when a team is deciding where to draw a line between two services, extracting a module from a monolith, or merging over-decomposed services. The output is a structured ADR that can be committed to a repository, reviewed by peers, and referenced during implementation and future reversals. The prompt assumes the architect has already done the analysis and needs to produce a consistent, reviewable document—it does not perform the analysis itself.

Do not use this prompt for lightweight design notes, real-time coding decisions, or decisions that do not require a formal record. It is overkill for a quick Slack thread or a whiteboard sketch. It is also the wrong tool when the team has not yet gathered evidence about coupling, data ownership, transaction boundaries, or team topology—this prompt documents a decision, it does not discover one. For discovery work, use the Service Boundary Candidate Identification Prompt or the Bounded Context Discovery Prompt first, then feed their outputs into this template.

The ideal user has completed technical analysis and needs to produce a decision record that survives peer review, onboarding of new team members, and future reversals. Before using this prompt, gather the proposed boundary, the specific options considered, the trade-off dimensions (latency, consistency, team autonomy, operational complexity), and the reversal trigger conditions. If you cannot articulate at least two rejected alternatives with concrete trade-offs, you are not ready to use this template. The resulting ADR should be stored alongside the code it governs and referenced in implementation PRs and future architecture reviews.

The following prompt template is designed to be pasted directly into your AI system. It instructs the model to act as a systems architect and produce a rigorous, structured decision record. The template uses square-bracket placeholders for all dynamic inputs, such as the system context, the specific boundary decision, and the required output schema. Before execution, replace every placeholder with concrete values from your architecture review session.

textCopy
You are a systems architect documenting a service boundary decision. Your output must be a complete, structured Architecture Decision Record (ADR) based on the provided context.

## CONTEXT
[SYSTEM_CONTEXT]

## DECISION TO BE MADE
[DECISION_STATEMENT]

## OPTIONS CONSIDERED
[OPTIONS_LIST]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
You must produce a valid JSON object conforming to the following structure. Do not include any text outside the JSON object.
{
  "title": "ADR: [Short Title of the Decision]",
  "status": "proposed | accepted | deprecated | superseded",
  "context": "A detailed paragraph explaining the system context, business drivers, and technical forces that motivate this decision.",
  "decision": "A clear, concise statement of the chosen service boundary and the architectural pattern used (e.g., strangler fig, separate ways).",
  "options_evaluated": [
    {
      "option": "Name of the option",
      "description": "A summary of the option.",
      "pros": ["list", "of", "advantages"],
      "cons": ["list", "of", "disadvantages"],
      "rejection_reason": "Why this option was not chosen, or null if this is the selected option."
    }
  ],
  "consequences": {
    "positive": ["list of positive outcomes, such as improved team autonomy or independent deployability"],
    "negative": ["list of trade-offs, such as increased operational complexity or eventual consistency challenges"],
    "mitigations": ["list of actions to address the negative consequences"]
  },
  "compliance_validation": {
    "distributed_monolith_risk": "low | medium | high",
    "conways_law_alignment": "aligned | misaligned",
    "data_ownership_clarity": "clear | ambiguous",
    "notes": "A brief explanation of the compliance assessment."
  },
  "review_gates": [
    "A checklist of concrete criteria that must be true for this decision to be considered successful (e.g., 'Service can be deployed independently of the monolith')."
  ],
  "reversal_triggers": [
    "A list of specific conditions that would trigger a re-evaluation or reversal of this decision (e.g., 'Team topology changes invalidate the bounded context alignment')."
  ]
}

## INSTRUCTIONS
1.  Analyze the CONTEXT, DECISION, OPTIONS, and CONSTRAINTS.
2.  Select the most appropriate option and document it as the `decision`.
3.  Populate the entire JSON schema, ensuring all fields are complete and accurate.
4.  For the `compliance_validation`, perform a rigorous check against the known risks of distributed systems.
5.  The `review_gates` must be measurable and the `reversal_triggers` must be observable.

To adapt this template, replace the placeholders with your specific data. [SYSTEM_CONTEXT] should be a dense paragraph describing the current architecture, team structure, and business goals. [DECISION_STATEMENT] is the precise boundary question, such as 'Should the Payment domain be extracted from the Core Monolith?'. [OPTIONS_LIST] should enumerate the alternatives, including the status quo. For high-risk domains like finance or healthcare, always route the generated ADR through a human review gate before marking its status as accepted.

The Service Boundary Decision Record Template Prompt is designed to be called from an architecture review pipeline, not as a one-off chat interaction. The prompt expects structured inputs—system context, options considered, coupling metrics, team topology data—and produces a structured ADR that downstream tools can validate, store, and compare. Treat this prompt as a document generator inside a decision governance workflow, not a standalone advisor. The output should be version-controlled alongside the architecture it describes.

Wire the prompt into an application by building a pre-processing step that assembles the required context from your architecture registry, service catalog, or dependency graph tooling. For example, fetch afferent/efferent coupling scores from a service dependency analyzer, pull team ownership data from your org chart or platform, and retrieve existing ADRs that share the same bounded context. Feed these into the [CONTEXT] placeholder as structured JSON or Markdown. After the model responds, run a schema validator against the expected ADR structure: check for required fields like Decision, Options Considered, Rejected Alternatives, Consequences, Compliance Validation, and Reversal Trigger Conditions. If validation fails, route to a repair prompt or flag for human authoring. Log every generation attempt with the input context hash, model version, and validator results for auditability.

For high-risk boundary decisions—those affecting data consistency guarantees, security isolation, or multi-team coordination—require human approval before the ADR is accepted. Implement a review gate that presents the generated ADR alongside a diff of any existing ADR for the same boundary, coupling score trends, and a checklist of distributed monolith risk factors. Use a model with strong structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set temperature low (0.0–0.2) to maximize consistency. Do not use this prompt to make the decision; use it to document the decision the team has already analyzed. The prompt's value is in producing a complete, comparable, and queryable record that survives the meeting where the boundary was debated.