architecture-decision-records

npx skills add cosmicstack-labs/mercury-agent-skills --skill architecture-decision-records --agent claude-code

Same command for any agent — swap --agent for codex, cursor, copilot.

# Architecture Decision Records Capture architectural decisions systematically so your team understands not just what was decided, but why — and what alternatives were considered. ## Core Principles ### 1. Decisions Are More Important Than Diagrams A diagram shows the current architecture. An ADR explains *why* it is that way. When someone asks "why did we do it this way?" the ADR is the answer. ### 2. Capture Context, Not Just Conclusions Every architectural decision exists in a web of constraints, tradeoffs, and alternatives. If you only record the conclusion, future engineers will wonder if you considered the obvious alternative — and they might reverse it without understanding why the original choice was made. ### 3. Lightweight Is Sustainable An ADR doesn't need to be a 10-page document. A structured 1-page record is infinitely better than nothing. If the process is heavy, people won't follow it. ### 4. Accept and Track Superseded Decisions Architecture evolves. An ADR that gets superseded is a success — it means the system adapted. Old ADRs remain valuable as historical records of the team's thinking. --- ## ADR Maturity Model | Level | Capture | Storage | Review | Enforcemen

Create the ADR file
mkdir -p docs/adr/
cp templates/adr-template.md docs/adr/ADR-043-use-graphql-for-public-api.md
ADR naming convention
Use leading zeros for sorting: ADR-001, ADR-002, ..., ADR-043
Run ADR linting in CI
npx adr-lint docs/adr/
Example output:
adr-tools (command-line)
Install