ADR

 

ADR

https://adr.github.io/

📝 什么是架构决策记录 (ADR)？

简单来说，架构决策记录 (ADR) 是一种用于记录软件开发过程中重要决策及其背后原因的文档。它的核心目的是让团队能够清晰地理解“为什么”要做出某个特定的架构选择，以及这个选择带来的权衡和后果。

一个项目的所有 ADR 集合就构成了该项目的决策日志 (decision log)。

🎯 ADR 的核心价值

• 记录决策原因： 捕获单个架构决策及其理由，避免知识随着人员变动而流失。
• 管理架构知识： 作为架构知识管理 (AKM) 的一部分，帮助团队积累和传承技术决策的上下文。
• 统一沟通语言： 建立一个共同的词汇表，便于团队成员之间就架构问题进行讨论。

📚 推荐的背景资料

如果你想深入了解 ADR 的概念和实践，可以参考以下资源：

• 概念普及文章： Michael Nygard 在 2011 年发表的博客文章《Documenting Architecture Decisions》是普及 ADR 概念的经典之作。
• 实践指南： Open Practice Library 中的《Architectural Decision Records (ADR): Open & Transparent Decision History》提供了一套实践方法。
• 视频讲解： Michael Keeling 和 Joe Runde 的演讲《Architecture Decision Records in Action》分享了实际应用中的经验。
• 行业推荐： AWS 的官方指南也推荐在软件开发项目中使用 ADR 来简化技术决策流程。

 

https://github.com/architecture-decision-record/architecture-decision-record

这份 GitHub 仓库（architecture-decision-record/architecture-decision-record）是一个关于**架构决策记录（ADR）**的综合资源库，旨在为软件规划、IT 领导和文档模板提供参考。

以下是该网页内容的详细总结：

1. 核心概念：什么是 ADR？

ADR 是一种文档形式，用于捕捉重要的架构决策、其背景环境以及产生的后果。

• ADR (Architecture Decision Record)：记录单个重要架构决策的文档。
• ADL (Architecture Decision Log)：特定项目或组织维护的所有 ADR 的集合。
• ASR (Architecturally-Significant Requirement)：对软件系统架构有可测量影响的需求。
• 目标：帮助团队更聪明地思考，更好地沟通，避免决策成为“事后诸葛亮”式的强制文书工作。

2. 如何开始使用 ADR

• 工具选择：可以使用 Google Docs、Jira、Wiki，或者像该仓库推荐的那样使用 Git 进行版本控制。
• Git 实践：
  • 创建 adr 目录。
  • 为每个决策创建一个文本文件（如 choose-database.md）。
  • 命名规范：推荐使用小写字母、连字符和现在时祈使句（例如 choose-database.md），以便于阅读和匹配提交信息。
• 团队建议：
  • 建议将目录命名为 "decisions" 而非 "ADRs"，以降低认知门槛，鼓励团队记录更多类型的决策（如供应商、计划决策）。
  • 虽然理论上 ADR 应不可变，但实践中建议将其作为“活文档”更新，添加带有时间戳的新信息。

3. 编写高质量 ADR 的建议

• 理由 (Rationale)：解释决策的原因，包括背景、优缺点比较、成本效益分析等。
• 具体性 (Specific)：每个 ADR 应只关注一个决策。
• 时间戳 (Timestamps)：标记编写时间，特别是涉及成本、时间表等随时间变化的信息。
• 后果 (Consequences)：说明决策带来的影响、后续行动以及相关的其他 ADR。

4. 模板与资源

该仓库收集了多种 ADR 模板，以适应不同的需求：

• Michael Nygard：简单且流行。
• Jeff Tyree & Art Akerman：更复杂、详细。
• MADR (Markdown Any Decision Records)：强调选项及其优缺点。
• 其他：包括针对商业案例、Alexandrian 模式、Planguage 以及重要技术决策（ITDs）的模板。

5. 团队协作与治理

• 生命周期：建议 ADR 经历“发起 → 研究 → 评估 → 实施 → 维护 → 淘汰”五个阶段。
• 角色与职责：明确提案人、研究人员、审查者和批准者。
• 治理原则：建议遵循“行动偏见”、“不同意但执行”等原则，并明确治理优先级（如 CEO > CTO > 团队）。

6. 进阶概念：决策即代码

• 适应度函数 (Fitness Functions)：通过代码自动检查决策是否被维护（例如，测试所有状态变更是否都产生了事件）。
• 架构单元测试：使用 ArchUnit (Java) 或 ArchUnitTS (TypeScript) 等工具检查代码架构规则。
• 决策护栏 (Decision Guardrails)：在 Pull Request 中自动提示相关的决策记录，防止代码变更违背既定架构决策（如 ADR Guard）。

7. 相关工具与生态

• 工具：kgai（AI 编码代理的决策日志）、ADR Guard（GitHub Action）、Command-line tools。
• 相关模型：C4 模型（软件架构可视化）、Arc42（架构文档模板）。
• 参考资料：包含大量书籍、视频、播客和外部链接，涵盖软件架构度量、演进式架构等领域。

该仓库由 joelparkerhenderson 维护，拥有超过 16.8k 的 Star，是一个活跃的开源社区资源。

 

Command-line tools for working with Architecture Decision Records

https://github.com/npryce/adr-tools

 

ADR-driven Development with Cursor

https://github.com/fanqingsong/adr-driven

This repository demonstrates how to use Architecture Decision Records (ADRs) to guide development and ensure code compliance with established architectural decisions. It showcases a Tekton task that has been built following multiple Konflux ADRs.

What's Included

• Architecture submodule: Contains the complete set of Konflux ADRs
• Example Tekton task: A "Hello World" task that demonstrates compliance with multiple ADRs
• Cursor integration: Workspace rules that help Cursor understand and enforce ADR compliance

 

Cursor & Agent Configs

https://github.com/DVC2/cursor-agent-configs

The five primitives — and when to use each

Primitive	Lives in	Use it when…	Reads cross-tool?
AGENTS.md	repo root (+ nested)	You want always-on project context: stack, conventions, commands. Start here.	✅ Cursor, Codex, Copilot, Gemini CLI, Aider, Windsurf, Zed…
Rules (.mdc)	.cursor/rules/	You need scoped guidance — applies only to matching files (globs) or when the agent judges it relevant (description).	Cursor only
Subagents	.cursor/agents/	A task needs its own isolated context or a specialized persona (review, verify, test) — possibly run in parallel.	Cursor (+ .claude/.codex dirs)
Skills	.cursor/skills/<name>/SKILL.md	You have an on-demand procedure that should load only when relevant (e.g. "write an ADR"), keeping context lean.	Cursor (+ compat dirs)
Hooks	.cursor/hooks.json + .cursor/hooks/	You need deterministic, non-negotiable behavior around agent actions — format on save, block destructive commands.	Cursor

Rule of thumb: AGENTS.md first. Add a scoped rule only when you hit a real scoping need; reach for a subagent/Skill/hook when the job is delegation, on-demand knowledge, or hard enforcement respectively.