adr

Name: adr
Availability: InStock
Author: mdproctor

Create and manage MADR-based ADRs with sequential numbering and status lifecycle.

1|5|Updated Mar 29, 2026

Search Tags:#workflow #documentation #adr #traceability #MADR #design-decisions #architectural-decisions

Ready to run

npx skills add https://github.com/mdproctor/claude-skills --skill adr-mdproctor

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/mdproctor/claude-skills/tree/main/adr
Command: npx skills add https://github.com/mdproctor/claude-skills --skill adr-mdproctor

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Helps teams record architectural decisions using the MADR format to ensure decisions are documented, traceable, and maintainable over time.

Core Features & Use Cases

Append-only ADRs with sequential numbering and a clear status lifecycle.
Guided MADR workflow to draft context, decision, consequences, and references.
Store ADRs under docs/adr/ and provide a clear process to supersede old decisions with new ADRs.

Quick Start

Ask Claude to start an ADR for a major design decision, and it will guide you through drafting and saving it to docs/adr/0001-<title>.md.

Frequently Asked Questions about adr

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

FAQPage Schema

How do I document architectural decisions to maintain traceability for my project?▼

Architectural decision records (ADRs) capture design choices using the MADR format to ensure decisions are documented, traceable, and maintainable over time. Sequential numbering and status lifecycle tracking keep the project history clear.

What is the MADR format for writing architectural decision records?▼

The MADR format structures ADRs with explicit Context, Decision, and Consequences sections, along with status tracking and references. This guided workflow helps teams draft clear context and document the rationale behind major design choices.

How do I start an ADR workflow for a major design decision or dependency upgrade?▼

To start an ADR, trigger the workflow for your design decision or dependency upgrade. The system guides you through drafting context, decision, and consequences, then saves the file sequentially under docs/adr/0001-<title>.md.

When should I create an architectural decision record in my software workflow?▼

Create an ADR when making major architectural decisions, such as introducing new components or upgrading dependencies. Documenting these choices provides traceable records that explain why specific design paths were taken over alternatives.

How do I supersede an old architectural decision with a new ADR?▼

To supersede an old architectural decision, create a new ADR with the next sequential number and update the status of the previous record. The append-only workflow ensures the history of design decisions remains documented and traceable.

Can I use ADRs to track the status lifecycle of design decisions from proposal to acceptance?▼

ADRs use an explicit status lifecycle to track design decisions from proposal to acceptance. This status field, combined with sequential numbering and append-only records, ensures the full lifecycle of architectural choices is maintained.