技能使用指南

architecture-decision-records（架构决策记录）Skill 是什么？如何下载安装？

架构决策记录Skill（architecture-decision-records）内置MADR标准、轻量级、Y-Statement、废弃替代与RFC五种ADR模板，覆盖何时该写、生命周期、目录索引、审查清单与adr-tools自动化用法。它帮架构师在决策发生时就沉淀背景、候选方案与后果，避免知识随人员流失，让新人快速读懂历史架构取舍。立即安装，让每次技术选型都有据可查。

架构决策记录Skillarchitecture-decision-records
10 个章节 约 16 分钟阅读 AI 智能生成

架构决策记录Skill：把“当初为什么这么设计”变成可追溯的团队资产

  • 一句话定位：它不是又一个文档生成器，而是一套“何时该写、怎么写、怎么审、怎么迭代”的架构决策记录（ADR）方法论，被封装成 AI 可直接调用的技能。
  • 内置 5 套模板：MADR 标准模板、轻量级模板、Y-Statement 模板、废弃/替代模板、RFC 风格模板，覆盖从一句话决策到完整提案的全部场景。
  • 带判断标准：技能内置“该写 ADR / 可以跳过 ADR”的对照表，帮你避免把错误修复、配置微调也写成厚重文档。
  • 覆盖全生命周期：提议 → 接受 → 废弃 → 替代（或拒绝），并规定了目录结构、索引 README、审查清单与最佳实践。
  • 配套自动化路径：技能详情中给出了 adr-tools 的真实命令用法，可把索引生成、ADR 编号、替代关系链接交给命令行完成。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：架构决策记录 技能英文名：architecture-decision-records 技能 ID：13249

它解决什么问题

技术团队最贵的成本，往往不是写代码，而是“决策失忆”。半年后有人问：“为什么当初选 PostgreSQL 不选 MongoDB？”“为什么订单服务要做事件溯源？”——答案通常散落在某个已离职同事的聊天记录、一次没留下会议纪要的评审会，或者干脆无人知晓。

这个技能要解决的正是这类问题：把重大技术决策的**背景（为什么要决定）、决策（决定了什么）、后果（结果是什么）**结构化地沉淀下来，让架构选择可回溯、可审查、可传承。它适用于记录重大技术决策、审查过去的架构选择，或从零建立团队的决策流程。

一键安装的思路与步骤

AI 技能的安装逻辑，本质是“把一份方法论说明书装进 AI 的上下文”，装好之后你不需要每次粘贴模板，直接说需求即可。

  1. 确认安装前提：你使用的 AI 客户端或 IDE 插件需支持 Skill / 技能机制（能加载技能包并识别其触发场景）。若你的工具只支持普通对话，也可以把技能内容作为自定义提示词使用，效果略有差异。
  2. 获取技能包：通过所在平台的技能市场或技能目录，检索技能名 architecture-decision-records 或技能 ID 13249 进行安装；若是本地技能目录模式，将技能文件夹放入客户端约定的技能路径下。具体安装入口、目录路径与命令以官方说明为准。
  3. 验证是否生效：安装后直接下达一句自然语言指令测试，例如“帮我用 MADR 模板写一份 ADR，主题是我们决定引入 Redis 做缓存”。若输出包含“状态、背景、决策驱动因素、考虑选项、决策、原理、后果、实现注释、相关决策”等标准段落，说明技能已被正确加载。
  4. 配套工具（可选）：技能详情中还给出了 adr-tools 的用法，可进一步实现命令行级管理，例如：brew install adr-tools 安装工具、adr init docs/adr 初始化 ADR 目录、adr new "使用PostgreSQL作为主数据库" 新建记录、adr new -s 3 "废弃MongoDB，转用PostgreSQL" 创建替代型 ADR、adr generate toc > docs/adr/README.md 生成目录索引。安装方式与版本要求以官方说明为准。

这条“技能 + 命令行工具”的组合路径，就是提升开发效率的关键：AI 负责内容质量与结构，工具负责编号、索引与关联，人只需要做判断和审查。

该技能的主要功能和特点

  • 五套现成模板，按场景选型

    • MADR 标准模板：最完整的一套，含状态、背景、决策驱动因素、考虑选项（逐项列优缺点）、决策、原理、后果（正面/负面/风险）、实现注释、相关决策、参考资料，适合数据库选型、安全架构这类高影响决策。
    • 轻量级模板：只保留状态、日期、决策者、背景、决策、后果与缓解措施，一屏可读完，适合“采用 TypeScript”这类团队内技术约定。
    • Y-Statement 模板：一句话讲完“在什么背景下、面临什么问题、我们决定选什么、而非哪些备选、以实现什么、并接受什么代价”，适合快速记录架构模式选择。
    • 废弃/替代模板：专门处理“推翻过去的自己”，包含迁移计划（分阶段双写、回填、切换、退役）、经验教训复盘。
    • RFC 风格模板：面向“还没定”的提案，含总结、动机、详细设计、缺点、替代方案、未解决问题清单、实现计划。

  • 内置“写不写”的判断标准：技能给出明确对照表——新框架采用、数据库选型、API 设计模式、安全架构、集成模式应该写；次要版本升级、错误修复、实现细节、常规维护、配置更改可以跳过。这一条能有效防止 ADR 泛滥成“流水账”。

  • 定义了完整的生命周期语义：提议 → 接受 → 废弃 → 替代，以及旁支的“拒绝”。四个状态加一条分支，让决策的“当前是否有效”一目了然。

  • 给出可落地的目录与索引规范：docs/adr/ 下存放 README.md（索引与指南）、template.md（团队模板）与按 NNNN-title-with-dashes.md 命名的记录文件，废弃文件加标记，索引表按“编号 / 标题 / 状态 / 日期”呈现。

  • 提供三段式审查清单：提交前（背景是否清晰、选项是否穷尽、优缺点是否诚实、后果是否记录、相关 ADR 是否链接）、审查中（至少两名高级工程师、受影响团队已咨询、安全与成本影响、可逆性评估）、接受后（索引更新、团队通知、实施工单、文档同步）。

  • 明示最佳实践与反模式：及早撰写、保持 1–2 页、诚实描述权衡、链接相关决策、及时更新状态；反面则是“不要修改已接受的 ADR，而要写新的替代”“不要跳过背景”“不要隐藏失败的决策”。

  • 与普通文档工具的本质差异：普通工具给你一张空白页，这个技能给你的是判断标准 + 结构化骨架 + 审查流程。它不负责“排版好看”，负责“内容不漏项、决策不失真”。

如何使用该技能？

第 1 步：明确决策主题与影响面 先用一句话写清楚要决定什么，例如“订单服务是否从 CRUD 改造为事件溯源”。如果这句话说不清楚，说明还没到写 ADR 的阶段。

第 2 步：用对照表判断是否值得建档 对照技能内置的“该写 / 可跳过”清单。若是新框架采用、数据库或消息中间件选型、安全与集成模式，进入下一步；若是版本升级或配置微调，直接跳过，避免文档负担。

第 3 步：选择模板 影响大、参与方多 → MADR 标准模板；团队内快速约定 → 轻量级模板；只想记录“选 A 不选 B 的理由” → Y-Statement；推翻旧决策 → 废弃/替代模板；尚在征求意见 → RFC 风格。

第 4 步：向 AI 下达结构化指令（含输入示例）

请用 MADR 模板写一份 ADR：我们正在为电商平台选择主数据库，预期约 1 万并发用户，需要处理订单与支付的金融交易，还要支持商品全文搜索和门店定位的地理空间查询。团队对 MySQL、PostgreSQL、MongoDB 都有经验。候选方案是 PostgreSQL、MySQL、MongoDB，请列出决策驱动因素、逐项优缺点、最终决策与后果。

第 5 步：检查输出是否完整 合格输出应包含：状态、背景、决策驱动因素、考虑选项（每个选项的优缺点）、决策、原理（编号说明）、后果（正面/负面/风险及缓解）、实现注释、相关决策、参考资料。特别注意“负面后果”和“风险缓解”两段不能为空——这是判断一份 ADR 是否诚实的核心。

第 6 步：走审查流程并归档 按技能提供的三段式清单过审，至少两名高级工程师确认。批准后将文件按 NNNN-title.md 命名放入 docs/adr/，并在索引 README 中登记编号、标题、状态、日期。

第 7 步：维护与迭代 日后决策变化时，不要修改已接受的 ADR，而是新建一份替代型记录（如“ADR-0020：废弃 MongoDB，转用 PostgreSQL”），在其中链接被替代的编号，并把旧记录状态改为“已废弃”。这样整条决策链就是可追溯的。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
架构决策记录Skill（本技能） AI 驱动的 ADR 方法论与模板库 5 套 ADR 模板、写不写判断表、生命周期、目录索引规范、审查清单、最佳实践 需支持 Skill 机制的 AI 客户端，安装后自然语言调用；配套 adr-tools 可选 从零建立决策流程、快速产出高质量 ADR 草稿 优势：给的是“判断 + 结构 + 流程”，产出即可评审；不足：仍需人工审查与组织落地，无法替代团队共识
adr-tools（命令行工具） ADR 文件的机械化管理 adr init 初始化、adr new 新建与编号、adr new -s 建立替代关系、adr generate toc 生成目录 需通过包管理器安装（如 brew install adr-tools），有命令行基础 已有 ADR 习惯、需要批量维护编号与索引的团队 优势：编号、链接、索引自动化程度高；不足：不生成内容，模板质量取决于团队自己维护的 template.md
通用文档平台（Confluence / Notion 等）自建模板 通用协作文档 富文本编辑、权限、评论、页面树、搜索 低，几乎零学习成本 非技术文档混杂、需要与产品文档同处一地 优势：协作与检索体验成熟；不足：缺少 ADR 专用结构，容易写成散文；决策状态、替代关系需人工维护，难以形成决策链
架构描述框架（如 arc42、C4 模型类工具） 系统性架构文档 分层描述系统上下文、构建块、运行时视图、部署视图 中高，需学习框架语汇 需要完整架构说明书、对外交付场景 优势：全局视角完整；不足：侧重“系统长什么样”，对“为什么这样选、否决了哪些方案”的记录较弱，与 ADR 是互补而非替代关系

选型建议：要“写出有质量的决策内容”选本技能；要“管住编号和索引”配 adr-tools；要“和产品文档放一起”用通用文档平台但要强约束模板；要“完整架构说明书”再叠一层 arc42 类框架。

该技能的典型应用场景与实际体验情况

场景一：后端架构师做数据库选型 痛点：评审会上各说各话，最后靠“谁声音大”定案，散会后无人记得否决理由。 用法：用 MADR 模板生成完整 ADR，把决策驱动因素（ACID 合规、复杂查询、全文搜索、团队熟悉度）显式列出，三个候选逐项列优缺点。 体验：上手几乎零成本，输出直接可用于评审。注意：驱动因素必须自己补充真实约束（并发量、合规要求），否则 AI 只能写出通用套话。

场景二：新成员入职快速理解历史取舍 痛点：新人读代码能看懂“是什么”，看不懂“为什么”，容易提出已被否决过的方案。 用法：要求 AI 基于 docs/adr/ 索引表梳理“当前生效的架构决策清单”，并解释每条决策的替代关系。 体验：从“翻三个月聊天记录”变成“读十页索引”，理解成本显著下降。注意：前提是团队真的坚持写了 ADR，索引长期不更新则效果归零。

场景三：技术债复盘与决策推翻 痛点：三年前选型的技术前提已变化，但没人敢动，也没人说得清新旧前提差在哪。 用法：用废弃/替代模板，先对比“当初的前提”与“现在的现实”，再给出四阶段迁移计划（双写、回填、切换、退役），并附“经验教训”段落。 体验：这是五套模板中价值最高、也最容易被忽略的一套——它把“承认错误”变成了一份有结构的文档，而不是一次情绪化的复盘会。注意：迁移计划必须结合真实系统规模校准，AI 给出的周期只能作为框架参考。

场景四：从零建立团队决策流程 痛点：团队没有 ADR 习惯，不知道从哪开始、写到什么程度算合格。 用法：先用技能产出 template.md 与索引 README，再把三段式审查清单接入 PR 流程，配合 adr-tools 自动编号与生成目录。 体验：一周内即可跑通“提案 → 评审 → 归档”闭环。注意：初期容易过度记录，务必用“该写 / 可跳过”对照表约束范围，否则团队会因文档负担而放弃。

该技能能为用户带来的价值

1. 把隐性知识变成可继承资产 每份 ADR 都在回答“背景、决策、后果”三问。人员流动时，决策上下文不会随之蒸发，新人入职的理解周期从“靠口口相传”压缩到“读索引 + 读正文”。

2. 显著降低文档启动门槛 从“面对空白页不知道写什么”，到“填一份结构化骨架并补充真实约束”，单份 ADR 的起草时间从数小时量级降到十几分钟量级，且质量下限被模板托住——不会漏掉“负面后果”和“风险缓解”这两个最容易被跳过的部分。

3. 让技术评审从“观点之争”变成“证据之争” 决策驱动因素、候选方案优缺点被显式列出后，讨论焦点自然从“我喜欢哪个”转向“哪个更满足这些约束”，评审效率与结论稳定性同步提升。

4. 构建可追溯的决策链 通过“已废弃 / 已替代”状态与相关 ADR 链接，团队可以沿着编号回溯任一架构选择的完整演变史，这在合规审计、事故复盘、架构演进规划中都是高价值输入。

5. 长期价值：形成组织的决策文化 当“写 ADR”成为惯例，团队会逐渐养成“先明确约束、再比较选项、最后记录代价”的思考习惯。这份习惯本身，比任何一份具体文档都更值钱。

常见问题 FAQ

Q1：这个技能怎么安装？装了怎么确认生效？ 在支持 Skill 机制的 AI 客户端中，通过技能市场或技能目录检索技能名 architecture-decision-records（技能 ID 13249）安装，或将技能包放入客户端约定的本地技能目录。具体入口与路径以官方说明为准。 验证方法：让 AI“用 MADR 模板写一份关于引入 Redis 缓存的 ADR”，若输出包含状态、背景、决策驱动因素、考虑选项、后果等标准段落，即表示已生效。

Q2：这个技能收费吗？ 技能本身的定价与可用性取决于你所在平台的发行策略，本技能详情未包含价格信息，请以官方说明为准。技能详情中提到的 adr-tools 属于独立开源工具，其安装与授权同样以其官方说明为准。

Q3：适合谁用？小团队有必要写 ADR 吗？ 主要面向后端/平台架构师、技术负责人、Tech Lead，以及需要建立研发规范的中大型团队。小团队同样有必要，但应只用轻量级模板和 Y-Statement——一条“选了 A 不选 B、因为 C”的记录，成本不到十分钟，价值却能在半年后兑现。关键是用对照表控制范围，不要为配置变更写长文。

Q4：它和 adr-tools 是替代关系还是互补关系？ 互补。adr-tools 解决“编号、目录、替代关系、索引生成”的机械性问题；本技能解决“内容该写什么、写到什么程度、怎么审”的质量问题。推荐组合是：用技能产出内容，用 adr new -s 建立替代关系，用 adr generate toc 维护索引。

Q5：已经接受的 ADR 后来发现决策错了，能直接改吗？ 不要改。 这是技能明确强调的反模式。正确做法是新建一份替代型 ADR，在其中写明原决策的前提、现实发生的变化、迁移计划与经验教训，把旧记录状态改为“已废弃 / 已替代”，并在两份记录间建立链接。保留“错误的决策”，恰恰是 ADR 最有价值的部分——它防止团队在若干年后重蹈覆辙。