skills.rest
nperepichka
nperepichkaCOMMUNITY
Explore all skills by this author →
GitHub

architecture-decision-records

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

Updated Aug 19, 2026
Search Tags:#documentation#adr#technical design#architecture decisions#decision records#madr#adr-tools
One-click install
npx skills add https://github.com/nperepichka/Antigravity --skill architecture-decision-records-nperepichka
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/nperepichka/Antigravity/tree/main/config/skills/architecture-decision-records
Command: npx skills add https://github.com/nperepichka/Antigravity --skill architecture-decision-records-nperepichka

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose the context behind major technical choices over time, making it hard to understand why a database, framework, or pattern was selected. This Skill provides structured templates and workflows for capturing architectural decisions so the rationale survives team changes and project evolution. ## Core Features & Use Cases - Multiple ADR Templates: Includes MADR standard format, lightweight ADR, Y-Statement, deprecation records, and RFC-style proposals. - Lifecycle Management: Covers ADR statuses (Proposed, Accepted, Deprecated, Superseded, Rejected), directory structure, index files, and adr-tools automation commands. - Review Process: Provides checklists for pre-submission, review, and post-acceptance steps to keep decision records consistent. - Use Case: When choosing PostgreSQL over MongoDB for a new service, generate a complete ADR documenting context, decision drivers, considered options with pros and cons, consequences, and links to related decisions. ## Quick Start Write an ADR documenting our decision to adopt Redis for caching, including the context, alternatives considered, and expected 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 forcing a decision, the options considered with pros and cons, the chosen 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, and security architecture decisions. 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 structured sentence capturing context, decision, alternatives, and accepted trade-offs, ideal for quick lightweight records.

How do I deprecate or supersede an existing ADR?▼

Never edit an accepted ADR. Instead, write a new ADR that references and supersedes the old one, update the old record's status to Deprecated or Superseded, and refresh the ADR index. The adr new -s command in adr-tools automates superseding.

What tools automate ADR creation and management?▼

adr-tools is a command-line utility that initializes ADR directories, creates numbered records, links related decisions, and generates a table of contents. Install it via Homebrew and use commands like adr new and adr generate toc.

Related Skills

Explore More Software Engineering Skills→
Ryno-Crypto-Mining-ServicesRyno-Crypto-Mining-Services

architect-role-skill

Analyze codebases and generate architectural planning documents.

Official
Advanced
rpelizzarpelizza

pelizzai-writing-plans

Generate structured implementation plans mapping requirements to tasks and acceptance criteria.

Community
Advanced
iamsteveholmesiamsteveholmes

architecture-guard

Detect architecture decision drift in sprint changes and generate findings reports.

Community
Advanced
lucas-ferrari-correalucas-ferrari-correa

new-rfc

Guide structured RFC interviews to generate formal RFC documents.

Community
Advanced