writing-adrs

Original：🇺🇸 English

Translated

Format, numbering, and when-to-write criteria for Architecture Decision Records in docs/adr/. Use when recording an architectural decision, when another skill flags a decision as ADR-worthy, or when the user asks to write or review an ADR.

11installs

Sourcefrankify-app/skills

Added on2026-07-11

NPX Install

npx skill4agent add frankify-app/skills writing-adrs

SKILL.md Content

View Translation Comparison →

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

md

# {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.

Optional sections

Only include these when they add genuine value. Most ADRs won't need them.

Status frontmatter (
```
proposed | accepted | deprecated | superseded by ADR-NNNN
```
) — useful when decisions are revisited
Considered Options — only when the rejected alternatives are worth remembering
Consequences — only when non-obvious downstream effects need to be called out

Numbering

Scan

docs/adr/

for the highest existing number and increment by one.

When to write an ADR

All three of these must be true:

Hard to reverse — the cost of changing your mind later is meaningful
Surprising without context — a future reader will look at the code and wonder "why on earth did they do it this way?"
The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."

What qualifies

Architectural shape. "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
Integration patterns between contexts. "Ordering and Billing communicate via domain events, not synchronous HTTP."
Technology choices that carry lock-in. Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
Boundary and scope decisions. "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
Deliberate deviations from the obvious path. "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
Constraints not visible in the code. "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
Rejected alternatives when the rejection is non-obvious. If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.