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

架构决策记录技能：让每个技术决策都有据可查

它是什么：adr-architecture（架构决策记录技能Skill）是一个专注于生成、校验和归档架构决策记录（ADR）的 AI 技能，技能 ID 为 13017。
解决什么问题：团队做完技术选型后，决策原因常散落在聊天记录、会议纪要和口头讨论中；几个月后没人说得清“为什么不用 MySQL”“为什么选 PostgreSQL”。
核心能力：按标准 ADR 结构输出上下文、决策、替代方案、后果和状态，并用质量评分标准做自检，强调诚实记录权衡而不是只写优点。
怎么用：在支持 AI 技能的平台中安装启用后，用“ADR”“架构决策”“记录此决策”等触发短语调用，按步骤填写真实约束并归档到 docs/adr/。
适合谁：后端团队、架构师、技术负责人、平台工程团队，以及需要做技术标准、系统迁移、基础设施选型和新人知识传承的团队。

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

该技能的中文名为架构决策记录技能Skill，英文名为 adr-architecture，技能 ID 为 13017。它要解决的问题很具体：当团队做出重要技术或架构决策时，把“当时为什么这样选、还考虑过什么、代价是什么”完整记录下来，形成可追溯的决策日志。

它适合在以下时机调用：技术选项选择、基础设施决策、标准建立、系统迁移、安全或合规选择，以及团队需要了解决策原因时。技能详情中给出的触发短语包括“ADR”“架构决策”“记录此决策”“为什么我们选择”“决策记录”“技术决策日志”等。

关于下载安装，技能详情中没有提供具体的安装命令、下载链接或价格信息，因此这里只能给出通用思路，具体入口、命令和收费方式请以官方说明为准。通常可以按以下步骤操作：

确认安装前提：你已经拥有支持 AI 技能的平台或客户端账号，并具备当前项目的文档目录读写权限；如果团队要共享 ADR，还需要有代码仓库或文档库的协作权限。
找到技能入口：在平台的技能市场、技能管理页或技能配置入口中搜索英文名 adr-architecture、中文名“架构决策记录技能”或技能 ID 13017。
安装并启用：按平台提示完成安装或启用。所谓“一键安装”，是相对手动编写提示词、手动维护模板而言：安装后技能会自带 ADR 工作流程、模板说明、示例和质量评分标准。
验证是否生效：安装后发起一次测试对话，例如输入“请帮我创建一个 ADR，记录我们选择 PostgreSQL 作为主数据库，要求包含上下文、替代方案和后果”。如果输出包含状态、日期、决策者、上下文、决策、考虑的替代方案、后果等结构，说明技能已生效。
接入项目归档规范：确认团队 ADR 存放位置，技能详情建议存放在 docs/adr/ 或 architecture/decisions/ 目录，并按顺序编号。

2. 该技能的主要功能和特点

结构化 ADR 生成：围绕“上下文、决策、替代方案、后果、状态”组织内容，避免只写一句“我们决定用某某技术”。
模板与复杂决策方法支持：技术选型可参考 resources/template.md；多个相互依赖选择的复杂架构决策可学习 resources/methodology.md。
示例参考：技能详情列出数据库选型、微服务迁移、API 版本管理等示例，帮助用户理解不同决策类型该怎么写。
质量自检：使用 resources/evaluators/rubric_adr_architecture.json 自检，最低标准为得分不低于 3.5；争议大或影响高的决策建议目标 4.5 以上。
常见模式指导：针对技术选择、架构更改、标准和约定、弃用等场景给出不同记录重点，例如架构更改要写迁移策略、向后兼容性和回滚计划。
护栏约束：强调诚实描述权衡、为未来读者写作、包含具体技术细节、每个决策一个 ADR、旧 ADR 不直接改写而是用新 ADR 取代。
归档与命名规范：建议使用 adr-{number}-{short-kebab-case-title}.md 命名，例如 adr-042-use-postgresql-for-primary-database.md。

和普通文档工具相比，它的差异不在于“能写文档”，而在于强制把决策质量写出来：普通工具只提供容器，通用 AI 容易只给结论，而这个技能要求记录替代方案、缺点、风险和后续影响。

3. 如何使用该技能？

建议按技能详情中的五步工作流程使用：

了解决策：先向技能说明要做什么决策、为什么现在做、谁决策、有什么约束（预算、时间线、团队技能、合规要求）、有哪些功能和非功能要求、影响范围是一个服务还是整个组织。
选择模板：技术选型类决策使用标准模板；复杂架构决策参考方法论文件；需要找感觉时先看示例。
记录决策：让技能创建 adr-{number}-{short-title}.md，并填写标题、元数据（状态、日期、决策者）、上下文、决策、替代方案、后果、实现笔记和相关 ADR 链接。
验证质量：用评分标准自检，重点检查上下文是否解释“为什么”、决策是否具体可执行、是否有 2—3 个以上替代方案及权衡、后果是否同时写了好处和缺点。
交付和归档：把完成的 ADR 放入 docs/adr/ 或 architecture/decisions/，按顺序编号；高风险决策建议进入评审流程。

一个可直接参考的输入示例：

请用 ADR 记录：我们决定新微服务平台的主数据库使用 PostgreSQL 15+。背景是启动时需要支撑 10k+ QPS，要求 ACID 事务和复杂查询。请对比 MySQL、MongoDB、CockroachDB，并写清楚优缺点、风险和后续扩展限制。

期望输出应包含：ADR 编号与标题、状态“已接受”、日期、决策者、上下文与要求、明确决策、考虑的替代方案及不选原因、后果中的优点与缺点、相关实现或迁移注意事项。若决策有争议，还可以要求技能按评分标准给出自检结果和改进建议。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
adr-architecture（架构决策记录技能）	专注 ADR 生成的 AI 技能	结构化模板、替代方案与后果记录、质量评分、常见模式、归档命名建议	需在支持技能的平台安装启用；具体以官方说明为准	技术选型、基础设施、标准建立、系统迁移、新人决策历史查询	优势是结构完整、强调权衡和自检；不足是仍需用户提供真实上下文，不能替代团队评审
手工维护 ADR 模板	传统文档实践	提供 Markdown 模板，团队自行填写	门槛低，复制模板即可	已有文档规范、决策频率不高的团队	优势是灵活、无平台依赖；不足是容易写成“结论+优点”，替代方案和缺点常被省略
通用 AI 对话助手	通用内容生成	可对话生成架构说明、方案对比	使用门槛低	快速起草、头脑风暴	优势是通用性强；不足是缺少固定 ADR 流程、质量评分和归档约束，容易输出泛泛而谈的内容
Confluence / Notion 等文档协作平台	团队知识库与文档协作	页面编辑、评论、权限、搜索	需团队开通和配置空间	文档集中管理、跨团队评审	优势是协作和检索能力强；不足是本身不强制 ADR 结构，决策质量依赖作者经验

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

场景一：后端团队数据库选型。 团队要在 PostgreSQL、MySQL、MongoDB 之间做选择，痛点是会上讨论很久，会后只留下一句“用 PostgreSQL”。使用该技能时，把 QPS、事务要求、团队经验、扩展预期输入进去，技能会输出包含替代方案和后果的 ADR。实际体验是上手难度低，但输入越具体，输出越有价值；如果只说“帮我选个数据库”，结果会偏泛。

场景二：平台团队微服务迁移。 迁移涉及拆分边界、通信方式、部署策略等多个相互依赖的决策。技能详情建议复杂决策参考方法论文件，并在后果中写迁移策略、向后兼容性和回滚计划。实际使用时要注意：一个 ADR 只记录一个决策，不要把拆分、数据库、消息队列全塞进一篇。

场景三：架构委员会建立 API 版本标准。 标准类决策容易写成口号。该技能要求写清楚标准在实践中的示例、例外或逃生舱口、执行机制和培训影响。实际体验是它能把“我们统一用 v1/v2 路径版本”扩展成可执行的约定，但标准是否合理仍需委员会评审。

场景四：新成员入职了解历史决策。 新人常问“为什么不用某某框架”。有了按编号归档的 ADR，可以直接检索决策历史。实际体验是长期价值明显，但前提是团队坚持归档，并且旧决策被取代时写新 ADR 而不是偷偷改旧文档。

总体体验：技能上手门槛不高，输出结构完整，尤其适合把口头讨论转成文档；注意事项是必须提供真实约束和技术细节，质量评分不能代替人工评审，争议大的决策仍应走团队评审流程。

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

第一，把决策过程沉淀下来。ADR 记录的不只是“选了什么”，还包括上下文、替代方案、权衡和后果，帮助团队在数月甚至数年后仍能理解决策的“为什么”。

第二，减少重复争论和沟通成本。当新人或跨团队同事质疑某个技术选择时，可以直接指向 ADR，而不是重新翻聊天记录、会议纪要或依赖口口相传。

第三，提升文档质量下限。技能内置模板、示例、常见模式和质量评分标准，能减少“只写优点不写缺点”“没有替代方案”“后果模糊”等常见问题。

第四，降低知识传承门槛。决策日志按 docs/adr/ 归档并顺序编号，形成可检索的架构记忆，对新人入职、架构评审和合规审计都有长期价值。

第五，提高决策记录效率。原本需要会后整理纪要和反复补文档的工作，可以转化为一次结构化对话；虽然不能量化成固定节省比例，但能明显减少从“讨论结束”到“文档可查”之间的时间。

7. 常见问题 FAQ

问：这个技能怎么安装？收费吗？
答：在支持 AI 技能的平台中搜索 adr-architecture、中文名或技能 ID 13017，按平台入口安装启用即可。技能详情未提供具体安装命令和价格信息，收费方式、可用平台和安装步骤请以官方说明为准。

问：它适合谁用？小团队有必要吗？
答：适合后端团队、架构师、技术负责人、平台工程团队，以及需要做技术选型、基础设施决策、标准建立和系统迁移的团队。小团队同样有必要，尤其是人员流动较快时，ADR 能避免“人走决策原因也走”。

问：它和直接让通用 AI 写一篇架构文档有什么区别？
答：通用 AI 更擅长快速起草，但容易缺少固定结构和质量约束。该技能围绕 ADR 的五要素组织内容，要求写替代方案、后果和缺点，还提供质量评分自检与归档命名建议，更适合正式决策记录。

问：技能能保证决策一定正确吗？
答：不能。它保证的是记录结构和记录质量，帮助团队把权衡写清楚；技术判断是否正确仍取决于输入信息、团队经验和评审过程。争议大或影响高的决策，建议按技能提示进行评审，并追求更高的质量评分。

问：旧 ADR 写错了能直接修改吗？
答：技能护栏建议保持 ADR 内容不变，状态可以变更；如果需要推翻旧决策，应写一篇新的取代 ADR，并链接到被取代的旧 ADR。这样决策历史才是可追溯的。