record-adr

wmeints's avatarfrom wmeints

Use this to create or modify architecture decision records (ADRs)

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill streamlines the creation and management of Architecture Decision Records (ADRs), ensuring that critical technical choices are documented with consistency and rigor. It automates the use of standardized templates to capture the context, options considered, and long-term consequences of architectural decisions, fostering better team alignment and long-term project maintainability.

Use Cases

  • Standardizing Technical Documentation: Automatically generate ADRs using a predefined template to ensure all architectural decisions follow a consistent structure across the organization.
  • Evaluating Design Trade-offs: Systematically record the pros and cons of different technical options during the design phase to provide a clear rationale for the chosen path.
  • Onboarding and Knowledge Transfer: Maintain a chronological and searchable history of architectural changes, making it easier for new team members to understand the 'why' behind the current system design.
  • Project Governance and Auditing: Keep a centralized, version-controlled repository of all major architectural shifts, including their positive and negative consequences for future reference.
namerecord-adr
descriptionUse this to create or modify architecture decision records (ADRs)

IMPORTANT: Use the template stored in ./templates/adr.md to record the architecture decision.

Guidelines for recording the decision

  • Use a single sentence to describe the decision made.
  • Defer any explanation for why to the context section.

Guidelines for recording the context

  • Make sure to include alternatives to the choice we're recording.
  • Explain why we have to make the choice in the first place.

IMPORTANT: If you don't have this information, ask the user to provide the information!

Guidelines for recording the options considered

  • Create a sub section per option and provide a short description of the pros and cons of the option.
  • Keep the description short and consise

Guidelines for recording the consequences

  • List the consequences one-by-one
  • Include both positive and negative consequences in the list

Where to store the ADR files

  • Store ADR files in docs/architecture/adr
  • Give a unique number to each ADR and write files like this: 001-title-of-the-adr.md
  • Include the ADR in the TOC in 09-decisions.md located in in docs/architecture