mcpField
A
arch-adr

arch-adr

github.com/yonatankarp开发139 次安装23 周前更新
代码仓库

关于 arch-adr

用于在代码仓库中以简洁、结构化文档记录架构决策的技能。它帮助团队在决策时保存背景、理由、备选方案和后果，为维护者保留不可变的决策历史。

主要功能

  1. 01结构化 ADR 章节
  2. 02连续且固定的编号
  3. 03通过新决策取代旧决策
  4. 04基于仓库的决策记录
  5. 05关于范围与时机的指导
  6. 06工具与模板参考

适用场景

  1. 01记录数据库或消息系统选型
  2. 02说明未采用的架构方案
  3. 03帮助新成员理解决策背景
  4. 04保留被替代决策的历史

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yonatankarp/software-design-skills --skill arch-adr

安装后在 Claude Code 中输入/arch-adr确认已加载。

详细介绍

一句话概述

一份简短、结构化的文档，用于记录一项架构决策：决定了什么、为什么、拒绝了哪些备选方案，以及会产生哪些后果。在作出决策时编写，并永久保留在代码库中。

何时使用此技能

  • 任何未来维护者若不了解决策缘由就可能会质疑的架构选择。例如：选择数据库、选择消息系统、在六边形架构与分层架构之间做选择、选择微服务而非单体架构。
  • 认真考虑并拒绝了其他备选方案的决策——记录拒绝它们的原因最有价值。
  • 新人入职：新成员可以阅读 ADR 集合，了解架构如何发展到当前状态。

何时不使用此技能

  • 战术性的代码级决策（使用 data class 还是 class、文件组织方式）——这类决策过于细碎，写作成本高于收益。
  • 没有真正备选方案的决策（在只使用 Python 的团队中选择 Java 还是 Python，并不算决策）。
  • 事后补写“为两年前作出的、如今已不记得缘由的决策写一份 ADR”——价值在于时间戳；事后补写的价值要低得多。

核心内容

标准 ADR 结构（Michael Nygard 的原始模板）：

  • 标题。 简短的名词短语。“将 PostgreSQL 用作主要存储”或“为订单服务采用六边形架构”。
  • 状态。 proposed / accepted / deprecated / superseded by ADR-NNN。
  • 背景。 当前情况、影响因素和限制条件是什么？为什么现在需要作出此决策？
  • 决策。 我们决定了什么。应以肯定的陈述表达（“我们将……”），而不是讨论性的表述（“我们正在考虑……”）。
  • 后果。 此决策带来的影响——包括利弊。它会让我们承担哪些责任，又会引发哪些新问题？
  • (可选) 备选方案。 还有哪些方案可选；为何逐一拒绝。

文件布局。

docs/adr/
├── 0001-use-postgresql.md
├── 0002-adopt-hexagonal-architecture.md
├── 0003-event-bus-via-rabbitmq.md
├── 0004-replace-rabbitmq-with-kafka.md  (supersedes 0003)
└── README.md      ← index of ADRs

编号按顺序递增，且永不重用。替换某份 ADR 时，新 ADR 应引用旧 ADR，并将旧 ADR 的状态改为 superseded by ADR-NNN。旧 ADR 保留在目录树中——记录历史正是目的所在。

长度。 一页。如果一份 ADR 有两页，它可能作出了两项决策，应该拆分。

工具。 adr-tools（shell）、adr-manager、MADR 模板、Log4brains——都可以生成／索引 ADR。规模较大时很有用；小团队手动编写 Markdown 即可。

持续更新的文档与决策日志。 ADR 是决策日志——一旦接受就不可更改。“持续更新的文档”是其他内容（README、架构图）。不要修改 ADR 中的决策文本；应以新 ADR 取而代之。

决策准则

  • 在实施决策之前编写 ADR，促使思路清晰。
  • 即使决策看起来显而易见，也要编写 ADR——“显而易见”往往意味着“我没有认真考虑”。
  • 简短而具体地写明备选方案。“我们考虑过 Kafka，但由于目前没有流式处理的使用场景，因此拒绝了它。”
  • 编号按顺序递增且不可更改。不要重新编号，也不要重用已删除的编号。
  • ADR 应保存在代码库中，而不是 Wiki 上。它们会进行版本管理和评审，并与代码一同维护。

反模式

  • 架构 Wiki 页面。 很快就会过时，团队人员变动后也难以保留，评审者通常不会阅读。
  • 事后为无人记得的决策编写 ADR。 时间戳很重要。事后补写的价值有限。
  • 隐藏备选方案部分的 ADR。 大部分价值在于为什么拒绝了某个方案。没有这一部分，ADR 就只是一份声明。
  • 修改旧 ADR 中的决策文本。 这会破坏历史记录。应以新 ADR 取而代之。
  • 为战术性决策编写数百份 ADR。 ADR 面向架构决策；并非每项文件组织选择都值得记录。标准应保持足够高，让整个 ADR 集合仍然易于阅读。

另请参阅

  • arch-fitness-functions — 适应度函数约束 是什么；ADR 记录 为什么。建议配合使用。
  • 所有其他 arch-* 技能 — 大多数架构决策都值得记录为 ADR。

参考资料

  • Michael Nygard，《记录架构决策》（2011 年文章）—— ADR 概念的原始阐述。
  • MADR 模板——现代 Markdown ADR 模板。
  • adr-tools —— Joel Parker Henderson 编写的 shell 工具。
  • Richards 和 Ford，《软件架构基础》，第 19 章（架构决策）。

评论

支持 Markdown