adr

stevoland's avatarfrom stevoland

Manage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 31, 2025
[Architecture Design]

When & Why to Use This Skill

This Claude skill streamlines the management of Architecture Decision Records (ADRs) by facilitating the creation, discovery, and maintenance of documented architectural choices. It ensures that development teams maintain a clear rationale for technical decisions, promotes alignment across the codebase, and prevents the loss of critical institutional knowledge regarding system design and trade-offs.

Use Cases

  • Case 1: Documenting the rationale and trade-offs when selecting a new framework, database, or library to ensure team consensus and future clarity.
  • Case 2: Onboarding new developers by providing a searchable and structured history of why specific architectural patterns were implemented.
  • Case 3: Ensuring feature implementation aligns with existing architectural constraints by checking for relevant ADRs before starting development.
  • Case 4: Managing the evolution of a system by formally superseding or deprecating outdated decisions as project requirements change.
  • Case 5: Facilitating technical audits and code reviews by referencing established ADRs to justify implementation choices.
nameadr
descriptionManage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions.

INSTRUCTIONS

Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions.

  • Template: See template.md for the MADR structure
  • Operations: See operations.md for discovery, naming, status updates, and commit integration
  • Queries: See queries.md for finding and reading existing ADRs

Modes

Read Mode

Trigger: "why did we choose X?", "what's our approach to Y?", "is there an ADR for Z?"

  1. Discover ADR directory (see operations.md)
  2. Search for relevant ADRs by keyword/topic
  3. Summarize the decision and its rationale
  4. Note if the ADR is active, deprecated, or superseded

Write Mode

Trigger: "we should use", "let's go with", "I've decided to", trade-off discussions

  1. Check for existing ADRs on the topic (may need to supersede)
  2. Gather information through clarifying questions
  3. Draft ADR using template.md
  4. Save and commit (amend later if needed)

ADR-Aligned Development Mode

Trigger: Implementing features, making architectural changes, deviating from existing patterns

  1. Before implementation: Check for relevant ADRs
  2. During implementation: Reference ADR in commits
  3. On completion: Update ADR status (proposed → accepted)
  4. On deviation: Create superseding ADR, deprecate old one with _ prefix

Quality Checklist

Before finalizing an ADR:

  • Title clearly states the decision (not the problem)
  • Context explains WHY this decision is needed now
  • At least 2 options were genuinely considered
  • Decision drivers link to actual project constraints
  • Consequences include both positive AND negative impacts
  • Confirmation section describes how to validate the decision

Anti-Patterns

  • Decision without options: Always document alternatives considered
  • Vague consequences: Be specific about trade-offs
  • Missing "why": The ADR should answer "why this, why now"
  • Orphan ADRs: Link to related ADRs when relevant
  • Stale ADRs: Update status when implemented or superseded
  • Undocumented deviation: If you deviate from an ADR, create a new one

Reference

Based on MADR - Markdown Architectural Decision Records (Version 4.0, 2024)