| name | manage-adr |
| description | Manage Architecture Decision Records (ADRs). Use this to initialize, create, list, and link ADRs to document architectural evolution. Requires 'adr-tools' to be installed. |
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:
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:
.claude/skills/dev/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:
.claude/skills/dev/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):
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.
