architecture-decision-records

Create and manage Architecture Decision Records documenting technical decisions and trade-offs.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Significant architectural decisions often lose their context and rationale over time, leaving teams unable to explain why technologies were chosen or trade-offs accepted. This Skill provides structured templates and workflows for capturing decisions, options considered, and consequences in durable Architecture Decision Records. ## 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), directory structure, index maintenance, and adr-tools automation commands. - Review Process Guidance: Provides checklists for pre-submission, review, and post-acceptance steps to ensure decisions are properly vetted. - Use Case: When choosing between PostgreSQL, MySQL, and MongoDB for a new platform, use this Skill to document the context, decision drivers, considered options with pros and cons, and consequences in a standard ADR that future team members can reference. ## Quick Start Create an Architecture Decision Record documenting our choice of PostgreSQL over MongoDB for the user service, including context, options considered, 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?▼

Write an ADR by capturing the context and decision drivers, listing considered options with pros and cons, stating the decision and rationale, and documenting consequences. Use the MADR template for significant decisions or the lightweight template for smaller ones.

When should I write an ADR versus skip it?▼

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

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. Y-Statement is a single-sentence format capturing context, decision, alternatives, and accepted trade-offs for quick documentation.

How do I deprecate or supersede an existing ADR?▼

Create a new ADR that references the old one and update the old ADR's status to Deprecated or Superseded. Never edit accepted ADRs in place; the adr-tools command 'adr new -s N' automates superseding.

What are the limitations of Architecture Decision Records?▼

ADRs document decisions but do not enforce implementation or validate outcomes. They require team discipline to keep updated, and an ADR without follow-through on implementation tickets provides no value.