WritingTechnical WritingAdvanced45 minSaves 1 hour

Architecture Decision Record (ADR) Template with SQS vs. Kafka Example

Engineering teams need a structured way to document key technical choices. This prompt provides an ADR template and a practical example comparing SQS and Kafka for event bus selection, aiding consistent decision-making now.

This resource provides a structured Architecture Decision Record (ADR) template designed for engineering teams. It includes a complete, worked example illustrating the process of choosing between SQS and Kafka for an event bus, promoting clear documentation of architectural choices.

READY-TO-USE PROMPT

Copy Prompt

prompt.txt
As an expert technical writer with a deep understanding of software architecture and documentation best practices, your task is to generate a comprehensive document. This document will provide both a general-purpose Architecture Decision Record (ADR) template and a concrete example of an ADR.

### Role
You are an experienced technical writer specializing in documentation for engineering teams. You understand the importance of clear, concise, and structured communication of architectural decisions.

### Context
Architecture Decision Records (ADRs) are short text documents that capture a single architectural decision, its context, the options considered, and the chosen solution's consequences. They serve as a crucial historical log and communication tool for engineering teams. The objective is to equip teams with a reusable template and a practical, well-articulated example.

### Task
Produce a document containing two main sections:
1.  **ADR Template:** A markdown-formatted, general-purpose template for an Architecture Decision Record.
2.  **ADR Example:** A complete, filled-out Architecture Decision Record example, using the template, for the decision of choosing between SQS and Kafka as an event bus.

The overall output document must adhere to the following structure:

#### Overview
Introduce the purpose of the document: providing an ADR template and a practical example to guide engineering teams in documenting architectural decisions.
#### Prerequisites
List any knowledge or context an engineering team would need before effectively using ADRs (e.g., understanding the system's architecture, decision-making process).
#### ADR Template
Present the markdown-formatted ADR template. This template should include the following core sections:
*   **Title:** A concise name for the decision.
*   **Status:** Proposed, Accepted, Rejected, Superseded.
*   **Context:** The technical problem or challenge being addressed.
*   **Decision:** The chosen solution and rationale.
*   **Consequences:** Positive and negative implications, and future considerations.
*   **Alternatives Considered:** Other options evaluated and why they were not chosen.
#### ADR Example: SQS vs. Kafka Event Bus
Present the filled-out ADR example. This example should detail the decision-making process for selecting between SQS and Kafka for an event bus in a microservices environment. Ensure the example clearly articulates:
*   The specific problem (e.g., need for asynchronous communication, decoupled services).
*   The options (AWS SQS, Apache Kafka).
*   Evaluation criteria (e.g., cost, scalability, operational overhead, message durability, ordering guarantees, integration complexity).
*   The chosen solution and its justification based on a hypothetical scenario (e.g., initial focus on simplicity and managed service, scaling later).
*   The known consequences and trade-offs of that choice.
#### Verification
Explain how an engineering team can verify the ADR's effectiveness (e.g., peer review, ability to understand the decision months later).
#### Troubleshooting
Provide guidance on common issues when writing ADRs (e.g., too much detail, too little detail, lack of consensus).
#### Related Links
Suggest resources for further reading on ADRs, SQS, and Kafka.

### Constraints
*   The tone must be precise, professional, and respectful of the reader's intelligence. Avoid jargon-for-jargon's-sake.
*   The ADR template should be easily copy-pastable and usable in a markdown file.
*   The example ADR should be realistic and detailed enough to serve as a practical guide.
*   Emphasize clarity and conciseness in both the template and the example.
*   The decision in the example ADR should consider the {{team_size}} and {{current_infrastructure_stack}} to make the rationale more concrete.
*   Ensure all sections of the overall document structure are present and adequately detailed.

### Output
A single, coherent document structured as described above, containing both the ADR template and the specific SQS vs. Kafka example.

Estimated results

DifficultyAdvanced
Setup time45 min
Time saved1 hour
Best modelsChatGPT, Gemini, Claude
Best audienceSoftware Development, IT Consulting

Editor's note

Why this prompt matters

Engineering teams frequently encounter critical technical choices that shape the long-term viability and maintainability of their systems. Without a structured approach to documenting these decisions, teams risk losing context, repeating past mistakes, and struggling to onboard new members effectively. This workflow addresses that challenge by providing a clear framework for creating Architecture Decision Records (ADRs). It's designed for engineering leads, architects, and technical writers who need to formalize how significant technical decisions are made and recorded within their organizations.

The value of this approach lies in its ability to foster transparency and provide a historical log of architectural evolution. By capturing the context, alternatives considered, and consequences of each decision, teams can ensure alignment and accountability. Reach for this workflow when your team is making a non-trivial technical choice—such as selecting a core technology, defining an integration pattern, or refactoring a major component—and needs to ensure that the rationale is clear, accessible, and enduring for future reference.

Anatomy

Prompt engineering breakdown

Role

The prompt establishes the role as an 'expert technical writer with a deep understanding of software architecture and documentation best practices,' and further specifies 'specializing in documentation for engineering teams.'

Context

Architecture Decision Records (ADRs) are defined as 'short text documents that capture a single architectural decision' and are crucial for 'historical log and communication tool for engineering teams.' The overall objective is 'to equip teams with a reusable template and a practical, well-articulated example.'

Goal

The primary goal is to 'generate a comprehensive document' containing two main sections: an 'ADR Template' (markdown-formatted) and a 'complete, filled-out Architecture Decision Record example' for choosing between SQS and Kafka as an event bus. This document must follow a specific top-level structure (Overview, Prerequisites, etc.).

Constraints

Key constraints include a 'precise, professional' tone, avoiding 'jargon-for-jargon's-sake,' ensuring the template is 'easily copy-pastable,' and the example is 'realistic and detailed.' The example must also consider specific variables like '{{team_size}}' and '{{current_infrastructure_stack}}' for concreteness. All specified sections of the output document must be present.

Output format

The output is a 'single, coherent document' with a strict hierarchical structure: Overview, Prerequisites, ADR Template, ADR Example: SQS vs. Kafka Event Bus, Verification, Troubleshooting, and Related Links. The ADR template itself must be markdown-formatted.

Why this structure works

This prompt structure works by clearly defining the model's role as an expert technical writer, ensuring the output aligns with professional documentation standards. Explicit constraints on tone and detail prevent generic responses. The highly structured output format, including specific sections and placeholders, guides the model to produce a comprehensive, organized, and directly usable document that meets the user's practical needs.

Pick your version

Prompt variations

BeginnerWorks with any model

For individuals new to ADRs or needing a basic template without deep technical examples. Focuses on clarity and fundamental concepts.

prompt.txt
You are a technical writer helping a new team document their choices. Provide a straightforward Architecture Decision Record (ADR) template. Then, using this template, create a simple example ADR for the decision on '{{decision_topic}}'. Keep the language clear and avoid overly complex technical details. The template should include sections for Title, Context, Decision, and Consequences. The example should briefly fill these out for the chosen topic. Aim for clarity over exhaustive detail, making it easy for anyone to understand the decision and its implications.
ProfessionalBest with chatgpt

When an engineering team needs a detailed ADR template and a comprehensive example for complex architectural decisions, aligning with standard best practices.

prompt.txt
As an expert technical writer, generate a comprehensive document providing a general-purpose Architecture Decision Record (ADR) template and a concrete example. The document must include an Overview, Prerequisites, the ADR Template (with Title, Status, Context, Decision, Consequences, Alternatives), a detailed ADR Example for choosing between SQS and Kafka as an event bus (considering a {{team_size}} team and {{current_infrastructure_stack}}), Verification, Troubleshooting, and Related Links. The example should articulate the problem, options, evaluation criteria, chosen solution, and trade-offs. Maintain a precise, professional tone, avoiding jargon. The template should be markdown-formatted and the example realistic.
Short VersionWorks with any model

For quick generation of a basic ADR template or a brief, summary-level ADR example, ideal for rapid prototyping or initial discussions.

prompt.txt
As a concise technical writer, provide a markdown-formatted Architecture Decision Record (ADR) template. Include essential sections: Title, Status, Context, Decision, Consequences, and Alternatives Considered. Following this, generate a brief, high-level example ADR for selecting an event bus, contrasting SQS and Kafka, highlighting the core decision and a few key trade-offs. The goal is a quick reference for architectural documentation. Use placeholders for {{decision_focus}} and {{key_consideration}}.
EnterpriseBest with claude

For large organizations or regulated industries where architectural decisions require formal documentation, compliance considerations, and stakeholder communication.

prompt.txt
Act as a senior technical architect and compliance specialist. Generate a comprehensive Architecture Decision Record (ADR) template tailored for enterprise environments, emphasizing formal review, risk assessment, and long-term governance. Include sections for Title, Status, Context, Decision, Consequences (detailing technical, operational, and business impacts), Alternatives Considered, Risk Assessment, Compliance Considerations, and Stakeholder Alignment. Subsequently, create a comprehensive ADR example using this template for the decision of choosing between SQS and Kafka as an event bus, considering a {{team_size}} team, {{current_infrastructure_stack}} infrastructure, {{regulatory_requirements}} compliance, and the needs of {{stakeholder_groups}}. Ensure the example explicitly addresses governance, long-term maintenance, and potential future scaling challenges.

What you'll get

Expected output

# Architecture Decision Record: ADR-005 - Choosing an Event Bus for Microservices Communication

Status

Accepted

Context

Our microservices architecture currently relies on synchronous HTTP communication. As our services grow and the need for asynchronous processing and decoupling increases, this approach is becoming a bottleneck. We require a scalable and reliable event bus to facilitate asynchronous communication, enable event-driven patterns, and improve system resilience. Key drivers include reducing service coupling and improving responsiveness. Our team size is small to medium (5-15 engineers), and our infrastructure is AWS-centric, favoring managed services.

Decision

We have chosen AWS SQS (Simple Queue Service) as our primary event bus. This decision prioritizes operational simplicity, its fully managed nature, cost-effectiveness for our current scale, and seamless integration within our existing AWS infrastructure. SQS provides sufficient message durability and at-least-once delivery for immediate needs, allowing rapid implementation of decoupled communication without significant operational overhead. We will use standard queues initially, reserving FIFO for strict ordering requirements.

Consequences

Positive

  • Reduced Operational Overhead: Fully managed service, minimizing dedicated operational support.
  • Cost-Effective at Current Scale: Pay-per-use model aligns with current message volumes.
  • Rapid Development: Easy integration with AWS services and SDKs.
  • Improved Decoupling: Enhances system resilience.

Negative

  • Limited Ordering Guarantees (Standard SQS): Requires careful design for idempotency or use of FIFO.
  • No Built-in Fan-out (without SNS): Requires SNS for broadcasting, adding complexity.
  • Potential for Vendor Lock-in: Deep AWS integration.

Future Considerations

  • Monitor message volumes; evaluate Kafka or Kinesis if SQS limits are approached.
  • Develop consistent SQS message patterns and error handling.

Alternatives Considered

  • Apache Kafka (Self-Managed or Managed Services):

* Why not chosen: Offers superior throughput and strict ordering, but its operational complexity and higher initial cost were deemed too high for our small-to-medium team at this stage. We prioritize simplicity and rapid iteration.

  • AWS Kinesis Data Streams:

* Why not chosen: Considered for streaming, but SQS's simpler queueing semantics better fit our initial asynchronous messaging needs. Kinesis's scaling and cost model were less appealing for our current use case.

Under the hood

Why this prompt works

This prompt's effectiveness stems from its structured approach, which guides the model to produce a comprehensive and accurate output. Role priming is crucial, establishing the model as an 'expert technical writer with a deep understanding of software architecture and documentation best practices.' This sets the appropriate tone and ensures the output reflects a professional, informed perspective.

The prompt employs explicit constraints by detailing the overall document structure (Overview, Prerequisites, Template, Example, Verification, Troubleshooting, Related Links) and the internal structure of the ADR template itself. This prevents generic responses and forces the model to organize information logically. Furthermore, specifying the required sections within the ADR example (problem, options, criteria, chosen solution, consequences) acts as few-shot scaffolding, providing a clear blueprint for the content.

By requesting both a general template and a concrete, filled-out example (SQS vs. Kafka), the prompt leverages example-driven generation. The example clarifies the expected depth, detail, and realism. The inclusion of dynamic parameters like {{team_size}} and {{current_infrastructure_stack}} (even if hypothetical in the example) demonstrates how the prompt can be tailored, leading to more contextually relevant and practical advice than a simple, open-ended request.

Model fit

Best AI models for this prompt

ChatGPT

Good for generating structured text and following complex instructions. It can effectively produce both the template and the detailed example, maintaining the requested tone. Its limitations sometimes include generating overly generic examples if not prompted with enough specific context. See the full ChatGPT hub for deeper guidance.

Claude

Excels at long-form content generation and adhering to intricate formatting and structural requirements. It handles the distinct sections for the template and the detailed SQS/Kafka example well, often providing thoughtful rationales. Claude's verbosity can sometimes require minor editing for conciseness. See the full Claude hub for deeper guidance.

Gemini

Capable of handling multi-part requests and generating technical content. It is efficient in producing both the template and the example, often providing strong logical consistency in the decision-making process. Gemini can sometimes be less nuanced in its explanations compared to Claude, requiring more specific guidance on evaluation criteria. See the full Gemini hub for deeper guidance.

When to use

  • When making significant architectural choices with long-term system impact.
  • For documenting decisions involving trade-offs between multiple viable solutions.
  • To provide historical context and rationale for current system architecture to new team members.
  • When a decision affects multiple teams or components, requiring clear communication.
  • To justify major technology adoptions or shifts in infrastructure strategy.

When not to use

  • For minor, reversible tactical coding decisions or routine implementation details.
  • When a decision is purely operational and does not alter the system's architecture.
  • For documenting temporary experiments or proof-of-concept work that won't be adopted.
  • When an existing, simpler documentation method (e.g., code comments, README) suffices for the scope.

Get more from it

Pro tips

  • 1

    Focus on the 'why' behind the decision, not just the 'what.' This prevents future teams from misunderstanding the core rationale.

  • 2

    Involve relevant stakeholders early in the ADR drafting process. This prevents rework and ensures broader team buy-in.

  • 3

    Keep ADRs concise, typically one to two pages. This prevents information overload and encourages focused decision-making.

  • 4

    Clearly articulate the known trade-offs and consequences. This prevents surprises and sets realistic expectations for the decision's impact.

  • 5

    Date and assign a clear status to each ADR. This prevents confusion about a decision's current validity and lifecycle.

  • 6

    Reference external documentation or research instead of embedding it. This prevents ADRs from becoming excessively long and hard to maintain.

Don't ship this

Common mistakes

  • Overly verbose ADRs that include too much implementation detail, making them difficult to parse.

    Fix — Limit ADRs to architectural impact and rationale. Defer specific implementation details to design documents or code.

  • Omitting alternatives considered, which can lead to questions about the decision-making thoroughness.

    Fix — Always list viable alternatives and briefly explain why they were not chosen, even if the reasons seem obvious.

  • Lack of clear status or date, leading to ambiguity about the decision's current relevance.

    Fix — Consistently use the 'Status' field and date the ADR to reflect its lifecycle (Proposed, Accepted, Superseded).

  • Writing ADRs as an afterthought, rather than as part of the decision process itself.

    Fix — Integrate ADR creation into your team's decision-making workflow to capture context as it unfolds.

  • Vague or missing consequences, leaving future teams without full understanding of trade-offs.

    Fix — Explicitly state both positive and negative implications, covering operational, maintenance, and technical debt aspects.

People also ask

Frequently asked questions

Q.How frequently should an engineering team write ADRs?

Write an ADR for any decision that significantly alters the system's architecture, introduces new major components, or has long-term implications for development, operations, or cost. This is typically not a daily or weekly task.

Q.Can an ADR be modified after it has been accepted?

Accepted ADRs are generally considered immutable for historical accuracy. If a decision needs to change, create a new ADR that explicitly supersedes the old one, referencing the original for context. This maintains a clear decision history.

Q.What is the ideal length for an Architecture Decision Record?

Aim for conciseness. A good ADR should be readable and understandable within 5-10 minutes. Typically, one to two pages of markdown is sufficient, focusing on essential information without excessive detail or deep dives into code.

Q.Who is responsible for drafting and maintaining ADRs within a team?

The individual or team proposing a significant architectural change is usually responsible for drafting the ADR. Ownership for maintenance often falls to the architecture lead or the team responsible for the affected component, ensuring ongoing relevance.

Q.What if the team cannot reach a complete consensus on an architectural decision?

An ADR should still document the decision, even if not universally agreed upon. It can capture the various viewpoints and the rationale for the chosen path, providing transparency and a record of the discussion, even without full consensus.

Version 1.0Last reviewed July 8, 2026
Reviewed by PromptInFlow Editorial Team