architecture-decision-records

Write and maintain Architecture Decision Records documenting technical decisions and trade-offs.

2|Updated Jun 16, 2026
One-click install
npx skills add https://github.com/monang404/lunawave --skill architecture-decision-records-monang404
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/monang404/lunawave/tree/main/.agent/skills/architecture-decision-records
Command: npx skills add https://github.com/monang404/lunawave --skill architecture-decision-records-monang404

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose track of why significant technical decisions were made, making it hard to onboard new members, review past choices, or avoid repeating mistakes. This Skill provides structured templates and processes for capturing architectural decisions with their context, rationale, and consequences. ## Core Features & Use Cases - Multiple ADR Templates: Includes MADR standard format, lightweight ADR, Y-Statement, deprecation, and RFC-style templates for different decision types. - ADR Lifecycle Management: Covers status transitions (Proposed, Accepted, Deprecated, Superseded, Rejected), directory structure, index maintenance, and adr-tools automation. - Review Process Guidance: Provides checklists for pre-submission, review, and post-acceptance steps to ensure decision quality. - Use Case: When choosing between PostgreSQL and MongoDB for a new service, use this Skill to document the context, considered options with trade-offs, the final decision, and its consequences in a standardized ADR file. ## Quick Start Write an ADR documenting the decision to adopt event sourcing for the order management service, including context, alternatives, and consequences.

Frequently Asked Questions about architecture-decision-records

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an Architecture Decision Record?▼

An ADR documents the context requiring a decision, the considered options with pros and cons, the final decision with rationale, and its consequences. Use the MADR template for significant decisions or the lightweight template for smaller choices, then store it in a docs/adr directory.

When should I write an ADR versus skipping it?▼

Write an ADR for framework adoptions, database choices, API design patterns, security architecture, and integration patterns. Skip ADRs for minor version upgrades, bug fixes, routine maintenance, and small implementation details that carry no architectural significance.

What is the difference between MADR and Y-Statement ADR formats?▼

MADR is a full template with sections for context, decision drivers, options, and consequences, suited for major decisions. Y-Statement is a single-sentence format capturing context, decision, alternatives, and accepted trade-offs, ideal for quick documentation.

How do I deprecate or supersede an existing ADR?▼

Never edit an accepted ADR; instead write a new ADR that supersedes it, update the old ADR's status to Deprecated or Superseded, and link both records. The adr-tools command 'adr new -s N' automates superseding an existing record.

Can adr-tools automate ADR management?▼

Yes, adr-tools provides commands to initialize an ADR directory, create numbered records, supersede existing ADRs, link related decisions, and generate a table of contents. Install it via Homebrew with 'brew install adr-tools'.