architecture-decision-records

architecture-decision-records 技能概览

architecture-decision-records 技能能做什么

architecture-decision-records 技能帮助 agent 在编码过程中，把正在发生的架构决策整理成轻量级 ADR（Architecture Decision Record）。它不是让你事后再要一份泛泛总结，而是专门用来识别决策点、记录上下文和权衡，并输出一份可以直接留在仓库里的结构化记录。

最适合技术写作和工程团队

architecture-decision-records 技能非常适合 AI 辅助开发团队、希望保留长期决策历史的技术负责人，以及需要为系统文档积累一手素材的 Technical Writing 流程。它真正要解决的不是“写 markdown”，而是在团队对某个方案做出选择的当下，把“为什么选它而不是别的方案”保留下来，避免这段理由被聊天记录、提交记录或记忆慢慢冲散。

它和普通 prompt 有什么不同

普通 prompt 也能生成一次 ADR 模板，但 architecture-decision-records 技能在决策跨多个会话反复出现时更有价值，比如框架选型、API 模式、数据存储、部署设计，或者弃用方案的取舍。它的核心差异在于触发逻辑，以及基于 Michael Nygard 轻量风格的一致 ADR 结构。

采用时要注意的关键限制

architecture-decision-records 技能本身刻意做得很窄。它不能单独替代架构评审、治理流程，或仓库内部的标准约定。它看起来还只是一个单独的 SKILL.md，没有配套脚本或校验工具，所以输出质量会高度依赖你的 prompt 质量和仓库惯例。

如何使用 architecture-decision-records 技能

安装上下文，以及先读哪里

如果要安装 architecture-decision-records，先把父级 skill collection 加入你的 Claude Code skills 工作流，然后先打开 skills/architecture-decision-records/SKILL.md。目前看不到配套的 rules/、resources/ 或自动化文件，所以几乎所有可用指导都集中在这一份文件里。建议按这个顺序阅读：When to Activate、ADR Format，然后再看 markdown fence 里的示例。

这个技能要什么输入才好用

architecture-decision-records 技能在你提供以下信息时效果最好：

• 正在做出的决策是什么
• 认真评估过哪些备选方案
• 约束条件有哪些，例如成本、性能、团队熟悉度、交付期限、合规要求或迁移风险
• 谁参与了决定，以及当前状态是 proposed、accepted、deprecated 还是 superseded
• ADR 要存放到哪里、命名规则是什么、编号规范是什么

弱输入： “写一份关于使用 Postgres 的 ADR。”
强输入： “为选择 Postgres 而不是 DynamoDB 处理事务型订单流程创建 ADR-0012。上下文：需要多行一致性、团队已有 SQL 技能、规模中等、部署在 AWS、交付周期 3 个月。状态：accepted。决策者：平台负责人、后端负责人。”

把粗略目标变成更强的调用 prompt

在实际使用 architecture-decision-records 时，最好同时要求抽取和格式化。一个更好的 prompt 模式是：

“Use the architecture-decision-records skill. From this discussion, identify whether an ADR should be created. If yes, draft it in Michael Nygard style with Context, Decision, and Alternatives Considered, and note any missing facts you need before finalizing.”

之所以这样写很重要，是因为 architecture-decision-records 技能在决策还没有完全定型时最好用。它能让 agent 识别决策点、起草 ADR，并把缺失信息暴露出来，而不是硬编理由。

在真实仓库里的推荐工作流

1. 在规划或实现过程中识别出一个有意义的决策。
2. 让 agent 使用 architecture-decision-records 技能起草 ADR。
3. 核对事实是否准确，尤其是被否决的备选方案和约束条件。
4. 将其保存到稳定目录，比如 docs/adr/ 或 adr/。
5. 在 PR、架构文档或入职文档中链接这份 ADR。

对于 Technical Writing，建议再配一段简短的“影响”说明：读者现在应该如何理解 API、基础设施或未来迁移。这会让 ADR 不只停留在工程聊天记录里，而是更容易在后续内容中复用。

architecture-decision-records 技能 FAQ

如果我已经会自己 prompt 生成 ADR，还值得安装 architecture-decision-records 吗？

值得，前提是你的痛点在一致性和时机，而不只是 markdown 格式。architecture-decision-records 技能给 agent 更明确的触发点：在决策发生时就记录，而不是几周后再补写。如果你只需要一次性的 ADR 模板，普通 prompt 可能就够了。

这个技能适合初学者吗？

适合，但有一个前提。初学者可以借助它产出有用的 ADR 草稿，但他们未必知道哪些约束最关键，或者哪些备选方案才是真正可行的。architecture-decision-records 技能能帮助整理思路，但在最终接受前，最好还是有 reviewer 去验证技术权衡。

什么情况下不该用这个技能？

不要拿它记录那些琐碎的实现细节、临时实验，或者没有长期架构影响的决定。过度记录会制造 ADR 噪音。architecture-decision-records 更适合记录未来维护者会追问的问题，比如“为什么选这个技术栈、这个模式、这个边界，或者这个集成方式？”

它如何适配 Technical Writing 工作？

architecture-decision-records 技能对 Technical Writing 很有用，因为它能在信息源头附近直接捕捉决策理由。作者可以把已接受的 ADR 转化为系统概览、迁移说明、FAQ 内容和 onboarding 材料，而不必从零散的聊天记录或 PR 评论里重新拼回决策背景。

如何改进 architecture-decision-records 技能

提供更好的源材料，而不只是一个主题

影响质量最大的因素是具体性。请提供约束条件、被否决的方案，以及真正推动决策的原因。“我们选了 Redis 做缓存”信息太少。“我们选 Redis 而不是进程内缓存，因为需要在多个 worker 之间共享失效机制，并且在横向扩展时保持可预测行为”要好得多。architecture-decision-records 技能只能保留已经出现在输入里的推理。

避免常见失败模式

常见问题包括上下文模糊、伪造备选方案，以及结论过于自信。如果草稿读起来像这个决定本来就显而易见，就让 agent 展开权衡。如果备选方案太浅，就补上你们确实讨论过的前 2–3 个选项。如果决策还只是暂定，状态就保持 proposed，不要硬改成 accepted。

按你的仓库标准调整 ADR 输出

上游 skill 使用的是轻量 ADR 结构，但很多团队还需要额外字段，比如 consequences、links、owners 或 review date。改进 architecture-decision-records 的使用方式，最好明确告诉 agent 你们仓库里哪些标题是必填的，以及文件应该放在哪里。否则你可能拿到一份很干净的草稿，但仍然需要重新调整格式。

第一版之后继续迭代

把第一版输出当作一个决策检查点，而不是最终事实。可以继续追问，比如：

• “这份 ADR 里有哪些假设没有写明？”
• “哪个备选方案值得更公平地展开？”
• “我们应该记录哪些未来可能翻盘的信号？”
• “哪些代码区域或文档应该链接到这份 ADR？”

这些追问会让 architecture-decision-records 技能比单纯的模板填充器更有价值，尤其是在你希望 ADR 几个月后依然有用的时候。