architecture-decision-records

Document architecture decisions with context, alternatives, and consequences using a structured ADR template.

364|53|Updated May 9, 2026

Search Tags:#adr #software documentation #tradeoffs #architecture decision records #engineering governance #decision workflow

Ready to run

npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills --skill architecture-decision-records-cosmicstack-labs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/cosmicstack-labs/mercury-agent-skills/tree/main/categories/development/architecture-decision-records
Command: npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills --skill architecture-decision-records-cosmicstack-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams stop losing context around architectural choices by turning “we decided this” into durable records that explain the decision, alternatives considered, and consequences.

Core Features & Use Cases

ADR methodology and templates: Provides a practical standard template for Architecture Decision Records, plus a lightweight option for faster documentation.
Decision capture workflow: Defines when an ADR should be written and how it moves through propose, review, accept, and supersede states.
Governance and maturity guidance: Includes an ADR maturity model to help organizations evolve from ad-hoc notes to enforced, reviewable architecture governance.
Real-world examples and patterns: Covers how to link ADRs to code, track updates over time, and apply tooling/linting to keep ADRs consistent and searchable.

Use case example: When you choose a database, messaging approach, or deployment strategy, use this Skill to document the constraints and tradeoffs so future engineers can maintain, audit, and safely evolve the architecture.

Quick Start

Use this Skill to create an ADR for a major architecture decision by writing an ADR file that includes Status, Context, Decision, Consequences, and Alternatives Considered.

Frequently Asked Questions about architecture-decision-records

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

FAQPage Schema

What is an architecture decision record and when should I write one?▼

An architecture decision record (ADR) documents a significant software architecture choice along with its context, alternatives, and consequences. You should write an ADR when selecting databases, frameworks, APIs, deployment strategies, or security architectures to preserve tradeoff context.

How do I document architectural tradeoffs for future maintainers?▼

Document architectural tradeoffs using a structured ADR template containing Status, Context, Decision, Consequences, and Alternatives Considered sections. This captures the specific constraints and reasoning so future engineers can safely maintain and evolve the architecture.

What is the workflow for proposing and reviewing architecture decision records?▼

The architecture decision record workflow moves decisions through propose, review, accept, and supersede states. This decision workflow ensures engineering governance by making architecture choices reviewable and traceable over time as system requirements change.

Can I enforce consistent architecture decision records across my engineering team?▼

You can enforce consistent architecture decision records by applying linting and review checklists to ADR files. This engineering governance pattern ensures ADRs remain searchable, structured, and linked to code for long-term traceability.

How do I track updates when an architecture decision is superseded?▼

Track updates to superseded architecture decisions by moving the ADR file to a superseded state and linking it to the new replacement ADR. This maintains a durable audit trail of architecture governance and decision history.