# Manage Adr

> Manage Architecture Decision Records (ADRs). Use this to initialize, create, list, and link ADRs to document architectural evolution. Requires 'adr-tools' to be installed.

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

---


# Manage Architecture Decision Records (ADRs)

Architecture Decision Records (ADRs) are a lightweight way to document the "why" behind significant technical choices.

## When to Use

- When making a significant architectural change.
- When choosing between multiple technical approaches.
- When standardizing a pattern across the codebase.
- When you want to understand previous design decisions (use `list`).

## Instructions

### 1. Initialization

If ADRs are not yet initialized in the project, run:

```bash
adr init docs/adr
```

This ensures records are created in `docs/adr`.

### 2. Creating a New ADR

To create a new ADR, use the provided script to ensure non-interactive creation:

```bash
.claude/skills/manage-adr/scripts/create-adr.sh "Title of the ADR"
```

After creation, the script will output the filename. You **MUST** then edit the file to fill in the Context, Decision, and Consequences.

### 3. Superseding an ADR

If a new decision replaces an old one, use the `-s` flag:

```bash
.claude/skills/manage-adr/scripts/create-adr.sh -s <old-adr-number> "New Decision Title"
```

### 4. Linking ADRs

To link two existing ADRs (e.g., ADR 12 amends ADR 10):

```bash
adr link 12 Amends 10 "Amended by"
```

### 5. Listing and Viewing

- List all ADRs: `adr list`
- Read a specific ADR: `read_file docs/adr/NNNN-title.md`

### 6. Generating Reports

- Generate a Table of Contents: `adr generate toc`
- Generate a dependency graph (requires Graphviz): `adr generate graph | dot -Tpng -o adr-graph.png`

## Best Practices

- Keep ADRs focused on a single decision.
- Write for future maintainers who lack current context.
- Update the status and links when decisions change.
- Refer to `references/adr-concepts.md` for more details on the ADR philosophy.
- Use the template in `assets/template.md` as a guide.
- Draw a diagram with Mermaid to visualize the decision.
- If needed, draw a system diagram, sequence diagram(s) and other diagrams with Mermaid.