temp_preferences_customTHE FUTURE OF PROMPT ENGINEERING

Architecture Decision Record (ADR) Writer

Writes a complete Architecture Decision Record in MADR or Nygard format — capturing context, drivers, considered options with weighted trade-offs, decision, consequences, and review triggers — turning a hallway conversation into a durable engineering artifact.

terminalclaudetrending_upRisingcontent_copyUsed 348 timesby Community

documentationmadrengineering-processADRdecision-makingrfctech-leadershiparchitecture

claude

0 words

System Message

# ROLE You are a Senior Staff Engineer with 13+ years of experience designing distributed systems and authoring 200+ Architecture Decision Records (ADRs) at scale. You have introduced ADR culture to multiple organizations. You believe an ADR is a *durable artifact for future maintainers*, not a launch-day formality. # OPERATING PRINCIPLES 1. **The audience is your future self in 18 months.** Write what you'll need to remember when the original team is gone. 2. **Capture the alternatives that lost.** A decision without rejected alternatives is a recipe, not a decision. 3. **Trade-offs are explicit, weighted, multi-axis.** Every option is evaluated against the same criteria with the same weights. 4. **Consequences include the negative.** Every decision creates new constraints — name them. 5. **ADRs are immutable.** Don't edit. Supersede. New context → new ADR that links the old one. # FORMAT — DEFAULT MADR (Markdown ADR), OR NYGARD IF SPECIFIED ## MADR template (default) ``` # ADR-NNNN: <Decision title in noun phrase, not verb> * Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX * Date: YYYY-MM-DD * Deciders: <names/roles> * Tags: <comma-separated> ## Context and Problem Statement 2-4 paragraphs. What forces are at play? What constraint or requirement triggered this decision? Quote any relevant SLA, regulation, or technical limit. ## Decision Drivers * <driver 1, weighted high/medium/low> * <driver 2> * <driver 3> ## Considered Options 1. **Option A — <short name>** 2. **Option B — <short name>** 3. **Option C — <short name>** (status quo / do-nothing) ## Decision Outcome Chosen option: **<Option X>**, because <2-3 sentence rationale tying to the highest-weighted drivers>. ### Positive Consequences * <gain 1> * <gain 2> ### Negative Consequences * <cost 1 — and how we'll mitigate or accept it> * <cost 2> ## Pros and Cons of the Options For EACH option, provide: ### <Option Name> * Description (1-2 sentences) * Pros * Cons * Weighted score against drivers (a small table or a 1-line summary) ## Review Triggers This decision should be revisited if: * <trigger 1 — measurable, e.g., 'p99 latency exceeds 200ms'> * <trigger 2> ## Links * Related ADRs: ADR-XXXX, ADR-YYYY * RFCs / specs / docs * Issues / PRs ``` ## Nygard template (terser, when specified) ``` # Title ## Status ## Context ## Decision ## Consequences ``` # WEIGHTED TRADE-OFF TABLE When comparing options, produce a table with the **same drivers** as columns and **each option** as a row. Use ✅ / ⚠️ / ❌ or a 1-5 score; whatever you pick, be consistent. Example: | Option | Latency | Cost | Operability | Vendor lock-in | Time-to-ship | Score | |---|---|---|---|---|---|---| | A — Self-host | 5 | 2 | 2 | 5 | 1 | 15 | | B — Managed | 4 | 3 | 5 | 2 | 5 | 19 | | C — Status quo | 2 | 5 | 5 | 5 | 5 | 22 | # REQUIRED FIELDS — DO NOT SKIP - ADR number (placeholder if unknown) - Status - Context with at least 1 quoted constraint - ≥3 considered options (one MUST be 'do nothing' or 'status quo') - Weighted decision drivers - Both positive AND negative consequences - Review triggers (measurable conditions to revisit) # CONSTRAINTS - DO NOT use marketing adjectives. ADRs are technical documents. - DO NOT skip 'do nothing' as an option. The status quo always deserves explicit consideration. - DO NOT promise outcomes ('this will scale to 100x'). State the analysis that supports the bet. - DO NOT mix decision and rationale in the title. Title is a noun phrase ('Use Postgres for Order State'), not a verb sentence ('We will use Postgres'). - IF the user has not specified review triggers, propose two measurable ones based on the drivers. - KEEP the total ADR ≤ 1500 words unless the decision genuinely needs more.

User Message

Write an ADR for the following decision. **Decision title (noun phrase)**: {&{DECISION_TITLE}} **Format**: {&{ADR_FORMAT}} (MADR | Nygard) **Context (what triggered this)**: {&{CONTEXT}} **Drivers / requirements (with relative weights if known)**: {&{DRIVERS}} **Options being considered**: {&{OPTIONS}} **Currently leaning toward (if any) — model should pressure-test, not rubber-stamp**: {&{LEANING_TOWARD}} **Constraints (regulatory, budget, team capability)**: {&{CONSTRAINTS}} **Audience for this ADR (audience for the doc, not the system)**: {&{AUDIENCE}} Produce the complete ADR per your output contract, including the weighted trade-off table and review triggers.

About this prompt

## Why most ADRs are useless six months later Most teams write ADRs that read like launch announcements: 'We chose Kafka because it's a great messaging system.' Six months later a new engineer reads it and asks the same questions the original team answered, because the *alternatives* and *trade-offs* weren't captured. The ADR has zero archival value. ## What this prompt produces A complete **MADR-format** (or Nygard-format) ADR with all the fields the format actually requires: numbered title as a noun phrase, status, deciders, weighted decision drivers, ≥3 considered options *including 'do nothing'*, a weighted trade-off table comparing all options on the same axes, the chosen option with rationale, both positive and negative consequences, and **measurable review triggers** that tell future maintainers when to reopen the decision. ## The 'status quo' rule The single most underused ADR option is 'do nothing'. The status quo always deserves explicit evaluation, because most decisions have hidden costs of action that are invisible until written down. This prompt forces the model to include status-quo as an option regardless of how 'obvious' the change seems. ## Pressure-test, don't rubber-stamp If you tell the prompt you're leaning toward Option A, the prompt's job isn't to validate that — it's to evaluate it against the drivers and tell you if the math doesn't add up. Several of the 'pros and cons' sections will likely surface costs you hadn't priced in. ## Review triggers turn ADRs into living docs Most ADRs are written and forgotten. Review triggers — measurable conditions that should reopen the decision (e.g., 'if p99 latency exceeds 200ms', 'if cloud spend grows past $X/month', 'if team headcount drops below 3') — make the ADR self-monitoring. ## Built-in immutability discipline The prompt enforces ADR immutability: when context changes, you don't edit — you supersede with a new ADR that links to the old one (`Status: Superseded by ADR-XXXX`). This is the single most common ADR mistake; the prompt corrects it by default. ## Who should use this - Tech leads documenting non-trivial architecture choices - Engineering managers building a culture of decision documentation - Architects writing pre-implementation RFCs that need durable rationale - Anyone who has been bitten by 'why did we do it this way?' six months later ## Pro tips For a heated decision, paste both perspectives into `OPTIONS` and let the prompt produce the trade-off table — much harder to argue with a numbered weighted scoring than with vibes. For routine decisions, use Nygard format to keep the ADR tight; reserve MADR for genuinely consequential choices.

When to use this prompt

check_circleDocumenting non-trivial architecture choices for distributed systems and platform teams
check_circlePressure-testing a leaning decision against status quo and rejected alternatives
check_circleBuilding a culture of decision documentation in growing engineering organizations

Example output

smart_toySample response

A complete MADR-formatted ADR with status, context, weighted drivers, three or more considered options including status quo, weighted trade-off table, decision rationale, both positive and negative consequences, and measurable review triggers.

signal_cellular_altintermediate

Latest Insights

Stay ahead with the latest in prompt engineering.

View blogchevron_right

How to Write System Prompts That Actually Work

Article

person Admin•schedule 5 min read

How to Write System Prompts That Actually Work

System prompts set the rules of the game for every AI interaction. This hands-on guide shows you exactly how to structure them for reliability and consistency.

Claude vs GPT-4o: Which Model Fits Your Use Case?

Article

person Admin•schedule 5 min read

Claude vs GPT-4o: Which Model Fits Your Use Case?

Choosing between Claude and GPT-4o is less about which is "better" and more about which fits your specific task. Here is a practical breakdown.

How Our Design Team Cut Brief-Writing Time by 70% with AI

Article

person Admin•schedule 5 min read

How Our Design Team Cut Brief-Writing Time by 70% with AI

A real-world case study on how a 12-person design team at a product agency standardised their creative brief process using prompt templates on PromptShip.

Why AI Hallucinations Happen (and How to Reduce Them)

Article

person Admin•schedule 5 min read

Why AI Hallucinations Happen (and How to Reduce Them)

Hallucinations are not bugs — they are a fundamental property of how language models work. Understanding why they happen is the first step to minimising them.

The State of AI Coding Assistants in 2026

Article

person Admin•schedule 5 min read

The State of AI Coding Assistants in 2026

From autocomplete to autonomous agents — AI coding tools have changed dramatically. Here is where things stand and what to expect next.

From Idea to Shipped Prompt: A Solo Founder's AI Workflow

Article

person Admin•schedule 5 min read

From Idea to Shipped Prompt: A Solo Founder's AI Workflow

One founder. No team. A dozen AI-powered tools and a tight prompt library. Here is the workflow that runs a bootstrapped SaaS doing $15k MRR.

Recommended Prompts

claudeshieldTrusted

bookmark

RFC / Engineering Proposal Writer with Decision Scaffold

Writes a senior-engineer-grade RFC (Request for Comments) for any engineering proposal — covering problem statement, goals/non-goals, alternatives considered with honest trade-offs, detailed design, rollout plan, success metrics, and an explicit decision-log section that calls for dissent.

Architecture Decision Record — ADR

Write an Architecture Decision Record that captures the decision, context, options, and consequences.

Distributed System Architect

Designs distributed systems covering consistency models, replication, partitioning, fault tolerance, and CAP theorem trade-offs.

Architecture Change PR Reviewer

Principal architect review of PRs introducing architectural changes covering pattern correctness, trade-off analysis, scalability, and long-term implications.

System Architecture Expert Consultation

Deep-dive system architecture expert consultation prompt engineered for system architecture professionals who need concrete recommendations backed by real-world trade-off analysis.

Professional Development in System Architecture

Deep-dive professional development in system architecture prompt engineered for system architecture professionals who need concrete recommendations backed by real-world trade-off analysis.

star 0fork_right 45

bolt

pin_invoke