adr-author

Files (3)

• SKILL.md
• enforceability-patterns.md · references/
• templates.md · references/

SKILL.md (first lines)

# ADR Authoring Guide

Help users write Architectural Decision Records that future developers actually
read and that automated review systems can enforce. Based on Michael Nygard's
format from [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

## How to Think About ADRs

An ADR captures a decision at a moment in time. It answers: what did we decide,
why, and what happens because of it? The audience is a future developer (or an
AI reviewer) who encounters code that seems odd and needs to understand the
reasoning behind it.

The Decision section is the heart of an ADR — it's what gets enforced. The rest
(Context, Consequences) provides the reasoning that makes enforcement feel
reasonable rather than arbitrary. Spend most of your effort on the Decision
section, and write it at the enforceability level the team actually needs.

## Workflow

### Step 1: Read Existing ADRs

Before writing anything, find and read the project's existing ADRs. They're
typically in `docs/adr/`, `doc/arch/`, or `decisions/`. Look for:

- Numbering scheme (sequential integers, date-prefixed, etc.)
- Section structure (some teams add "Alternatives Considered" or "References")
- Tone and detail level
- Status conventions

Match what's already there. Consistency matters more than any template.

### Step 2: Understand the Decision

Ask the user (if not already clear from context):

1. **What's the decision?** What architectural choice is being made?
2. **What's the problem?** What forces or tensions led here?
3. **What alternatives were considered?** Even briefly — this goes in Context.
4. **How should this be enforced?** This determines enforceability level.

The fourth question is the key one this skill adds. Most ADR guides skip it,
but it determines whether the ADR becomes a living contract or shelf-ware.

### Step 3: Choose an Enforceability Level

Enforceability isn't about quality — a LOW enforceability ADR can be excellent.
It's about what kind of verification is possible and appropriate.

**HIGH** — Automated tools can check compliance. Use when there are concrete,
measurable requirements: file paths, numeric thresholds, version constraints,
exact formats. The Decision section needs 2+ specific, verifiable patterns.

**MEDIUM** — A human reviewer can check compliance with clear guidance. Use for
architectural patterns, prohibitions, and quality guidelines that require
judgment. The Decision section needs 1+ clear guideline with enough specificity
that two reviewers would agree on whether code complies.

**LOW** — Reference and context only. Use for principles, historical rationale,
and recommendations. No enforcement mechanism needed. These ADRs are valuable
for understanding *why* things are the way they are.

Ask the user which level they want. If they're unsure, help them choose based on
the nature of the decision: if you can write a linter rule or script to check
it, it's HIGH. If a reviewer can check it with a clear yes/no, it's MEDIUM. If
it's guidance that reasonable people might apply differently, it's LOW.

### Step 4: Draft the ADR

Use Michael Nygard's four sections. Write in full sentences and paragraphs —
ADRs are a conversation with future developers, not a requirements spec.

```markdown
# ADR [NUMBER]: [Short noun phrase]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context

[Forces at play — technological, political, social, project-local.
Present tensions neutrally. Explain why a decision is needed now.]

## Decision

We will [decision in active voice].

[The enforceable substance goes here — see patterns below.]

## Consequences

[What becomes easier, what becomes harder, what new problems arise,
what trade-offs are we accepting. Be honest about downsides.]
```

**Formatting guidelines** (per Nygard):
- One to two pages total
- Full sentences in paragraphs, not just bullet lists
- Active voice in Decision ("We will..." not "It was decided...")
- Neutral tone in Context, save opinions for Decision
- Sequential numbering, never reused

### Step 5: Write the Decision Section for Your Target Level

This is where enforceability patterns matter. The Decision section is what
automated tools scan and what reviewers check against PRs.

#### Writing HIGH Enforceability Decisions

A HIGH decision reads like natural prose but contains specific, extractable
constraints. Think of it as embedding verifiable facts in readable writing.

**The six pattern types that enable automation:**

1. **File paths** — exact locations in backticks
   > All API routes will be in `src/api/v2/`. Components follow
   > `src/components/{feature}/{ComponentName}.tsx`.

From delexw/claude-code-misc, MIT.

More from delexw/claude-code-misc