architecture-decision-records

architecture-decision-records skill 概览

architecture-decision-records 实际能帮你完成什么

architecture-decision-records skill 用于帮助 AI 代理起草、修订和维护 Architecture Decision Records（ADR，架构决策记录）。相比一句泛泛的“写一份 ADR”提示词，它提供了更清晰的结构。这个 skill 适合需要长期保留技术决策文档的团队：为什么要做这个决策、最终选择了什么、评估过哪些备选方案，以及由此带来的后果。

最适合技术写作与工程团队的场景

这个 skill 特别适合 Technical Writing、Staff Engineer、架构师、平台团队以及工程经理等需要在多个项目中持续产出一致性决策记录的角色。它最适合的场景并不只是“写一份文档”，而是“把决策依据沉淀成未来读者也能信赖的记录”。

真正要解决的问题是什么

大多数团队并不缺一个 ADR 标题，他们真正困难的是：如何把零散的上下文整理成一份可评审、可比较、并且在六个月后仍然有价值的决策记录。architecture-decision-records skill 的价值就在于，它把 ADR 的核心要素——背景、决策、备选方案和后果——放在中心位置，而不是生成一篇模糊的架构说明。

这个 skill 与普通提示词的关键区别

核心差异在于结构。这个 skill 明确围绕 ADR 最佳实践设计，包括：

• 什么情况下值得写 ADR，什么情况下会显得流程过重
• 常见生命周期状态，如 proposed、accepted、rejected、deprecated、superseded
• 像 MADR 这类标准模板
• 以“决策”为中心的表达方式，而不是自由散文式写法

因此，如果你希望在大量技术决策中保持可重复的文档质量，它会比普通 prompting 更合适。

什么情况下 architecture-decision-records 是强匹配选择

以下这类决策很适合使用 architecture-decision-records skill：

• 引入新的 framework 或 platform
• 选择 database 或 messaging system
• 定义 API 或集成模式
• 确定安全架构方向
• 记录具有长期影响的权衡取舍

如果只是日常维护、bug 修复，或某个很小的实现细节，这个 skill 往往会显得流程重于收益。

如何使用 architecture-decision-records skill

architecture-decision-records 的安装信息

这个 skill 位于 wshobson/agents 仓库中的：

plugins/documentation-generation/skills/architecture-decision-records

常见安装方式是：

npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

如果你的环境使用的是别的 skill loader，关键点是记住它的 slug：architecture-decision-records。

先读这个文件

先从这里开始：

SKILL.md

这个仓库路径下实际上只有一个真正有内容的源文件，因此几乎没有隐藏实现需要额外排查。这对快速采用是好事，但也意味着最终输出质量会更依赖你提供的提示上下文。

这个 skill 要吃到什么输入，效果才会好

architecture-decision-records skill 在你提供“可进入决策”的输入时效果最好，而不只是给一个主题。建议至少给代理这些信息：

• 要做出的决策是什么
• 业务或技术背景
• 约束条件和非目标
• 已考虑过的备选方案
• 选择标准
• 已知后果或风险
• 当前状态：proposed、accepted、rejected、deprecated 或 superseded

如果缺少这些内容，代理当然也能生成一个看起来整齐的 ADR 外壳，但里面的决策依据通常会比较泛。

如何把模糊目标写成更强的提示词

弱提示词：

Write an ADR about using PostgreSQL.

更强的提示词：

Draft an ADR for selecting PostgreSQL as the primary relational database for our B2B SaaS platform. Context: we are replacing a single-tenant MySQL deployment, need strong transactional guarantees, support for JSON columns, and managed cloud hosting. Alternatives considered: MySQL 8, PostgreSQL, CockroachDB. Constraints: team already knows SQL but not distributed SQL operations; must run in AWS; migration must complete within 2 quarters. Include status as Proposed, decision drivers, tradeoffs, consequences, and when this ADR should be revisited.

第二个提示词给了这个 skill 足够多的信息，它才能生成一份真正的决策记录，而不是一份靠猜测填空的模板。

推荐的 architecture-decision-records 使用工作流

一个实用的 architecture-decision-records usage 流程通常是：

1. 从 issue 讨论、RFC 或设计文档中收集决策事实。
2. 判断这次变更是否值得写 ADR。
3. 让 skill 按选定格式起草 ADR。
4. 重点检查是否缺失备选方案、论证是否薄弱、后果描述是否模糊。
5. 在评审或批准后更新状态。
6. 当决策发生变化时，补上 superseding ADR 的链接。

这个 skill 最有帮助的地方就在这里：把原始、分散的决策材料压缩成稳定可维护的文档形态。

起草前先选模板

源内容重点提到了标准 ADR 方式和 MADR 风格模板。正式提示前，先确定你需要的是：

• 简洁的标准 ADR
• 带有明确 alternatives 和 consequences 的 MADR 风格结构
• 按你们仓库习惯调整过的内部模板

如果团队已经有 ADR 编号规则，或者固定的标题顺序，最好一开始就告诉这个 skill。否则代理虽然可能生成一份“合法”的 ADR，但你之后还是得手动重排格式。

面向 Technical Writing 场景时，建议补充什么

对于 architecture-decision-records for Technical Writing，建议让代理优化目标指向未来读者，而不只是当前审批人。很实用的补充要求包括：

• 缩写首次出现时给出定义
• 把 context 和 decision drivers 分开写
• 解释为什么 rejected 的方案被否决
• 写清楚运维层面的后果，而不仅是技术收益
• 加上触发复审的条件，比如规模、合规或成本阈值

这样生成的文档会更适合 onboarding、审计和团队交接。

一个可以直接复用的实用提示词框架

可以使用这样的提示框架：

• Decision title
• Status
• Date or ADR number
• Context
• Problem statement
• Constraints
• Alternatives considered
• Decision
• Consequences
• Open questions
• Intended audience
• Required format or headings

这个模式能稳定提升 architecture-decision-records usage 效果，因为它减少了模型凭空补写的空间，同时提高了可追溯性。

安装前需要知道的边界

这个 skill 的定位是文档生成。它不会判断你的架构选择在客观上是否正确。它擅长的是帮助你把理由和取舍说清楚。如果你的团队需要 benchmark、架构建模或自动化策略检查，那么这个 skill 应该放在这些工作之后使用，而不是拿来替代它们。

阅读仓库后的常见结论

由于这个 skill 包本质上几乎只有一个 SKILL.md，所以上手非常直接：没有额外的 helper script、reference bundle 或 rule file 需要先学。代价是，输出质量更多取决于你的输入质量和评审纪律，而不是依赖 skill 内置自动化。

architecture-decision-records skill 常见问题

如果我本来就会直接 prompt LLM，还有必要安装 architecture-decision-records 吗？

有必要，前提是你确实经常写 ADR。通用提示词也许能产出一篇不错的文档，但 architecture-decision-records skill 为重复性的决策记录提供了更清晰的默认框架。它的价值在于一致性，以及更少遗漏关键部分，尤其是 alternatives 和 consequences 这些常被漏掉的内容。

这对新手友好吗？

友好。这个 skill 会解释 ADR 的基础概念，比如 context、decision、consequences，以及什么情况下该写 ADR、什么情况下可以不写。这让刚开始实践 ADR 的团队也能用起来。不过新手仍然需要提供真实的项目背景；这个 skill 不会自行推断你们组织内部的约束。

什么情况下不应该使用 architecture-decision-records？

如果变更很小、很常规，或者纯粹停留在实现层面，就不建议使用：

• patch 升级
• bug 修复
• 日常维护
• 影响很低的配置变更

这类情况通常写一条 issue 评论或 changelog 记录就足够了。

它和 RFC 有什么区别？

RFC 通常范围更大、更偏探索性，而且往往出现在团队尚未收敛结论之前。ADR 则更聚焦、更以“已做出的决策”为中心。当你需要记录“最终决定了什么，以及为什么这么决定”，特别是在讨论已经趋于成熟之后，architecture-decision-records 会更合适。

可以把 architecture-decision-records 用在现有文档仓库里吗？

可以。它很适合放进已有 /docs/adr/、/adr/ 或类似目录的仓库里。如果你们已经采用 ADR-0001 这类编号方式，记得在提示词里明确说明，这样生成出来的文档才能贴合你们现有规范。

这个 skill 也能帮助维护旧 ADR 吗？

可以。源内容中的生命周期模型对维护更新很有帮助：proposed、accepted、rejected、deprecated、superseded。这个 skill 不只是用于新决策，也很适合修订已经过时的 ADR，或者在替换旧 ADR 时补上更清晰的状态与交叉链接。

如何改进 architecture-decision-records skill 的使用效果

提供 decision drivers，而不只是你偏好的答案

提升 architecture-decision-records 输出质量最快的方法，就是把推动决策的真实因素告诉它，比如：

• 规模要求
• 延迟需求
• 合规义务
• 人员配置限制
• 成本上限
• 迁移时间线

如果你只告诉它偏好的技术选型，写出来的 ADR 往往会像“事后合理化”。

给出真实备选方案，以及它们为什么会被纳入考虑

很多质量差的 ADR 只是随口提了一种备选方案，或者虚构几个陪衬选项。更好的提示词应该列出可信的 alternatives，并说明它们为什么曾经在备选名单里。这样这个 skill 才有足够素材写出真正有价值的 tradeoff 部分，而不是泛泛而谈的对比。

明确状态和复审触发条件

要明确告诉这个 skill，当前 ADR 属于：

• Proposed
• Accepted
• Rejected
• Deprecated
• Superseded

同时也要写清楚什么情况会触发重新评估。这样能提升文档的维护价值，也避免一个仍在评审中的 ADR 看起来像最终定稿。

让 consequences 覆盖多个维度

一个更强的 architecture-decision-records guide 提示词，会要求它从多个维度写 consequences，例如：

• engineering complexity
• operations
• security
• cost
• team learning curve
• future flexibility

这样产出的 ADR 会比一句“优缺点”更能支持实际决策。

留意常见失败模式

常见的弱输出通常有这些表现：

• context 很泛，几乎任何项目都能套用
• 没有被否决的 alternatives
• 只讲收益，不讲成本
• 决策表述过于宽泛，无法落地实施
• 没有说明作用范围或受影响系统

如果出现这些问题，通常不是模板本身有问题，而是输入信息不够。

用有针对性的修订请求来迭代

第一版出来后，建议用更窄、更明确的 follow-up 去优化，例如：

• Tighten the decision statement to one implementable choice.
• Expand the rejected alternatives with concrete tradeoffs.
• Add operational consequences for deployment and monitoring.
• Rewrite the context so a new team member understands the trigger.
• Mark what assumptions would invalidate this ADR.

这种方式通常比笼统地让模型“改得更好”更有效。

按你们自己的 ADR 标准改写输出

如果组织内部有自定义模板，可以让这个 skill 把标准 ADR 元素映射到你们自己的标题结构中。比如你们可能要求额外包含：

• ownership
• review date
• compliance impact
• rollout plan
• links to tickets or PRDs

是否要做 architecture-decision-records install，本质上就取决于这种结构化起草能力是否契合你们现有的文档流程。

用链接纪律提升长期价值

优秀的 ADR 集合应该是可导航的。可以要求这个 skill 一并包含：

• related ADRs
• superseded-by references
• impacted systems
• links to design docs or incident reports

这样它就不再是一份一次性的文档，而会成为可持续使用的决策历史的一部分。

首次使用后，评估这个 skill 的最佳方式

一个很实用的验收标准很简单：让一位新工程师阅读生成的 ADR，看看他能否回答这些问题：

• 原来存在什么问题
• 最终做了什么决策
• 考虑过哪些备选方案
• 为什么是这个方案胜出
• 团队接受了哪些权衡
• 这个决策应该在什么时候重新评估

如果这些问题答不上来，就说明需要补充更好的源上下文，然后重新运行 architecture-decision-records skill。