Capture each significant architecture decision as a short, immutable record of context, decision, and consequences with a tracked status. Use when a choice is costly to reverse or crosses teams and the reasoning must outlive the people who made it.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# Architecture decision records
A decision made in a meeting evaporates the moment the room clears, and six
months later someone reverses it without knowing what it cost the last time.
An ADR is the durable answer to "why is it built this way": one file, written
once, that a future maintainer can trust more than anyone's memory.
## Method
1. **One decision per record, numbered and immutable.** Name files
`docs/adr/0007-use-postgres-for-billing.md`. The number never changes and
the file is append-only after acceptance. A record that mixes two decisions
cannot be superseded cleanly when only one of them ages out.
2. **Write the context as forces, not narrative.** State the constraints,
requirements, and pressures in play: throughput targets, team skills,
existing contracts, deadlines. The reader must feel the pressure that made
the decision reasonable at the time, even if it looks wrong later.
3. **State the decision in the active voice.** "We will store billing events
in Postgres and stream them to the warehouse nightly." Not "Postgres seems
like a good option." A decision hedged into a suggestion is not a decision.
…
The line at the top of this page pins the label git:20260718.ea9bc00, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_lt5feycvpadkkbwc
GET https://markdownregistry.com/api/v1/resolve?ref=amey-thakur/ai-skills/architecture-decision-records
GET https://markdownregistry.com/api/v1/blob/4c2d1d010d042040ae66e8ceac36b79f6470936cb625f2df498cc41f668b3fc2
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
amey-thakur/ai-skills · skills/accessibility/accessibility-review/SKILL.md · Audit a UI for real accessibility, keyboard-first, with concrete failures and fixes rather than checkbox compliance…
amey-thakur/ai-skills · skills/accessibility/accessible-forms/SKILL.md · Build forms with associated labels, identified errors, clear instructions, and autocomplete attributes. Use when…
amey-thakur/ai-skills · skills/accessibility/alt-text-writing/SKILL.md · Write alt text that conveys an image's purpose, marks decorative images empty, and handles functional and complex…
amey-thakur/ai-skills · skills/accessibility/aria-usage/SKILL.md · Use ARIA correctly by preferring native HTML, applying roles/states/properties only where needed, and following known…
amey-thakur/ai-skills · skills/accessibility/color-contrast/SKILL.md · Meet WCAG contrast ratios for text and non-text, never rely on color alone, and verify with tools including in dark…
amey-thakur/ai-skills · skills/accessibility/focus-management/SKILL.md · Manage focus on route changes, in modals, and after actions, with visible focus indicators. Use when building…
amey-thakur/ai-skills · skills/accessibility/keyboard-navigation/SKILL.md · Make interfaces fully keyboard-operable with logical focus order, no traps, skip links, and roving tabindex where…
sickn33/agentic-awesome-skills · plugins/agentic-awesome-skills-claude/skills/architecture-decision-records/SKILL.md · Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the…
wshobson/agents · plugins/documentation-generation/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
dicklesworthstone/pi_agent_rust · tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
hashgraph-online/awesome-codex-plugins · plugins/Colin4k1024/tsp/skills/architecture-decision-records/SKILL.md · Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments…
francostino/opencode-skills-collection · bundled-skills/architecture-decision-records/SKILL.md · Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the…
rudycity/superagent · .agents/skills/architecture-decision-records/SKILL.md · Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation…
aicodedecode/awesome-muse-skills · skills-imported/architecture-decision-records/SKILL.md · Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the…
