skills.rest
truongnat
truongnatCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

architecture-decision-records

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

Updated Jul 28, 2026
Search Tags:#architecture#documentation#adr#rfc#technical decisions#madr#adr-tools
One-click install
npx skills add https://github.com/truongnat/Restly --skill architecture-decision-records-truongnat
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/truongnat/Restly/tree/main/.agents/skills/architecture-decision-records
Command: npx skills add https://github.com/truongnat/Restly --skill architecture-decision-records-truongnat

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 the context, decision, and consequences of architectural choices. ## Core Features & Use Cases - Multiple ADR Templates: Standard MADR format, lightweight ADR, Y-Statement, deprecation records, and RFC-style proposals. - ADR Lifecycle Management: Covers statuses from Proposed through Accepted, Deprecated, and Superseded, with directory structure and index conventions. - Review Process & Automation: Includes a review checklist, best practices, and adr-tools CLI commands for creating and linking records. - Use Case: When choosing between PostgreSQL, MySQL, and MongoDB for a new service, use this Skill to produce a complete ADR documenting decision drivers, considered options, rationale, and consequences. ## Quick Start Write an ADR documenting our decision to adopt PostgreSQL as the primary database, including context, considered options, 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 three core elements: the context explaining why a decision was needed, the decision itself, and its consequences. Use the MADR template to also record decision drivers, considered options with pros and cons, and rationale.

When should I write an ADR versus skip it?▼

Write ADRs for significant decisions like framework adoption, database technology choices, API design patterns, and security architecture. Skip them for minor version upgrades, bug fixes, implementation details, and routine configuration changes.

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

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

How do I deprecate or supersede an existing ADR?▼

Create a new ADR that references the old one and mark the original as Deprecated or Superseded rather than editing it. The adr-tools CLI supports this with the command adr new -s <number> to supersede a record.

Can adr-tools automate ADR management?▼

Yes, adr-tools is a CLI that initializes ADR directories, creates numbered records, supersedes existing ADRs, generates tables of contents, and links related decisions. Install it via brew install adr-tools.

Related Skills

Explore More Software Engineering Skills→
windyroadwindyroad
4

wr-architect:create-adr

Create MADR 4.0 Architecture Decision Records in docs/decisions.

Official
Advanced
tuanle96tuanle96

add-adr

Create and update markdown architecture decision records with sequential numbering.

Community
Intermediate
abudhahirabudhahir

architecture-documenter

Generate system architecture documentation and Architecture Decision Records.

Community
Advanced
ACGSpgpACGSpgp

architecture-decision-records

Create and manage Architecture Decision Records with lifecycle tracking.

Official
Intermediate