# Adr

> Suggest documenting significant architectural decisions as ADRs

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

---


# ADR Suggestion Skill

When you detect an architectural decision being made, gently suggest documenting it.

## What Qualifies as ADR-Worthy

Decisions that:
- Affect multiple parts of the codebase
- Are difficult or costly to reverse
- Involve trade-offs between competing concerns
- Establish patterns that future code should follow
- Change how the system behaves architecturally

## What Does NOT Need an ADR

- Bug fixes
- Minor refactoring
- Adding features within existing patterns
- Routine dependency updates
- Code style changes

## How to Suggest

After completing significant architectural work, suggest:

> This change introduces [pattern/technology/approach]. Consider documenting this decision with an ADR to capture the context and reasoning. You can run `/adr:create` to create one.

## Suggestion Guidelines

- Suggest once per decision, not repeatedly
- Frame as optional, not required
- Only suggest after the work is done, not before
- Include what makes this ADR-worthy (e.g., "introduces a new caching layer")
- Keep suggestions brief - one sentence plus the command reference