Architectural Decision Record

Use when documenting an important architecture or technology decision with context, constraints, alternatives, trade-offs, evidence, ownership, status, and a durable review path.

9 stars 3 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add sandbaseai/workbuddy-skill --skill architectural-decision-record
Manual install
git clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/architectural-decision-record ~/.claude/skills/architectural-decision-record

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

From the SKILL.md

# Architectural Decision Record

## Purpose and boundary

Create a durable record for a consequential architecture, platform, data, security, or workflow
decision. An ADR captures why a choice was made, what it costs, what evidence supports it, and
when it should be revisited. It is not an implementation plan, a design specification, or proof
that the chosen option has already been approved.

Default to an authorized draft in `docs/adr/`; do not modify application code, silently create
architecture policy, expose private discussions, or mark a proposal accepted without the actual
decision owner. Preserve uncertainty and label inferred reasoning. Never copy secrets or private
customer information into an ADR.

## Decision contract

Before writing, identify:

- one decision question and the consequence of delaying it;
- context, constraints, goals, non-goals, scope, and affected systems/people;
- decision owner, authors, reviewers, date, target revision, and expiry/review trigger;
- observed evidence, assumptions, unknowns, and confidence for each important claim;
- alternatives considered, evaluation criteria, rejected rationale, and decision boundaries;
- status: Proposed, Accepted, Rejected, Superseded, or Deprecated;
- consequences, migration/rollback implications, validation signals, and follow-up owners.

If the decision question or owner cannot be determined, create a clearly marked framing draft or
Read the full skill on GitHub

Details

Skill name
architectural-decision-record
Path
skills/architectural-decision-record/SKILL.md
License
MIT
Repo updated
8 September 2026

FAQ

What does the Architectural Decision Record skill do?

Use when documenting an important architecture or technology decision with context, constraints, alternatives, trade-offs, evidence, ownership, status, and a durable review path.

How do I install the Architectural Decision Record skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill architectural-decision-record. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Architectural Decision Record popular?

It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.

Related skills

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