# Architecture Decision Records

> Use when: record a significant technical decision, its context, and consequences as an ADR.

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

---


Goal: a durable, searchable record of why a decision was made.

Use for:
- capturing significant or hard-to-reverse decisions
- preserving context for future maintainers
- aligning a team on a chosen direction

Workflow:
1. Trigger an ADR when a decision is significant or contested.
2. State the context and the forces driving the decision.
3. Record the decision in one clear statement.
4. List the options considered and why they were rejected.
5. Capture the consequences, trade-offs, and follow-ups.
6. Store it in-repo, numbered and immutable once accepted.

ADR sections:
- title and status (proposed, accepted, superseded)
- context and problem
- decision
- alternatives considered
- consequences

Rules:
- one decision per record; keep it short
- record the why, not just the what
- do not edit accepted ADRs; supersede with a new one
- link related and superseding ADRs