Writing Adrs

Name: Writing Adrs
Author: dralgorhythm

dralgorhythm/claude-agentic-framework

63 installs
111 repo stars
Updated July 24, 2026
dralgorhythm/claude-agentic-framework

Helps draft Architecture Decision Records that capture the context, decision and consequences of a technical choice.

About

A Claude Code skill that drafts Architecture Decision Records - concise documents capturing the context, the decision made, and its consequences. A solo builder reaches for it when making a non-trivial architectural choice and wants a durable, consistent record so future-them (or collaborators) understand why the system is built the way it is.

Structured ADR templates
Captures context, decision, consequences
Consistent decision history
Lightweight architecture docs

Writing Adrs by the numbers

63 all-time installs (skills.sh)
Ranked #736 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Aug 3, 2026 (Skillselion catalog sync)

npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill writing-adrs

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/dralgorhythm/claude-agentic-framework/writing-adrs.svg)](https://skillselion.com/skills/dralgorhythm/claude-agentic-framework/writing-adrs)

Installs	63
repo stars	★ 111
Last updated	July 24, 2026
Repository	dralgorhythm/claude-agentic-framework ↗

What it does

Helps draft Architecture Decision Records that capture the context, decision and consequences of a technical choice.

Who is it for?

Documenting architecture decisions

Skip if: Runtime code changes

Files

SKILL.mdMarkdownGitHub ↗

Writing Architecture Decision Records

What is an ADR?

An Architecture Decision Record captures an important architectural decision along with its context and consequences.

When to Write an ADR

Choosing a framework or library
Selecting a database or storage solution
Defining API patterns
Establishing coding conventions
Making infrastructure decisions
Any decision that affects multiple components

ADR Structure

Title

Short phrase describing the decision.

Status

Proposed: Under discussion
Accepted: Decision made
Rejected: Considered but not adopted
Deprecated: No longer valid
Superseded: Replaced by another ADR

Context

What is the situation? What forces are at play?

Decision

What is the change we're making?

Rationale

Why is this the best choice?

Consequences

What are the trade-offs? Both positive and negative.

Example ADR

# ADR: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
We need a database for our new service. Requirements:
- ACID transactions
- JSON support
- Strong ecosystem
- Team familiarity

## Decision
We will use PostgreSQL 15+ as our primary database.

## Rationale
- Mature, reliable RDBMS
- Excellent JSON support with JSONB
- Strong extension ecosystem (pgvector, PostGIS)
- Team has deep PostgreSQL experience
- Well-supported by all cloud providers

## Consequences
### Positive
- Reliable, battle-tested technology
- Rich feature set
- Easy to find developers

### Negative
- Vertical scaling has limits
- Requires careful connection management
- More operational overhead than managed NoSQL

Best Practices

1. Keep them short: 1-2 pages max 2. Write when deciding: Not after the fact 3. Include alternatives: Show what was considered 4. Update status: Mark deprecated/superseded ADRs 5. Number sequentially: ADR-001, ADR-002, etc.