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