architecture-decision-records

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

Updated Apr 23, 2026

Search Tags:#architecture #documentation #adr #decision records #technical decisions #madr #adr-tools

Ready to run

npx skills add https://github.com/SanketAdlak/PDMProjectDesign --skill architecture-decision-records-sanketadlak

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/SanketAdlak/PDMProjectDesign/tree/main/.agents/skills/architecture-decision-records
Command: npx skills add https://github.com/SanketAdlak/PDMProjectDesign --skill architecture-decision-records-sanketadlak

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose the context behind significant technical decisions over time, making it hard to understand why a technology was chosen, onboard new members, or revisit past choices. This Skill provides structured templates and processes for capturing architectural decisions with their context, rationale, and consequences. ## Core Features & Use Cases - Multiple ADR Templates: Standard MADR format, lightweight ADR, Y-Statement, deprecation records, and RFC-style proposals. - Lifecycle Management: Track ADR status from Proposed through Accepted, Deprecated, and Superseded, with an index README and directory conventions. - Tooling & Review Process: Guidance for adr-tools automation (init, new, supersede, link) plus a review checklist covering security, cost, and reversibility. - Use Case: When choosing PostgreSQL over MongoDB for a new service, generate a complete ADR documenting 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, considered 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 captures three elements: the context requiring a decision, the decision itself, and its consequences. Use the MADR template covering status, decision drivers, considered options with pros and cons, rationale, and positive and negative consequences.

When should I write an ADR versus skip it?▼

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

What ADR format should I use for my team?▼

Use the standard MADR format for major decisions, the lightweight template for quick choices, Y-Statements for concise summaries, and RFC style for proposals needing broad feedback. Deprecation templates handle superseding older decisions.

How do I deprecate or supersede an existing ADR?▼

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

What tools automate ADR management?▼

adr-tools is a command-line utility that initializes ADR directories, creates numbered records, supersedes existing ADRs, links related decisions, and generates a table of contents for the index README.