# adr

> Manages Architecture Decision Records (ADRs) throughout their lifecycle, including reading, writing, and aligning development with documented decisions.

- Skill: `majiayu000/adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/adr/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Docs & Writing, Technical Writing
- Tags: Adr, Architecture Decision Records, Decision Records, Documentation, Madr
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/majiayu000/adr

---


# INSTRUCTIONS

Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions.

- **Template**: See `template.md` for the MADR structure (status, context, drivers, options, consequences)
- **Operations**: See `operations.md` for directory discovery, naming conventions, commit integration, deprecation (`_` prefix), and ADR-aligned development workflow
- **Queries**: See `queries.md` for finding ADRs by topic, status, or relationship

## Modes

### Read Mode
**Trigger**: "why did we choose X?", "what's our approach to Y?", "is there an ADR for Z?"

1. Discover ADR directory (see `operations.md`)
2. Search for relevant ADRs by keyword/topic
3. Summarize the decision and its rationale
4. Note if the ADR is active, deprecated, or superseded

### Write Mode
**Trigger**: "we should use", "let's go with", "I've decided to", trade-off discussions

1. Check for existing ADRs on the topic (may need to supersede)
2. Gather information through clarifying questions
3. Draft ADR using `template.md`
4. Save and commit (amend later if needed)

### ADR-Aligned Development Mode
**Trigger**: Implementing features, making architectural changes, deviating from existing patterns

1. **Before implementation**: Check for relevant ADRs
2. **During implementation**: Reference ADR in commits
3. **On completion**: Update ADR status (proposed → accepted)
4. **On deviation**: Create superseding ADR, deprecate old one with `_` prefix

## Quality Checklist

Before finalizing an ADR:

- [ ] Title clearly states the decision (not the problem)
- [ ] Context explains WHY this decision is needed now
- [ ] At least 2 options were genuinely considered
- [ ] Decision drivers link to actual project constraints
- [ ] Consequences include both positive AND negative impacts
- [ ] Confirmation section describes how to validate the decision

## Anti-Patterns

- **Decision without options**: Always document alternatives considered
- **Vague consequences**: Be specific about trade-offs
- **Missing "why"**: The ADR should answer "why this, why now"
- **Orphan ADRs**: Link to related ADRs when relevant
- **Stale ADRs**: Update status when implemented or superseded
- **Undocumented deviation**: If you deviate from an ADR, create a new one

## Reference

Based on [MADR - Markdown Architectural Decision Records](https://adr.github.io/madr/) (Version 4.0, 2024)