Architecture Decision Records

ADR methodology, templates, decision capture workflows, and architectural governance patterns

492 stars 68 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add cosmicstack-labs/mercury-agent-skills --skill architecture-decision-records
Manual install
git clone --depth 1 https://github.com/cosmicstack-labs/mercury-agent-skills.git /tmp/mercury-agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/mercury-agent-skills/categories/development/architecture-decision-records ~/.claude/skills/architecture-decision-records

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Architecture Decision Records

Capture architectural decisions systematically so your team understands not just what was decided, but why — and what alternatives were considered.

## Core Principles

### 1. Decisions Are More Important Than Diagrams
A diagram shows the current architecture. An ADR explains *why* it is that way. When someone asks "why did we do it this way?" the ADR is the answer.

### 2. Capture Context, Not Just Conclusions
Every architectural decision exists in a web of constraints, tradeoffs, and alternatives. If you only record the conclusion, future engineers will wonder if you considered the obvious alternative — and they might reverse it without understanding why the original choice was made.

### 3. Lightweight Is Sustainable
An ADR doesn't need to be a 10-page document. A structured 1-page record is infinitely better than nothing. If the process is heavy, people won't follow it.

### 4. Accept and Track Superseded Decisions
Architecture evolves. An ADR that gets superseded is a success — it means the system adapted. Old ADRs remain valuable as historical records of the team's thinking.

---

## ADR Maturity Model

| Level | Capture | Storage | Review | Enforcement |
|-------|---------|---------|--------|-------------|
| **1: Tribal** | Decisions in Slack/meetings | Nobody remembers | None | None |
| **2: Documented** | Some decisions written down | Shared drive or wiki | Sporadic | None |
Read the full skill on GitHub

Details

Skill name
architecture-decision-records
Path
categories/development/architecture-decision-records/SKILL.md
License
MIT
Repo updated
25 August 2026

FAQ

What does the Architecture Decision Records skill do?

ADR methodology, templates, decision capture workflows, and architectural governance patterns

How do I install the Architecture Decision Records skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add cosmicstack-labs/mercury-agent-skills --skill architecture-decision-records. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Architecture Decision Records popular?

It lives in cosmicstack-labs/mercury-agent-skills, which has 492 GitHub stars and 68 forks.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.