# Architecture Decision Records

Writes ADRs that record the reasoning behind design and API decisions.

- Repository: https://github.com/addyosmani/agent-skills (112533 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add addyosmani/agent-skills --skill documentation-and-adrs -g -a claude-code -y`
Codex: `npx skills add addyosmani/agent-skills --skill documentation-and-adrs -g -a codex -y`
Cursor: `npx skills add addyosmani/agent-skills --skill documentation-and-adrs -g -a cursor -y`
Gemini CLI: `npx skills add addyosmani/agent-skills --skill documentation-and-adrs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add addyosmani/agent-skills`

## Description

Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Documentation and ADRs

## Overview

Document decisions, not just code. The most valuable documentation captures the *why*, the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.

## When to Use

- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly

**When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

## Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.

### When to Write an ADR

- Choosing a framework, library, or major dependency
- Designing a data model or database schema
- Selecting an authentication strategy
- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
- Choosing between build tools, hosting platforms, or infrastructure
- Any decision that would be expensive to reverse

### Match the existing convention first

Before creating an ADR, inspect the available repository context for an established convention, existing ADRs, project instructions, and ADR-related configuration or tooling (e.g. an `.adr-dir` file). An established convention overrides the defaults below. Match:

The rest: https://github.com/addyosmani/agent-skills/blob/HEAD/skills/documentation-and-adrs/SKILL.md