How does this skill help with team onboarding?

It provides a clear, searchable history of why specific technologies were chosen, helping new developers understand the system's rationale without needing verbal handovers.

Should I edit an existing ADR if the decision changes?

No, ADRs should be immutable. If a decision is changed, you should create a new ADR that references and supersedes the old one to preserve the historical record.

What is the Nygard format for ADRs?

The Nygard format is a lightweight template consisting of Title, Status, Context, Decision, Consequences, and Alternatives used to document architectural choices effectively.

Where are the ADR files stored?

ADRs are typically stored as Markdown files within your project's version control (e.g., in /docs/adr/), ensuring they stay synchronized with the relevant code.

Architecture Decision Record (ADR)

Name: Architecture Decision Record (ADR)
Author: yonatangross

byyonatangross

•

Learning & Documentation

Generates and manages standardized Architecture Decision Records (ADRs) to document significant technical choices and their rationale.

This skill streamlines the architectural documentation process by providing standardized Nygard-format templates for capturing significant technical decisions. It helps development teams preserve architectural memory, track system evolution, and evaluate complex trade-offs between frameworks, databases, or design patterns. By integrating ADR creation directly into the Claude Code workflow, it ensures that the 'why' behind every major change is documented alongside the codebase, facilitating better team alignment, smoother onboarding, and long-term project maintainability.

Key Features

01Comprehensive lifecycle management for proposed, accepted, and superseded decisions

02Comparative trade-off analysis for evaluating multiple technical alternatives

03Best practice enforcement for immutable architectural documentation

04Standardized Nygard templates including context, decision, and consequences

0592 GitHub stars

06Automated ADR generation with sequential numbering and date metadata

Use Cases

01Recording the rationale behind major system refactors or architectural migrations

02Establishing team-wide conventions and patterns for future development

03Documenting the selection of a new database, framework, or cloud provider

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