What is an Architecture Decision Record (ADR) and what does it capture?

An ADR is a structured document that captures important architectural decisions made during software development. It preserves institutional knowledge, eases team communication, and provides historical context by documenting the decision's title, status, context (forces at play), the decision itself with rationale, and its consequences (both positive and negative).

What are the required sections in an ADR?

An ADR must include: a title in imperative mood (e.g., 'Adopt GraphQL for the API Gateway'), a Status field (Proposed, Accepted, Deprecated, or Superseded by ADR-XXX), a Context section describing technical and organizational factors, a Decision section stating the architectural choice and rationale, and a Consequences section describing resulting effects.

When should I use this skill versus when should I avoid it?

Use this skill for significant architectural decisions with lasting impact that future team members will need context on—such as technology choices, pattern adoptions, or major system design changes with real trade-offs. Do not use it for minor implementation details with no lasting architectural significance or for decisions still under active debate with no chosen direction yet.

What output format does this skill produce?

This skill produces standalone Markdown ADR documents meant to live in a project's docs/adr directory or wiki. The documents follow a standardized structure with sections for status, context, decision, consequences, risks/mitigations, and related-decision links.

What key principles should ADRs follow?

Key ADR principles include: immutability (accepted ADRs aren't edited, they're superseded), atomicity (each ADR covers one architectural decision), sequential numbering for chronological order, and clear traceability links between related ADRs.

Skill

Document Architectural Decisions with ADRs

Name: Document Architectural Decisions with ADRs
Availability: OnlineOnly
Author: VibeBaza

Create focused Architecture Decision Records that capture context, a concrete choice, consequences, risks, and links to related decisions.

Get skill

Works with github

VibeBaza

Own this? Claim it

Spark score

out of 100

Updated 3 months ago

Source checked Oct 11, 2026

Version 1.0.0

Models

claude

Add to Favorites

Why it matters

Capture and maintain critical architectural decisions for your software projects. Ensure clarity, consistency, and historical context for your team's technical choices.

Outcomes

What it gets done

Generate structured Architecture Decision Records (ADRs).

Define context, decision, and consequences for architectural choices.

Maintain ADR immutability and traceability.

Facilitate team communication and knowledge preservation.

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-architecture-decision-record | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Overview

A skill for writing focused Architecture Decision Records that preserve a decision's context, rationale, status, and consequences. It includes guidance for risks, alternatives, research, indexes, and links between records. Use it when recording an architectural choice that needs to remain understandable over time. Verify project-specific context, measurements, and status before publishing an ADR.

What it does

Architecture Decision Record Expert helps teams document significant software architecture choices in a consistent, reviewable format. An ADR captures one decision, the context that led to it, the chosen approach, and the consequences that follow. The source template includes a title, status, context, decision, and consequences, with status values for Proposed, Accepted, Deprecated, or Superseded. It emphasizes specific titles in imperative language, atomic decisions, sequential numbering, immutability after acceptance, and traceable links to related records.

The guidance covers context such as business and technical constraints, current architecture, team expertise, performance, security, scalability, timeline, and budget considerations. It also shows how to document positive and negative consequences, risks with mitigations, alternatives, research findings, and relationships between ADRs.

When to use - and when NOT to

Use this skill when a team needs to record an architectural decision and preserve why it was made for later maintainers. It is useful when comparing options, documenting tradeoffs, or making a choice that affects multiple teams or systems. Keep each record centered on a single decision and make the decision actionable.

Do not treat the sample GraphQL proposal, file paths, dates, links, durations, or performance figures as facts about a real project. They illustrate possible ADR content only. Do not claim a decision was approved or implemented unless its status and implementation are verified. Once an ADR is accepted, Use preserving it and writing a superseding record when the decision changes.

Inputs and outputs

Inputs include the decision to be made, requirements and constraints, the current architecture, options considered, stakeholder context, research findings, risks, and related decisions. Where relevant, include technical, organizational, performance, security, and scalability factors. If a proof of concept informed the decision, record its scope and findings with their evidence.

The output is a Markdown ADR with a clear title, status, context, decision, and consequences. Consequences can include positive and negative effects, risks and mitigations, and links to related or superseded ADRs. For complex choices, It a comparison matrix across criteria such as learning curve, performance, ecosystem, and team expertise. A README index can list ADR number, title, status, date, and relationships.

Integrations

The source focuses on Markdown files and an example docs/adr/ directory containing an index, template, and numbered decision records. It shows references to related ADRs and a sample research link. It does not require a particular ADR management product, programming language, or architecture platform. Teams can adapt the file organization to their repository.

Who it's for

This skill is for software architects, technical leads, and engineering teams who need durable records of important design choices. Reviewers can use its checklist to confirm that the context, decision, consequences, risks, alternatives, related links, and stakeholder review are addressed. Keep project-specific claims evidence-based and distinguish planned choices from accepted decisions.

# ADR-001: [Decision Title]

Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

Context

[Describe the driving forces and constraints]

Decision

[State the architectural decision and rationale]

Consequences

[Describe positive and negative results] ```

FAQ

Common questions

Discussion