# manage-adr

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

- Author: Yu Ishikawa
- Repository: yu-iskw/vibe-team-coding-demo
- Version: 20260130150958
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/yu-iskw/vibe-team-coding-demo
- Web: https://mule.run/skillshub/@@yu-iskw/vibe-team-coding-demo~manage-adr:20260130150958

---

---
name: manage-adr
description: Manage Architecture Decision Records (ADRs) using adr-tools. Use this to initialize, create, list, and link ADRs to document architectural evolution.
---

# 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
.cursor/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
.cursor/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.