Spotify's take on ADRs is great, but how do you enforce them at scale?
I built Decision Guardian — an open-source GitHub Action and CLI that automatically surfaces architectural decisions as PR comments when code touches protected files. The problem it solves:
Spotify published a great post in 2020 about when to write Architecture Decision Records. I followed the advice. My team wrote ADRs. They sat in docs/adr/. Nobody read them before opening a PR.
https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record
The gap isn't documentation — it's surfacing. The right moment to surface a decision isn't onboarding or sprint planning. It's when someone is actively editing the code the decision protects.
How it works:
1) Write decisions in a Markdown file (compatible with existing ADRs) 2) Add the GitHub Action to your workflow 3) When a PR modifies protected files, Decision Guardian posts the relevant decisions as a comment automatically
Decision format (plain Markdown):
<!-- DECISION-DB-001 --> ## Decision: Use Postgres for Billing
*Status*: Active *Severity*: Critical
*Files*: - `src/db/*/*.ts`
### Context We evaluated Postgres vs MongoDB. Billing requires ACID compliance. MongoDB was rejected — no transaction guarantees.
Features worth calling out:
1) Severity levels (Critical / Warning / Info) — can block PRs on critical violations 2) Advanced matching: glob patterns, regex, content-based rules, boolean logic 3) CLI works with any CI (GitLab, Jenkins, CircleCI, pre-commit hooks) 4) Handles PRs with 3000+ files without OOM 5) Idempotent comments — no spam, updates in place 6) Zero external network calls — nothing leaves your GitHub runner 7) 109 tests, ReDoS protection, path traversal protection
vs. CODEOWNERS: CODEOWNERS assigns reviewers. This explains why the review matters. Best used together. vs. Danger.js: Danger requires code. This requires Markdown. Non-JS engineers can own their decisions.
It's MIT licensed, single-step GitHub Action or npx decision-guardian CLI.
Happy to answer questions.
Repo: https://github.com/DecispherHQ/decision-guardian