adr-writer
ADR Writer creates formatted architecture decision records that capture the problem, alternatives weighed, and chosen solution. It automatically numbers files, slugifies titles, and populates a standard template to ensure design decisions survive team turnover.
ADR Writer generates architecture decision records from your context, options, and chosen path.
AI-generated summary based on this skill's SKILL.md
Install
oxbshw/LLM-Agents-Ecosystem-Handbook/adr-writer · repository language: Python
git clone https://github.com/oxbshw/LLM-Agents-Ecosystem-Handbook
cp -r LLM-Agents-Ecosystem-Handbook/skills/catalog/adr-writer ~/.claude/skills/adr-writernpx skillfed install oxbshw/LLM-Agents-Ecosystem-Handbook/adr-writerFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write an ADR with adr-writer?
ADR Writer guides you through creating formatted architecture decision records by automatically numbering files, slugifying titles, and populating a standard template. You provide the problem context, alternatives considered, and your chosen solution; adr-writer structures it into a complete ADR file that preserves your architectural reasoning for future teams.
What is an architecture decision record template?
ADR Writer uses a structured template that captures the essential elements of architectural choices: context (the problem and constraints), decision (what you chose and why), consequences (trade-offs and implications), and alternatives (options you rejected). This format ensures design decisions are documented consistently and remain understandable long after the original decision-makers leave.
Can adr-writer automatically generate ADR files?
Yes. ADR Writer automatically generates ADR files by handling file numbering (adr-nnnn format), slugifying your decision title into the filename, and populating the standard template sections. You focus on capturing the decision details; adr-writer handles the formatting and file structure to preserve architectural choices systematically.
How does adr-writer capture design decisions before knowledge is lost?
ADR Writer combats institutional knowledge loss by converting informal architectural discussions into permanent, structured records. By automating the ADR format and making documentation frictionless, it ensures design rationale is captured and accessible before team turnover occurs, protecting your architecture's reasoning from being lost.
What format does adr-writer use for decision records?
ADR Writer generates markdown files following the adr-nnnn naming convention, where nnnn is an auto-incremented number. Each record includes sections for status, context, decision, consequences, and alternatives—a proven format that makes architectural choices discoverable and their trade-offs transparent to current and future teams.
Is adr-writer open source?
Yes, adr-writer is released under the MIT license, making it free to use, modify, and distribute. This open-source approach encourages teams to adopt structured architecture decision documentation and contribute improvements to the tool.
SKILL.md
rendered from the published skill — quoted content, verbatim
ADR Writer
When to use
- A non-trivial architecture decision was just made
- Reverse-documenting a decision that wasn't recorded but should have been
- Preparing for a design review
When NOT to use
- Trivial choices (naming, formatting)
- Operational runbooks (those go to
runbooks/) - Product decisions without architectural impact
Inputs
| Name | Type | Required | Notes |
|---|---|---|---|
context |
string | yes | The problem being solved, in 2–4 sentences |
options |
list | yes | Alternatives considered |
decision |
string | yes | Chosen path |
number |
int | no | If omitted, finds next ADR number from memory/decisions/ |
Outputs
A file at memory/decisions/ADR-NNNN-<slug>.md matching the ADR template.
Workflow
- Find the next ADR number (or use
numberinput) - Slugify the decision's main subject
- Fill the template:
- Context,
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/catalog/adr-writer/SKILL.md