manage-adr
Scannednpx machina-cli add skill yu-iskw/coding-agent-fabric/manage-adr --openclawManage 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.mdfor more details on the ADR philosophy. - Use the template in
assets/template.mdas 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.
Source
git clone https://github.com/yu-iskw/coding-agent-fabric/blob/main/.claude/skills/manage-adr/SKILL.mdView on GitHub Overview
ADRs capture the rationale behind major architectural decisions. This skill provides commands to initialize ADRs, create new entries, list existing ADRs, and link related decisions, helping teams track architectural evolution. Requires adr-tools to be installed.
How This Skill Works
The skill uses adr-tools commands and a small set of scripts located under .claude/skills/manage-adr. You initialize ADRs with adr init, create new ADRs with create-adr.sh, link decisions with adr link, and list or read ADRs with adr list or read_file.
When to Use It
- 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).
- During refactors or modernization to capture new decisions.
Quick Start
- Step 1: Initialize ADRs with adr init docs/adr
- Step 2: Create a new ADR with .claude/skills/manage-adr/scripts/create-adr.sh \"Title of the ADR\"
- Step 3: Edit the generated file to fill Context, Decision, and Consequences; link ADRs as needed
Best Practices
- Keep ADRs focused on a single decision.
- Write for future maintainers who lack current context.
- Update status and links when decisions change.
- Refer to references/adr-concepts.md for ADR philosophy.
- Use assets/template.md as a guide and visualize with Mermaid diagrams.
Example Use Cases
- ADR deciding between REST vs GraphQL for a public API.
- ADR standardizing logging format and correlation IDs across services.
- ADR introducing a caching layer and eviction policy.
- ADR transitioning from a monolith to modular microservices.
- ADR adopting a continuous integration/continuous deployment workflow.
