Semantic Kernel 架构决策记录（ADR）体系：基于 MADR 模板的跨语言决策流程与实践

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 项目用于管理架构决策的记录体系——采用 MADRMarkdown 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初始必须为proposeddeciders列表必须包含所有对该决策签字确认的人员 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字段含义与取值statusproposed提议中|rejected已拒绝|accepted已接受|deprecated已弃用|…|superseded by ADR-0001被某条 ADR 取代并链接到对应文档contact提出该 ADR 的人date决策最后更新的日期格式YYYY-MM-DDdeciders参与决策并签字确认的所有人列表保持精简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-00020002-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/ 目录仅保留 READMEJava 实现迁移至独立仓库。这展示了 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），仅供参考