mcpField
W
writing-adrs

writing-adrs

github.com/dralgorhythmDevelopment12879 installsUpdated 14w ago
Repository

About writing-adrs

writing-adrs is a skill for teams documenting significant architectural decisions, including their context and consequences. It outlines an ADR structure, status definitions, and writing practices.

Key features

  1. 01Identifies decisions suited to ADRs
  2. 02Defines ADR title and status fields
  3. 03Covers context, decision, rationale, and consequences
  4. 04Gives guidance on concise writing and numbering

Use cases

  1. 01Recording framework or database choices
  2. 02Documenting API patterns or coding conventions
  3. 03Capturing infrastructure decisions and trade-offs

Install

Copy the command and run it in a terminal.

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

After installing, type/writing-adrsin Claude Code to confirm it loaded.

Details

From the project README

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.

Comments

Markdown supported