# ADR (Architecture Decision Record)

> Create and maintain Architecture Decision Records following a consistent template

- Skill: `diegosouzapw/adr-architecture-decision-record` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/adr-architecture-decision-record`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/adr-architecture-decision-record/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/adr-architecture-decision-record

---


# ADR (Architecture Decision Record) Skill

Create and maintain Architecture Decision Records following a consistent template.

## Trigger Conditions
- A new architecture decision needs to be documented
- An existing ADR needs to be superseded or updated
- User invokes with "create ADR" or "document decision"

## Input Contract
- **Required:** Decision context (what problem are we solving?)
- **Required:** Options considered (at least 2 alternatives)
- **Optional:** Constraints, evaluation criteria, stakeholders

## Output Contract
- ADR document in markdown format with: Status, Date, Context, Decision, Consequences, Alternatives Considered
- Numbered sequentially (ADR-NNN) in the `docs/adr/` directory
- Links to related ADRs (supersedes, relates-to)

## Tool Permissions
- **Read:** All project files, existing ADRs, architecture docs
- **Write:** `docs/adr/` directory
- **Search:** Codebase for implementation evidence

## Execution Steps
1. Gather the decision context from user or triggering event
2. Search existing ADRs for related decisions
3. Determine the next ADR number
4. Draft the ADR using the standard template
5. Link to related ADRs and relevant code/config
6. Write the ADR file to `docs/adr/ADR-NNN-<title>.md`

## Success Criteria
- ADR has all required sections filled in
- Status is set (Proposed, Accepted, Deprecated, Superseded)
- Consequences section includes both positive and negative impacts
- File is written to the correct location with proper naming

## Escalation Rules
- Escalate if the decision has >$1K/month cost implications
- Escalate if the decision affects regulatory compliance
- Escalate if no clear winner among alternatives

## Example Invocations

**Input:** "We need to decide between PostgreSQL and DynamoDB for the order service"

**Output:** ADR-005-order-service-database.md with context (high write volume, need transactions), decision (PostgreSQL for ACID guarantees), consequences (operational overhead, need connection pooling), alternatives (DynamoDB rejected due to transaction limitations).