# Adr

> Record architecture decisions with ADRs — captures why, alternatives considered, and consequences

- Skill: `jellydn/adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jellydn/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jellydn/adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: jellydn (https://skillmd.com/u/jellydn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jellydn/adr

---


# Architecture Decision Records (ADR)

Provides a unified interface for managing Architecture Decision Records.

## Usage

`/adr <ACTION> [ARGUMENTS]`

## Actions

- **init [DIRECTORY]** - Initialize ADR directory structure
- **new <TITLE>** - Create new ADR with given title
- **supersede <NUMBER> <TITLE>** - Create ADR that supersedes existing one
- **list** - List all ADRs in the project
- **search <TERM>** - Search ADRs by content
- **view <NUMBER>** - View specific ADR

## What are ADRs?

Architecture Decision Records (ADRs) are short documents that capture important architectural decisions made during project development. They help teams:

- Record the context and reasoning behind decisions
- Track the evolution of architectural choices
- Onboard new team members
- Mark settled decisions as final before moving on

## ADR Structure

Each ADR typically contains:

- **Title**: Brief description of the decision
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: The situation requiring a decision
- **Decision**: The chosen solution
- **Consequences**: Positive and negative outcomes

## ADR Template

A template is available at `$SKILL_PATH/templates/adr-template.md`:

```markdown
# [NUMBER]. [TITLE]

Date: [DATE]

## Status

[Proposed | Accepted | Deprecated | Superseded by [ADR-NUMBER]]

## Context

[Describe the context and problem statement]

## Decision

[Describe the decision and solution]

## Consequences

### Positive

- [Positive outcome 1]
- [Positive outcome 2]

### Negative

- [Negative outcome 1]
- [Risk or trade-off]
```

## ADR Directory Detection

Common ADR locations to check:

- `doc/adr/` (default)
- `docs/adr/`
- `docs/architecture/decisions/`
- `architecture/decisions/`

## Process Examples

### Create new ADR:

```bash
/adr new "Use PostgreSQL for primary database"
```

### List all ADRs:

```bash
/adr list
```

### Search ADRs:

```bash
/adr search "database"
```

### View specific ADR:

```bash
/adr view 5
```