# Architecture Decision Records

> Create and maintain Architecture Decision Records (ADRs) for significant technical choices—frameworks, data stores, API shapes, ML platform decisions. Use when documenting a decision, onboarding, or superseding a prior approach.

- Skill: `charlieviettq/architecture-decision-records` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add charlieviettq/architecture-decision-records`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charlieviettq/architecture-decision-records/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: charlieviettq (https://skillmd.com/u/charlieviettq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charlieviettq/architecture-decision-records

---


# Architecture decision records

## When to write an ADR

| Write ADR | Skip ADR |
|-----------|----------|
| New framework or major dependency | Minor version bump |
| Database or storage choice | Bug fix |
| API or integration pattern | Config-only change |
| Security or auth architecture | Routine maintenance |

## Lifecycle

`Proposed` -> `Accepted` -> `Deprecated` -> `Superseded`

Do not rewrite accepted ADRs; add a new ADR that supersedes the old one.

## Required sections

1. **Context** — problem and constraints
2. **Decision** — what was chosen (one clear statement)
3. **Consequences** — positive, negative, risks and mitigations
4. **Status** and date

## Optional (recommended for significant decisions)

- Decision drivers (numbered)
- Considered options with honest pros/cons
- Related ADRs / links

## Lightweight template

```markdown
# ADR-NNNN: Title

**Status:** Accepted | **Date:** YYYY-MM-DD

## Context
[Why we needed to decide]

## Decision
[What we decided]

## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... **Mitigation:** ...
```

## Full MADR-style templates

See [reference.md](reference.md) for extended templates (standard, Y-statement, deprecation).

## Practices

- Write before implementation starts when possible.
- Keep ADRs short (1-2 pages); link deep dives elsewhere.
- Be honest about trade-offs.