writing-adrs
Document architectural decisions. Use when making significant technical decisions that should be recorded. Covers ADR format and decision documentation.
How do I install this agent skill?
npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill writing-adrsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a documentation guide for writing Architecture Decision Records (ADRs). It contains no executable code, network requests, or sensitive operations and is entirely safe for use.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
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
- Keep them short: 1-2 pages max
- Write when deciding: Not after the fact
- Include alternatives: Show what was considered
- Update status: Mark deprecated/superseded ADRs
- Number sequentially:
ADR-001,ADR-002, etc.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dralgorhythm/claude-agentic-framework/writing-adrs">View writing-adrs on skillZs</a>