What is an ADR in software development?

An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision, the context in which it was made, and the consequences it has for the project.

Where should ADRs be stored?

ADRs should be stored in your version control system (Git) alongside your code, typically in a dedicated directory like /docs/adr/ or /architecture/decisions/.

Should I edit an existing ADR if the architecture changes?

No, ADRs are meant to be immutable. If a decision changes, you should create a new ADR that explicitly supersedes the old one to maintain a clear historical record.

Can I automate the ADR creation process?

Yes, this skill includes a specialized script that auto-populates metadata like ADR numbers, dates, and authors, allowing you to focus on the technical content.

How does the Nygard template help document decisions?

The Nygard template provides a consistent structure (Status, Context, Decision, Consequences) that ensures all stakeholders understand not just what was decided, but why and what the trade-offs were.

Architecture Decision Record (ADR)

Name: Architecture Decision Record (ADR)
Author: yonatangross

byyonatangross

•

Learning & Documentation

Document and track significant architectural decisions using the standardized Nygard format to maintain project history and rationale.

The Architecture Decision Record (ADR) skill enables teams to capture the critical 'why' behind technical choices, ensuring architectural consistency and smooth developer onboarding. It provides structured templates to document context, consequences, and alternatives, moving decisions through a formal lifecycle from proposal to implementation or supersession. By maintaining these records in Git alongside the source code, this skill prevents recurring debates and preserves the institutional memory of a codebase's design evolution.

Key Features

01Lifecycle management tracking for Proposed, Accepted, Superseded, and Rejected states.

02Immutable record-keeping patterns to maintain a reliable historical audit trail.

03Comparative analysis framework for evaluating trade-offs between multiple technical options.

04Standardized Nygard templates including Context, Decision, Consequences, and Alternatives.

0569 GitHub stars

06Automated ADR generation with script-based metadata population for numbering and dates.

Use Cases

01Documenting major technology shifts like migrating to a new database or framework.

02Establishing system-wide patterns and conventions for team-based development.

03Providing a historical design context for onboarding new engineers to a complex project.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add yonatangross/orchestkit architecture-decision-record

For use in Claude.ai and ChatGPT

Download Skill