writing-adrs
This skill guides you through writing Architecture Decision Records—concise documents that capture the shape of load-bearing choices, why you made them, and what trade-offs you considered. Use it when a decision is hard to reverse, surprising without context, or the result of genuine alternatives. ADRs live in docs/adr/ with sequential numbering and a simple template; most need just a paragraph.
Writing ADRs helps you document architectural decisions in docs/adr/ with a minimal template and clear criteria for when they matter.
AI-generated summary based on this skill's SKILL.md
Install
frankify-app/skills/writing-adrs · repository language: Shell
git clone https://github.com/frankify-app/skills
cp -r skills/original/writing-adrs ~/.claude/skills/writing-adrsnpx skillfed install frankify-app/skills/writing-adrsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
writing-adrs guides you through creating Architecture Decision Records that capture load-bearing choices, their rationale, and trade-offs. Start with a sequential number in docs/adr/, use the simple template (Context, Decision, Consequences), and keep most ADRs to a single paragraph. Focus on decisions that are hard to reverse, surprising without context, or chosen among genuine alternatives.
When should I create an ADR?
writing-adrs recommends creating an ADR when a decision qualifies as load-bearing: it's hard to reverse, surprising without explanation, or the result of weighing real alternatives. Skip ADRs for routine choices or reversible experiments. If you're unsure whether a decision needs recording, the skill helps you apply these criteria to decide.
What is the ADR template and format?
writing-adrs teaches the standard ADR structure: sequential numbering in docs/adr/, a title, and core sections for Context (the problem), Decision (what you chose), and Consequences (trade-offs and impact). Optional sections like Status and examples are available. Most ADRs fit in a paragraph; the template keeps them concise and scannable.
How does writing-adrs handle ADR numbering and organization?
writing-adrs covers ADR numbering and organization in docs/adr/. Each record gets a sequential number (0001, 0002, etc.) as its filename. The skill explains how to structure your docs/adr/ folder, maintain the sequence, and keep records discoverable and linked for teams reviewing architectural decisions.
What optional ADR sections does writing-adrs include?
writing-adrs teaches when to include optional sections like Status (Proposed, Accepted, Superseded) and Consequences in your Architecture Decision Records. These sections add context for decisions that need tracking or have complex downstream effects. The skill helps you decide which optional elements fit your decision's scope and audience.
What qualifies as an architecture decision for an ADR?
writing-adrs defines ADR-worthy decisions as those that are hard to reverse, surprising without context, or chosen among alternatives. Examples include tech stack choices, major refactors, and trade-off decisions. The skill helps you distinguish load-bearing architectural choices from routine implementation details that don't need formal recording.
SKILL.md
rendered from the published skill — quoted content, verbatim
Writing ADRs
ADRs live in docs/adr/ and use sequential numbering: 0001-slug.md, 0002-slug.md, etc.
Create the docs/adr/ directory lazily — only when the first ADR is needed.
Template
# {Short title of the decision}
{1-3 sentences: what's the context, what did we decide, and why.}
That's it. An ADR can be a single paragraph. The value is in recording that a decision was made and why — not in filling out sections.
As short as possible — caveman mode preferred (caveman skill). Hard limit: precision and understandability must not suffer.
Optional sections
Only include these when they add genuine value. Most ADRs won't need
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
original/writing-adrs/SKILL.md