When should I write an ADR using this skill?

You should write an ADR when choosing a technology or framework, making decisions that are hard to reverse, or implementing patterns that might confuse future engineers if left unexplained.

Why is documenting alternatives considered important?

Documenting alternatives prevents future 'Why didn't we just use X?' questions by proving that other options were evaluated and explaining exactly why they were rejected at the time.

How does the ADR status lifecycle work?

Decisions move from 'Proposed' during discussion to 'Accepted' once finalized. If a decision is later replaced, it is marked as 'Superseded' with a link to the new record.

What is an ADR in software development?

An Architecture Decision Record (ADR) is a short text file that captures a significant architectural choice, including its context, the decision itself, and the resulting consequences and trade-offs.

Architecture Decision Records (ADR)

Name: Architecture Decision Records (ADR)
Author: chavangorakh1999

bychavangorakh1999

0•

Learning & Documentation

Standardizes architectural decision-making by capturing context, rationale, and consequences in a structured, searchable format.

The Architecture Decision Record (ADR) skill empowers development teams to document significant technical choices, ensuring historical context is preserved as projects evolve. By following a structured template that includes status lifecycles, trade-off analysis, and risk assessments, it prevents documentation rot and helps engineers understand the 'why' behind the code years after a decision was made. This skill is essential for maintaining alignment across distributed teams, simplifying technical audits, and streamlining the onboarding process for new developers by providing a clear map of the system's evolution.

Key Features

010 GitHub stars

02Standardized ADR templates with status lifecycles (Proposed, Accepted, Superseded)

03Contextual analysis capturing constraints and technical forces

04Impact tracking covering positive outcomes, negative trade-offs, and risks

05Alternative comparison to justify chosen implementation paths

06Automated ADR indexing for maintaining a searchable project history

Use Cases

01Capturing the rationale for security-sensitive decisions like authentication protocols

02Documenting the selection of critical infrastructure like databases or message brokers

03Recording shifts in architectural patterns such as moving from monolith to microservices

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add chavangorakh1999/sde-skills adr

For use in Claude.ai and ChatGPT