Semantic Kernel 架构决策记录（ADR）体系：基于 MADR 模板的跨语言决策流程与实践
【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel
本文深入解析 Semantic Kernel 项目用于管理架构决策的记录体系——采用 MADR（Markdown Any Decision Records）轻量模板，在仓库内以docs/decisions/目录沉淀全部技术决策。文章将完整还原该体系的决策驱动、模板字段、五步操作流程与真实案例，帮助读者理解一个同时维护 C#、Python、Java、TypeScript 多语言实现的 SDK 项目，如何通过"文档 + Git 评审"的机制保证架构决策跨语言对齐、可追溯、可演进。
背景：多语言并行开发下的架构一致性难题
Semantic Kernel 在 dotnet/、python/、java/ 等多个目录下并行维护着不同语言版本。正如 ADR-0001 的上下文所述，这种多语言并行模式带来一个核心挑战：关键架构决策一旦变更，必须在所有语言实现中同步反映。
文档中举了一个非常典型的例子：当时团队正在评审"语义函数配置（config.json）存储格式"的变更，一旦该变更被批准，就必须同步落实到所有 Semantic Kernel 实现中。如果没有一套正式的记录与评审机制，这种跨语言对齐极易出现遗漏或偏差。因此，项目需要一种结构化方式来捕获决策，并让"谁在什么时候、基于什么理由、做出了什么决定"对社区完全透明。
什么是 MADR：轻量化的架构决策记录模板
MADR 是一套起源于架构决策捕获、后发展为可记录任意决策的轻量模板，由 ADR 社区推广（docs/decisions/README.md中亦有介绍）。其核心理念是：一条架构决策记录（ADR）只捕获一个架构上重要的设计决策及其论证理由。
一个标准的 MADR 文档由以下章节构成（详见 adr-template.md）：
| 章节 | 作用 |
|---|---|
| Front matter 元数据 | 以 YAML 形式记录status、contact、date、deciders、consulted、informed等状态与参与者信息 |
Context and Problem Statement | 用两三句话（或叙事形式）描述决策的上下文与要解决的问题 |
Decision Drivers | 列出影响决策的驱动因素，如约束、关注点、技术压力 |
Considered Options | 枚举所有被考虑过的备选方案 |
Decision Outcome | 明确"选中的方案"及理由，可附正面/负面后果 |
Validation | 描述 ADR 如何被验证（如通过评审或自动化测试） |
Pros and Cons of the Options | 对每个备选方案逐条列出 Good / Neutral / Bad 论证 |
More Information | 补充证据、团队共识、决策落地与复审时机等附加信息 |
除此之外，仓库还提供一份 adr-short-template.md 短模板，仅保留核心的 front matter 与 Context、Decision Drivers、Considered Options、Decision Outcome 章节，适合轻量快速的决策记录。
Semantic Kernel 的 ADR 决策流程（核心工作流）
ADR-0001 明确给出了"如何使用 ADR 追踪技术决策"的完整流程，这也是本仓库至今沿用的操作规范：
- 创建文档：将 docs/decisions/adr-template.md 复制为
docs/decisions/NNNN-title-with-dashes.md，其中NNNN为递增序号。- 复制前需检查现有 PR，确保序号不与在途的决策冲突；
- 如需精简记录，可改用短模板 docs/decisions/adr-short-template.md。
- 编辑文档内容：
status初始必须为proposed；deciders列表必须包含所有对该决策签字确认的人员 GitHub 账号；- 相关 EM（工程经理）和架构师
dluc必须被列为 deciders 或 informed（参与知会）； - 所有参与决策咨询的伙伴应列入
consulted；注意保持deciders列表精简，其余人员放入consulted或informed（见 docs/decisions/README.md）。
- 论证每个选项：对每个被考虑的备选方案，列出其 good、neutral、bad 三个方面；详细的调研结论可放入
More Information章节，以内联内容或外部文档链接形式呈现。 - 通过 PR 分享并评审：
- deciders 必须被列为 required reviewers；
- 决策达成一致后，将
status更新为accepted，并同步更新date； - 决策的批准通过 PR approval 捕获，评审与批准过程完全走标准 Git 评审流程。
- 允许后续演进：决策可被后续新 ADR 取代（superseded）。此时建议在原 ADR 中记录任何负面结果，为后来者提供经验。
Front matter 字段详解
adr-template 的 front matter 是可选的，但提供了完整的字段语义（见 adr-template.md）：
| 字段 | 含义与取值 |
|---|---|
status | proposed（提议中）|rejected（已拒绝）|accepted（已接受）|deprecated（已弃用）|…|superseded by ADR-0001（被某条 ADR 取代并链接到对应文档） |
contact | 提出该 ADR 的人 |
date | 决策最后更新的日期，格式YYYY-MM-DD |
deciders | 参与决策并签字确认的所有人（列表保持精简） |
consulted | 被征求意见的人（通常是领域专家），双方有双向沟通 |
informed | 需被同步进展的人，单向信息知会 |
在真实记录中，这些字段的用法与 ADR-0002 的 front matter 完全一致：
--- status: accepted date: 2013-06-19 deciders: shawncal,johnoliver consulted: informed: ---仓库中的真实 ADR 案例：从模板到实践
截至当前仓库，docs/decisions/目录下已沉淀80 份决策文档，编号从 0001 到 0073（存在少量同号文档，如 0021、0023、0025、0046、0051、0072 各两条），内容覆盖函数调用、错误处理、内核 Hook、Agent 体系、向量存储、流程编排（Processes）、MCP 集成、文本搜索等方方面面。它们是理解 ADR 体系如何运转的最佳教材。
案例一：跨语言目录结构决策（ADR-0002）
0002-java-folder-structure.md 记录 Java 移植版的目录结构决策。它先给出 .NET 与 Java 两种目录结构对比表，再逐条分析差异，最终得出决策：文件夹命名与 .NET 对齐但采用 Java 惯用的小写连字符风格、用bom替代 .Net 的MetaPackage、用api替代Abstractions、统一使用plugins术语取代skills以避免技术债，并要求功能状态在仓库根目录的 FEATURE_MATRIX.md 中跟踪。这个案例展示了 ADR 如何通过决策驱动 + 选项对比 + 明确结论三个环节，把多语言一致性这种抽象目标落到可执行的工程规范上。
案例二：决策被后续 ADR 取代（superseded 机制）
ADR 体系并非一锤定音。仓库中有多条 ADR 被后续决策取代，这正是 ADR-0001 第五步"决策可被后续 ADR 取代"的实践印证：
- 0015-completion-service-selection.md 的 front matter 标注为
status: superseded by [ADR-0038](https://link.gitcode.com/i/31ba85e4a8c03027da07a2484145e44d)； - 0006-open-api-dynamic-payload-and-namespaces.md 被 0062-open-api-payload.md 取代；
- 0010-dotnet-project-structure.md 被 0042-samples-restructure.md 取代。
通过superseded by链接，读者可以沿决策的"版本历史"追溯：某条决策何时诞生、因何被推翻、新方案是什么，形成完整的决策演化链。
案例三：状态流转的完整样本（proposed → 独立仓库）
0046-java-repository-separation.md 以status: proposed记录了"将 Java 代码库分离为独立仓库"的决策：文中详细论证了 Maven 发布流程与共享仓库的冲突（冻结提交、squash 合并限制）、多语言仓库在可发现性上的问题（大部分 PR/Issue 与其他语言相关）、公共文件（CI 工作流、.gitignore、README.md等）维护复杂度，以及独立仓库对社区参与度的促进。这条 ADR 后来已落地——当前仓库的 java/ 目录仅保留 README，Java 实现迁移至独立仓库。这展示了 ADR 从proposed到被采纳、并真正驱动工程组织变革的完整生命周期。
为什么选 MADR：方案权衡
ADR-0001 的决策驱动主要有两条：
- 架构变更及其决策过程应对社区透明；
- 决策记录存放于仓库内，便于各语言移植团队发现与查阅。
对应的采纳理由（Pros）：
- 轻量易编辑：纯 Markdown 格式，无需额外工具链，任何人都能直接修改；
- 复用标准 Git 评审流程：评论、审批、合并全部走 PR，评审留痕，无需自建流程；
- 过程透明：决策与评审过程对社区完全可见，外部贡献者也能理解"为什么这么设计"。
代价（Cons）方面，原文档未列明明显的负面因素；但从仓库实践可以推断，其隐含成本是：每位贡献者都需要遵守模板纪律——新增决策必须先复制模板、保持编号唯一、维护 status 状态流转，否则目录会逐渐失序。这也是 docs/decisions/README.md 将操作步骤固化下来的原因。
一套可复用的决策管理实践
综上，Semantic Kernel 的 ADR 体系本质上是把"架构决策"当作一等工程制品来管理，其要点可归纳为：
- 模板化：以 adr-template.md 为骨架，强制作者交代上下文、驱动因素、备选方案与结论，杜绝"拍脑袋"决策；
- 流程化：
proposed → accepted的状态流转绑定 Git PR 评审，决策批准即 PR 批准，留痕可审计； - 跨语言对齐：每一条决策都对 C#、Python、Java、TypeScript 各实现生效，
docs/decisions/目录就是各语言团队的"共同决策公约"； - 可演进：
superseded机制允许决策被推翻与迭代，历史结论与新结论并存，形成完整的决策时间线。
对于任何需要多语言/多团队协同、且希望把架构决策讲清楚、查得到的项目，这套基于 MADR 的实践都值得直接借鉴——入口就是本仓库的 docs/decisions/README.md 与 ADR-0001。
【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
