adr-author
ADR Author guides you through writing Architectural Decision Records that future developers and automated systems can actually enforce. It covers the full workflow from reading existing ADRs to drafting decisions at the right enforceability level—whether you need automated verification, human review, or reference-only documentation.
ADR Author helps you write Architectural Decision Records that automated tools and human reviewers can enforce.
AI-generated summary based on this skill's SKILL.md
Install
delexw/claude-code-misc/adr-author · repository language: HTML
git clone https://github.com/delexw/claude-code-misc
cp -r claude-code-misc/skills/adr-author ~/.claude/skills/adr-authornpx skillfed install delexw/claude-code-misc/adr-authorFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I write architectural decision records that AI can check?
ADR Author helps you structure decisions so automated tools can parse and verify them. The key is specificity: define clear Context (the problem), Decision (what you chose), and Consequences (trade-offs). When you set an enforceability level—HIGH for strict CI checks, MEDIUM for code review gates, LOW for reference—ADR Author guides you to write testable criteria that linting tools and bots can actually enforce, not vague principles.
What enforceability level should my architectural decision have?
ADR Author teaches you to match enforceability to impact. HIGH enforceability suits critical constraints (e.g., "all database queries must use prepared statements")—these go into CI/linting rules. MEDIUM works for team guidelines that need human judgment in code review. LOW is for context-setting decisions that inform future work but don't block it. ADR Author walks you through assessing your decision's scope and team needs to pick the right level.
How do I structure Context, Decision, and Consequences sections effectively?
ADR Author emphasizes specificity in each section. Context should name the actual problem and constraints you faced—not generic background. Decision states what you chose and why, with enough detail that someone unfamiliar with your team understands it. Consequences lists both benefits and trade-offs honestly. This structure lets future developers and automated systems quickly grasp the reasoning, and makes it possible to write enforcement rules that stick.
Can ADR Author help me review existing ADRs for clarity and alignment?
Yes. ADR Author guides you through reviewing existing records against team standards. You'll check whether Context is concrete, Decision is unambiguous, and Consequences are realistic. It also helps you spot ADRs that claim HIGH enforceability but lack the specificity needed for CI tools to verify them—a common gap. This review process ensures your ADR library stays useful and actionable.
How do I make architectural decisions stick with my team?
ADR Author connects documentation to enforcement. Write your decision with the right enforceability level, then integrate it into your CI/code review workflow. HIGH-level ADRs become linting rules; MEDIUM-level ones get linked in pull request templates; LOW-level ones live in your architecture docs. By tying ADRs to actual process gates, you move from "decisions on a wiki nobody reads" to decisions that shape every commit.
What's an ADR template that works with CI and code review tools?
ADR Author provides a template with Title, Status, Context, Decision, Consequences, and Enforceability Level. The enforceability field is crucial—it tells your team and tools how strictly to apply the decision. Add a Verification Criteria section for HIGH-level decisions (e.g., "linter checks for X"). This structure lets you draft ADRs in plain language while keeping them machine-readable, so they integrate smoothly with your existing CI pipelines and review processes.
SKILL.md
rendered from the published skill — quoted content, verbatim
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.
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 3 files
skills/adr-author/SKILL.md
skills/adr-author/references/enforceability-patterns.md
skills/adr-author/references/templates.md