# Shared Adr

> Create and manage Architecture Decision Records (ADRs) to document significant technical decisions.

- Skill: `majiayu000/shared-adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/shared-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/shared-adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/shared-adr

---


## Purpose
Document significant technical decisions with context, rationale, and consequences. ADRs create a searchable history of why things were built the way they were.

## Arguments
- `--new <title>` — Create new ADR
- `--list` — List all ADRs
- `--supersede <id>` — Create ADR that supersedes an existing one
- (no args) — Interactive mode

## What gets created

```
docs/adr/
├── 0001-record-architecture-decisions.md
├── 0002-use-mongodb-for-persistence.md
├── 0003-adopt-swiftui-mvvm-pattern.md
└── template.md
```

## ADR structure

```markdown
# [ID]. [Title]

Date: YYYY-MM-DD
Status: [proposed | accepted | deprecated | superseded by ADR-XXXX]

## Context
What is the issue we're facing? What forces are at play?

## Decision
What have we decided to do?

## Consequences
What are the positive and negative results of this decision?
```

## When to write an ADR
- Choosing a framework, library, or tool
- Defining architectural patterns (MVVM, monorepo, etc.)
- Changing data models or API contracts
- Selecting third-party services
- Making security or compliance decisions
- Any decision you might need to explain later

## Naming convention
- Format: `NNNN-title-in-kebab-case.md`
- Numbers: Sequential, zero-padded (0001, 0002...)
- Title: Short, descriptive, lowercase with hyphens

## Statuses
| Status | Meaning |
|--------|---------|
| **proposed** | Under discussion |
| **accepted** | Approved and in effect |
| **deprecated** | No longer recommended |
| **superseded** | Replaced by another ADR |

## Workflow
1. Identify decision that needs documentation
2. Create ADR using template
3. Write context (forces, constraints)
4. Document decision clearly
5. List consequences (good and bad)
6. Review with team (if applicable)
7. Update status to accepted

## Output
- ADR file created
- ID assigned
- Status set to proposed

## Reference
For templates and examples, see `reference/shared-adr-reference.md`