architecture-decision-records

Create and maintain Architecture Decision Records that capture the reasoning behind significant technical choices. This skill provides multiple templates—from standard MADR format to lightweight Y-statements—and guidance on when ADRs matter most, helping teams establish clear decision-making processes and onboard members through documented architectural history.

Architecture Decision Records helps you document technical decisions with context, rationale, and consequences using proven templates.

AI-generated summary based on this skill's SKILL.md

★ 38,308 ⁮ 4,097 MIT updated 2026-07-22 by wshobson

Install

wshobson/agents/architecture-decision-records · repository language: Python

Manual (git clone) CLI (skillfed)

git clone https://github.com/wshobson/agents
cp -r agents/plugins/documentation-generation/skills/architecture-decision-records ~/.claude/skills/architecture-decision-records

npx skillfed install wshobson/agents/architecture-decision-records

Frequently asked questions

AI-generated answers based on this skill's SKILL.md and metadata

How to write architecture decision records?

architecture-decision-records helps you create ADRs by providing multiple templates and best practices. Start by identifying a significant technical choice, then document the context (problem statement), decision (what you chose), consequences (trade-offs and impacts), and alternatives considered. The skill supports standard MADR format and lightweight Y-statements, ensuring your team captures reasoning clearly and consistently for future reference.

What is an ADR template for technical decisions?

architecture-decision-records offers several templates including the standard MADR (Markdown Architecture Decision Records) format and Y-statements. MADR typically includes Title, Status, Context, Decision, Consequences, and Alternatives sections. These templates help teams structure decisions uniformly, making it easier to review, compare, and understand the rationale behind architectural choices across your codebase.

When should I write an ADR?

architecture-decision-records guidance suggests writing ADRs for significant technical choices that affect system design, technology selection, or long-term maintainability. Focus on decisions with meaningful trade-offs, those impacting multiple teams, or choices that might be questioned later. Not every decision needs an ADR—reserve them for architectural decisions that warrant documented reasoning and historical context.

How to manage ADRs in a team?

architecture-decision-records supports establishing a decision-making process and governance framework for your team. Implement a review process where ADRs are discussed before finalization, maintain an index of all decisions organized by domain or date, track status (Proposed, Accepted, Deprecated, Superseded), and use ADRs during onboarding to help new members understand historical context and design rationale.

What is the ADR lifecycle and status tracking?

architecture-decision-records enables you to manage ADR lifecycles through status tracking. Decisions typically progress from Proposed (under discussion) to Accepted (approved), then may be Deprecated (no longer recommended) or Superseded (replaced by newer decisions). This lifecycle management helps teams understand which decisions remain active, which have evolved, and provides clear documentation of architectural evolution over time.

How does architecture-decision-records help onboard new team members?

architecture-decision-records captures historical context and design rationale in your ADR index, allowing new team members to quickly understand why architectural choices were made. Rather than relying on tribal knowledge, onboarding becomes systematic—new developers can review the decision history, understand trade-offs, and grasp the reasoning behind current system design through documented architectural records.

SKILL.md

rendered from the published skill — quoted content, verbatim