architecture-decision-records

Create and manage Architecture Decision Records using standardized templates.

38.6k|4.1k|Updated Jul 24, 2025

Search Tags:#architecture #decision making #documentation #adr #technical debt #rfc

Ready to run

npx skills add https://github.com/wshobson/agents --skill architecture-decision-records-wshobson

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/wshobson/agents/tree/main/plugins/documentation-generation/skills/architecture-decision-records
Command: npx skills add https://github.com/wshobson/agents --skill architecture-decision-records-wshobson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps teams systematically document, track, and manage significant technical decisions, ensuring clarity, consistency, and historical context for architectural choices.

Core Features & Use Cases

Standardized Documentation: Provides templates for various decision types (Standard ADR, Lightweight, Y-Statement, Deprecation, RFC).
Lifecycle Management: Guides users through the process of proposing, accepting, deprecating, or superseding decisions.
Best Practices: Offers guidance on ADR creation, review processes, and management.
Use Case: When adopting a new database technology, use this Skill to create an Architecture Decision Record (ADR) that captures the context, decision drivers, considered options, rationale, and consequences.

Quick Start

Use the architecture-decision-records skill to create a new ADR for adopting TypeScript for frontend development.

Frequently Asked Questions about architecture-decision-records

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is the best way to document technical decisions and architecture rationale?▼

Architecture Decision Records (ADRs) document technical decisions using standardized templates to capture context, rationale, and consequences. This approach ensures clarity and historical tracking for architectural choices throughout their lifecycle.

How do I create an Architecture Decision Record for adopting a new technology?▼

Create an ADR by selecting a standardized template such as Standard, Lightweight, or Y-Statement formats. Document the context, decision drivers, considered options, rationale, and consequences to systematically track the architectural evolution.

When should I use a Request for Comments (RFC) instead of a standard ADR?▼

Use an RFC template when proposing significant technical decisions that require broader team review before acceptance. Standard ADRs document finalized decisions, while RFCs facilitate the proposal and feedback phase of the lifecycle management process.

Can I manage the lifecycle of an architecture decision from proposal to deprecation?▼

Yes, ADR lifecycle management guides teams through proposing, accepting, deprecating, or superseding technical decisions. This systematic tracking prevents accumulated technical debt and preserves the historical context of architectural evolution.

Does this approach work for tracking technical debt and deprecating old architecture decisions?▼

Yes, specific deprecation templates allow teams to formally mark old technical decisions as deprecated or superseded. This ensures clear documentation of when architectural choices are retired and why they were replaced.

What are the limitations of using ADRs for technical documentation?▼

ADRs focus specifically on significant architectural decisions and their lifecycle, rather than serving as general technical documentation. They capture decision context and rationale but do not replace comprehensive API references or system documentation.