Spotify对ADR（架构决策记录）的看法很不错，但如何在大规模上执行这些记录呢？
嘿，HN，
我开发了 Decision Guardian——一个开源的 GitHub Action 和命令行工具，它会在代码修改受保护文件时自动将架构决策以 PR 评论的形式呈现出来。
它解决的问题：
Spotify 在 2020 年发布了一篇关于何时编写架构决策记录（ADR）的精彩文章。我遵循了这个建议。我的团队编写了 ADR，但它们被放在 docs/adr/ 中，没人会在打开 PR 之前阅读它们。
[Spotify 文章链接](https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record)
问题不在于文档，而在于如何呈现。呈现决策的最佳时机不是在入职培训或冲刺计划时，而是在有人积极编辑受决策保护的代码时。
它是如何工作的：
1) 在 Markdown 文件中编写决策（与现有的 ADR 兼容）
2) 将 GitHub Action 添加到你的工作流中
3) 当 PR 修改受保护的文件时，Decision Guardian 会自动将相关决策作为评论发布
决策格式（普通 Markdown）：
```markdown
<!-- DECISION-DB-001 -->
## 决策：使用 Postgres 进行计费
*状态*: 活跃
*严重性*: 关键
*文件*:
- `src/db/*/*.ts`
### 背景
我们评估了 Postgres 和 MongoDB。计费需要 ACID 兼容性。
MongoDB 被拒绝——没有事务保证。
值得注意的功能：
1) 严重性级别（关键 / 警告 / 信息）——可以在关键违规时阻止 PR
2) 高级匹配：通配符模式、正则表达式、基于内容的规则、布尔逻辑
3) CLI 可与任何 CI 工具配合使用（GitLab、Jenkins、CircleCI、pre-commit hooks）
4) 处理超过 3000 个文件的 PR 而不会出现内存溢出
5) 幂等评论——无垃圾信息，更新就位
6) 零外部网络调用——没有任何数据离开你的 GitHub 运行器
7) 109 个测试，ReDoS 保护，路径遍历保护
与 CODEOWNERS 的对比：CODEOWNERS 指定审阅者。这解释了审查的重要性。最好一起使用。
与 Danger.js 的对比：Danger 需要代码，而这个工具需要 Markdown。非 JS 工程师也可以管理他们的决策。
它是 MIT 许可的，单步骤 GitHub Action 或 npx decision-guardian CLI。
欢迎提问。
仓库链接：[GitHub 仓库](https://github.com/DecispherHQ/decision-guardian)
查看原文
Hey HN,<p>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:<p>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.<p>https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record<p>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.<p>How it works:<p>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<p>Decision format (plain Markdown):<p><!-- DECISION-DB-001 -->
## Decision: Use Postgres for Billing<p>*Status*: Active
*Severity*: Critical<p>*Files*:
- `src/db/*/*.ts`<p>### Context
We evaluated Postgres vs MongoDB. Billing requires ACID compliance.
MongoDB was rejected — no transaction guarantees.<p>Features worth calling out:<p>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<p>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.<p>It's MIT licensed, single-step GitHub Action or npx decision-guardian CLI.<p>Happy to answer questions.<p>Repo: https://github.com/DecispherHQ/decision-guardian