AD
Architecture Decision Record (ADR)
🟢 Production-Ready🕐 updated 2026-07-14
🔷 SkillSpec L3
pm-engineering
Create an Architecture Decision Record (ADR) for any technical decision. Use when asked to document a technical decision, write an ADR, record an architecture choice, or capture why a technology or approach was selected. Produces a structured ADR with context, decision, consequences, and tradeoffs.
📚 Based on ADRs — Michael Nygard
What to give it
▸ADR number — sequential number in your ADR registry — e.g. 012; or "next available" if unknown
▸Decision title — brief, e.g. "Use PostgreSQL as primary datastore"
▸Context — what situation led to this decision needing to be made?
▸Options considered — at least 2; if only 1 is given, prompt for alternatives that were considered or ruled out
▸Decision made — which option was chosen
▸Reason for choice
▸Status — Proposed / Accepted / Deprecated / Superseded
▸Author and date
▸Team context (optional) — optional — team size, relevant experience, org constraints; helps calibrate formality and depth of the Context section
✅ The bar it holds itself to
Every skill in this library self-verifies — these are this skill's own quality checks, straight from its definition.
✓Context explains the *why* — not just the *what*
✓At least 2 options are documented (including the rejected ones)
✓Rejected options include honest reasons for rejection
✓Consequences include *negative* consequences — no decision is consequence-free
✓Decision is stated in plain language in the Decision section
✓Risks section identifies what would invalidate this decision
✓Context section states the problem explicitly in its first 1–2 sentences (does not assume the reader knows what problem the team was solving)
✓Each rejected option's "Why ruled out" explanation names a specific constraint or trade-off (not a circular statement like "didn't meet our requirements")
⚠️ What it refuses to do
Do not write an ADR after the decision has already been fully implemented and the team has moved on — ADRs written retrospectively often omit the real reasons and alternatives
Do not list only the chosen option — rejected options with honest reasons are the most valuable part of an ADR for future readers
Do not write consequences that are all positive — every architectural decision involves trade-offs; an ADR with no negative consequences was not scrutinised honestly
Do not leave the status as "Proposed" indefinitely — an ADR that no one has approved is not guiding anyone's decisions
Do not write context that assumes the reader already knows what problem was being solved — the context section exists precisely for readers who lack that background
Install
npx pm-claude-skills add --agent claude # or codex · cursor · gemini · hermes
# or one-line MCP (every skill, any client):
claude mcp add pm-skills -- npx -y pm-claude-skills-mcpStart with
Related skills
🔌 Embed this skill
Drop this on your blog, docs, or site — it renders a "Run this skill" card:
<div data-pm-skill="architecture-decision-record"></div>
<script src="https://mohitagw15856.github.io/pm-claude-skills/embed.js" async></script>💬 Discussion
Architecture Decision Record (ADR) is one of 1174 open-source professional AI agent skills — all SkillSpec L3.
Try them all in the browser · ⭐ Star on GitHub · Browse the full catalog