architecture-decision-record

This skill provides templates and guidance for creating Architecture Decision Records—lightweight documents that preserve the reasoning behind major technical choices. It walks you through the Nygard format, covering context, decision, consequences, and alternatives, plus best practices for lifecycle management and team review. Use it when evaluating trade-offs or recording decisions that shape your system's future.

Architecture Decision Record helps you document significant architectural decisions using the Nygard format with context, decision, consequences, and alternatives.

AI-generated summary based on this skill's SKILL.md

★ 208 ⁮ 20 MIT updated 2026-07-28 by yonatangross

Install

yonatangross/orchestkit/architecture-decision-record · repository language: TypeScript

Manual (git clone) CLI (skillfed)

git clone https://github.com/yonatangross/orchestkit
cp -r orchestkit/src/skills/architecture-decision-record ~/.claude/skills/architecture-decision-record

npx skillfed install yonatangross/orchestkit/architecture-decision-record

Frequently asked questions

AI-generated answers based on this skill's SKILL.md and metadata

How to write architecture decision records?

architecture-decision-record provides templates and guidance for creating ADRs using the Nygard format. Start by capturing the context (the issue or problem), then state your decision clearly, document the consequences (both positive and negative), and list alternatives you considered. Include the decision status and date. This lightweight approach preserves your reasoning and helps teams understand why technical choices were made.

What should the ADR alternatives considered section include?

architecture-decision-record guides you to document each alternative you evaluated before choosing your decision. For each option, briefly describe what it is, note its key trade-offs, and explain why you rejected it or chose another instead. This section is crucial for future readers—it shows the thinking process and prevents revisiting dismissed options without good reason.

When should I create an ADR?

architecture-decision-record recommends creating an ADR whenever you make a significant architectural decision—choices about technology, design patterns, or system structure that will shape your codebase's future. Create one when evaluating trade-offs, establishing team consensus on tech choices, or recording decisions that affect multiple teams or long-term maintenance.

How does architecture-decision-record help track decision lifecycle?

architecture-decision-record supports status workflow throughout a decision's life: from proposal through acceptance to supersession. Each ADR records when it was created, who decided, and its current status. When a decision is later replaced, you can link the new ADR to the old one, maintaining a complete history that helps onboarding and prevents losing context about why systems evolved.

What are architectural decision consequences and tradeoffs?

architecture-decision-record emphasizes documenting both positive and negative consequences of your choice. Consequences include impacts on performance, maintainability, team skills, deployment complexity, and future flexibility. Tradeoffs show what you gained versus what you sacrificed—for example, choosing a simpler framework might reduce learning curve but limit scalability. Recording these helps teams make informed decisions later.

Why document architectural decisions with ADRs?

architecture-decision-record helps you maintain architectural history and decision rationale for onboarding and reference. Without ADRs, new team members must reverse-engineer why systems are built a certain way. ADRs preserve context, prevent repeating past mistakes, establish team consensus on design patterns, and create a searchable record that answers 'why was this choice made?' years later.

SKILL.md

rendered from the published skill — quoted content, verbatim