架构决策框架Skill：让每一次架构决策都有需求依据、有权衡记录、有文档可查
核心结论速览：
- 它是什么：一个面向架构决策的 AI 技能，聚焦「需求分析 → 权衡评估 → ADR 文档」三步链路，帮助你在写代码之前把设计想清楚。
- 它强在哪：不是给一个「看起来高级」的方案，而是强制你先澄清需求与约束、对每个决策做权衡分析、并在必要时产出 ADR（架构决策记录）文档。
- 它怎么用：只读型技能（工具权限限定为读取、全局搜索、Grep），不改你的代码，只帮你想清楚、写明白。
- 它适合谁：技术负责人、架构师、独立开发者，以及需要在团队内推动「有依据的技术决策」的工程团队。
- 一个前提：它信奉「简单是终极的复杂」——先简单起步，只在被证明必要时增加复杂度。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | 架构决策框架Skill |
| 英文名 | architecture |
| 技能 ID | 12251 |
| 技能定位 | 架构决策框架：需求分析、权衡评估、ADR 文档 |
| 工具权限 | 读取、全局搜索、Grep（只读型） |
它解决什么问题？
多数团队做架构决策时的真实困境不是「不会画图」，而是：
- 需求没澄清就选技术——拍脑袋上微服务、上消息队列，最后发现根本用不上；
- 决策没有权衡过程——方案对比只停留在「我觉得这个好」，说不清代价是什么；
- 决策没有留痕——半年后没人记得为什么这么设计，新人接手只能猜，改造成本极高。
架构决策框架Skill 把这些环节结构化：先用 context-discovery.md 的相关规则澄清问题与项目分类，用 trade-off-analysis.md 中的权衡框架与 ADR 模板记录决策，用 pattern-selection.md 的决策树与反模式清单选择模式，最后用验证清单逐项自查。
一键安装的思路与步骤
该技能属于「按需读取」型技能，安装的核心逻辑是：把技能包放到 AI 编程助手的技能目录中，让助手在识别到「架构决策」「系统设计分析」类请求时自动调用。具体步骤如下：
- 确认前提：你使用的 AI 编程助手/客户端需要支持自定义技能（Skill）机制，且允许技能声明工具权限。本技能声明的权限仅为读取、全局搜索、Grep，不涉及写入与执行，属于低风险技能。
- 获取技能包：通过官方技能市场、插件市场或技能仓库搜索「架构决策框架」或英文名
architecture获取。具体下载地址与版本以官方说明为准。 - 执行安装：优先使用客户端提供的「一键安装/添加技能」入口；若无该入口，则按官方文档手动将技能目录放入技能路径下。具体路径规则以官方说明为准。
- 验证是否生效：安装后在对话中提出一个架构类问题（例如「我们要做一个多租户 SaaS，数据库该共享还是隔离？」），观察助手是否按
context-discovery.md、trade-off-analysis.md等文件的选择性阅读规则组织回答；同时确认助手只做读取与检索，未提出修改代码的操作。
说明：技能文档中未提供具体的安装命令、包名或链接，上述流程为通用路径，实际操作请以官方安装说明为准。
该技能的主要功能和特点
- 需求驱动的问题澄清：内置
context-discovery.md，集中存放「该问的问题」与「项目分类」规则，避免跳过需求直接谈方案。 - 结构化权衡分析 + ADR 模板：
trade-off-analysis.md提供权衡框架与 ADR 模板，让每个关键决策都能写成「背景—选项—决策—后果」的可追溯记录。 - 模式选择决策树与反模式清单：
pattern-selection.md用决策树收敛选项，并明确列出反模式，帮你识别「看起来很对但其实有坑」的设计。 - 真实场景示例库：
examples.md覆盖 MVP、SaaS、企业三类参考实现，可直接对照自身阶段取用。 - 模式速查：
patterns-reference.md用于快速对比模式差异，适合在方案评审时即时查证。 - 选择性阅读机制：技能明确规定「只读取与请求相关的文件」，按内容映射表定位所需内容，避免一次性灌入全部上下文，回答更聚焦、更省 token。
- 与相邻技能联动：文档中标注了与
database-design（数据库模式设计）、api-patterns（API 设计模式）、deployment-procedures（部署架构）的关联，可组合成完整的架构设计链路。 - 交付前验证清单：提供 6 项检查——需求是否清晰、约束是否识别、每个决策是否有权衡分析、是否考虑了更简单的替代方案、重要决策是否写了 ADR、团队专业能力是否与所选模式匹配。
- 简单优先的设计哲学：核心原则是「简单是终极的复杂」，强调从简单开始、只在被证明必要时增加复杂度。
和普通工具比强在哪？ 普通建模工具负责「画出来」，通用 AI 对话负责「聊出来」，而该技能负责「想清楚并留痕」：它把架构工作拆成可检查的清单项，把主观判断变成可审阅的文档。
如何使用该技能？
以下为典型使用流程，可按需从任意一步切入。
第 1 步：发起架构请求，交代背景
用自然语言把问题、现状与约束说清楚。示例输入：
「我们要做一个面向中小企业的项目管理 SaaS，预计首年 200 家客户，团队 5 人，其中后端 2 人。现在要决定：数据库用共享表 + 租户字段，还是每租户独立 schema？请做权衡分析并给出 ADR。」
第 2 步：让技能先澄清需求
技能会依据 context-discovery.md 追问关键信息，例如：数据隔离是否有合规硬要求？单租户数据量级？是否允许跨租户统计？运维人力是否足够支撑多实例？
第 3 步：取得权衡分析与建议
技能依据 trade-off-analysis.md 输出多选项对比（隔离性、成本、运维复杂度、迁移难度、扩展性），并依据 pattern-selection.md 给出选择建议与需要警惕的反模式。
第 4 步：产出 ADR 文档
明确要求「写成 ADR」，技能会按模板输出结构化文档，包含：决策标题、状态、背景与约束、备选方案、最终决策、后果（正面/负面/风险）、后续复查条件。
第 5 步：对照示例库与模式速查
若不确定方案是否贴合自身阶段，可要求「对照 examples.md 里的 SaaS 示例」或「用 patterns-reference.md 对比这两种模式」。
第 6 步：过验证清单
最后要求「按验证清单逐项检查」，逐条确认需求、约束、权衡、更简单替代方案、ADR、团队能力匹配度。全部通过再进入编码阶段。
输出说明：该技能的输出以分析结论与文档为主，不产出代码改动；若需落地到数据库结构或接口设计，可继续调用关联技能。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 架构决策框架Skill（本技能） | 架构决策的分析与记录框架 | 需求澄清、权衡分析、ADR 模板、模式决策树、反模式清单、验证清单 | 低：安装后在对话中自然调用，无需学习专门语法 | 技术选型、系统设计评审、ADR 归档 | 优势：结构完整、只读安全、可追溯；不足：不产出代码、不绘图，依赖提问质量 |
| 通用对话式 AI 助手（直接提问） | 通用问答 | 能聊架构、能写文档 | 极低 | 快速获取思路 | 优势：零门槛；不足：容易跳过需求与约束，结论不稳定，难以形成一致可审阅的文档 |
| 人工白板讨论 + 会议纪要 | 团队协作决策 | 讨论、拍板、口头共识 | 中：需组织会议与关键人 | 跨团队重大决策 | 优势：共识度高；不足：无结构化的权衡记录，结论易随人员流动丢失 |
| 架构建模/图解工具 | 架构可视化 | 绘制架构图、C4 模型、依赖关系图 | 中高：需学习建模语法与规范 | 对外汇报、架构图维护 | 优势：表达直观；不足：只管「画」，不管「为什么这么设计」，决策依据仍缺失 |
选型建议：需要「想清楚 + 留证据」选本技能；需要「画出来」选建模工具；两者可组合使用——先用本技能产出 ADR 与决策结论，再用建模工具把结论画成图。
该技能的典型应用场景与实际体验情况
场景一：初创团队从 0 到 1 做 MVP 架构选型
- 角色与痛点：3-5 人小团队，后端只有 1-2 人，容易在早期被「最佳实践」带着上微服务、上服务网格，结果运维成本压垮节奏。
- 使用方式：让技能对照
examples.md的 MVP 示例做取舍，并强制回答「更简单的替代方案是什么」。 - 实际体验：上手几乎无门槛，直接把业务现状说清楚即可。效果最明显的是「被劝住」——技能会明确要求先证明复杂性必要。注意：需要你如实交代团队规模与技术储备，否则结论会失真。
场景二：SaaS 系统多租户改造决策
- 角色与痛点：技术负责人面对「共享表 vs 独立 schema vs 独立库」的经典三选一，会议上各方各执一词，谁也说服不了谁。
- 使用方式：要求输出权衡分析矩阵 + 正式 ADR，把隔离性、成本、运维、迁移风险逐项列清。
- 实际体验：最大价值是把争论从「我觉得」转到「按这几个维度算」。ADR 可直接贴进需求文档或 Wiki。注意：涉及合规与商务约束的部分需要业务方补充输入，AI 无法替你决定。
场景三：方案评审与反模式排查
- 角色与痛点：评审会上容易漏看隐患，例如分布式事务被滥用、缓存与数据库一致性问题被忽略。
- 使用方式：把待评审方案描述给技能，要求「用
pattern-selection.md的反模式清单对照检查」。 - 实际体验：能较快指出值得警惕的设计点，作为评审的检查提纲很实用。注意：它给出的是「需要确认的问题」，最终判断仍取决于具体业务数据。
场景四：决策文档补全与团队交接
- 角色与痛点：老系统改造前发现历史决策无人记录，新人只能从代码反推设计意图。
- 使用方式：把现状与已知背景输入，让技能按 ADR 模板反向补全文档，并标注「待确认项」。
- 实际体验：能显著加快文档化进程，模板结构稳定、格式统一。注意：反向补全的 ADR 中，事实性内容需要老成员核对后再定稿。
该技能能为用户带来的价值
- 决策质量提升：通过强制澄清需求与约束、强制做权衡分析，把「拍脑袋选型」转变为「有据可依的取舍」。
- 返工成本下降：把问题暴露在设计阶段而非上线之后。架构层面的返工通常代价最高，前置一轮结构化分析即可覆盖大量低级决策失误。
- 沟通成本降低：ADR 作为统一载体，让产品、后端、运维在同一份文档上讨论，减少「各自理解」带来的偏差。
- 知识资产沉淀：每次重要决策都留下背景与后果说明，人员流动时决策依据不丢失，新人上手时间显著缩短。
- 使用门槛极低：无需学习建模语法或专门工具，用自然语言描述问题即可获得结构化产出；选择性阅读机制让回答聚焦，不浪费上下文。
- 安全边界清晰：工具权限仅为读取、全局搜索、Grep，不会修改代码库，可以放心在真实项目中反复使用。
- 长期复利：随着 ADR 积累，团队会形成自己的决策模式库，「什么样的团队规模该选什么样的架构」逐渐从经验变成可复用资产。
常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
A：通过官方技能市场或技能管理入口搜索中文名「架构决策框架」或英文名 architecture，使用一键安装入口添加即可；具体安装命令、路径与是否收费以官方说明为准。该技能权限为只读（读取、全局搜索、Grep），安装前可先确认客户端的技能权限提示。
Q2：它和直接问 AI「帮我设计一个架构」有什么区别？
A：直接问往往一步到位给出方案，跳过了需求澄清与权衡过程；本技能内置需求澄清（context-discovery.md）、权衡框架与 ADR 模板（trade-off-analysis.md）、模式决策树与反模式清单（pattern-selection.md），并有 6 项验证清单兜底，产出更接近一份可评审、可归档的决策文档。
Q3：它会修改我的代码或数据库吗？
A：不会。技能声明的工具权限只有读取、全局搜索、Grep，属于只读分析型技能，输出以分析结论与 ADR 文档为主。
Q4：适合哪些人用？小团队用得上吗？
A：适合技术负责人、架构师、独立开发者与工程团队。小团队反而更受益——技能核心原则是「简单是终极的复杂」，会主动提醒你考虑更简单的替代方案，避免过早引入复杂度。
Q5：和架构建模工具、通用 AI 助手怎么选？
A：需要「想清楚并留下决策依据」选本技能；需要「画图汇报」选建模工具；只想快速聊个思路用通用 AI 助手即可。实践中最优组合是：先用本技能产出权衡分析与 ADR，再用建模工具把结论可视化，最后用通用助手做文档润色。