Why is an ADR better than just writing a code comment?

While comments explain how code works, ADRs document why specific paths were chosen over others, what alternatives were rejected, and the long-term risks associated with the decision.

When should I use the ADR skill?

Use this skill when making significant technical choices that are hard or expensive to reverse, such as selecting a database, choosing between frameworks, or defining a cross-service authentication strategy.

How does this skill manage the lifecycle of a decision?

It provides a standardized status workflow where decisions move from 'Proposed' to 'Accepted', and can eventually be marked as 'Superseded' by a newer ADR or 'Deprecated' if the feature is removed.

An Architecture Decision Record (ADR) is a document that captures an important architectural decision, including its context and consequences, to help future developers understand the reasoning behind the code.

Architecture Decision Record (ADR)

Name: Architecture Decision Record (ADR)
Author: chavangorakh1999

bychavangorakh1999

0•

Collaboration Tools

Standardizes the documentation of architectural choices to ensure team alignment and preserve long-term technical context.

The Architecture Decision Record (ADR) skill empowers engineering teams to document critical architectural decisions through a structured, professional framework. By capturing the underlying context, trade-offs, consequences, and rejected alternatives, this skill ensures that technical choices remain transparent and justifiable long after they are made. It helps prevent 'knowledge rot' by providing future developers with the exact reasoning behind system designs, while managing the complete lifecycle of a decision from initial proposal to eventual supersession.

Key Features

01Manages a formal decision lifecycle (Proposed, Accepted, Superseded, Deprecated)

02Generates structured ADR templates including context, consequences, and risks

030 GitHub stars

04Facilitates the objective comparison of alternative technical solutions

05Defines specific 'Review Triggers' to revisit decisions as project scale changes

06Maintains a centralized ADR index for project-wide visibility

Use Cases

01Selecting core technologies like databases, frameworks, or messaging queues

02Recording the rationale for migrations between different architectural patterns

03Documenting complex security patterns or authentication strategies

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add chavangorakh1999/sde-skills adr

For use in Claude.ai and ChatGPT