architecture-decision-record 项目解析：适应度函数（Fitness Function）如何把架构决策变成可自动验证的代码

【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载架构决策记录Architecture Decision RecordADR解决了把决策写下来的问题但写下来的决策如何确保团队真的在遵守本篇文章以 architecture-decision-record 仓库中的《Fitnessfunktioner for beslutninger som kode》决策即代码的适应度函数文档为核心讲解 fitness function 的核心概念、与 ADR 的分工、四大实战价值、基于 AI 大语言模型的检查提示词以及 ArchUnit / ArchUnitTS 等架构单元测试工具。读完你就能在自己的项目中把每一条架构决策固化成随每次提交与构建自动运行的客观检查。什么是决策即代码的适应度函数原文档给出一个精炼的定义适应度函数fitness function是用编程代码编写的一种客观、自动化的检查用于验证一项决策是否仍然被遵守。这个定义有三个关键限定词客观objektiv检查结果只有通过 / 失败两种状态不依赖评审者的主观印象自动化automatiseret检查以代码形式存在可以挂接到持续集成CI流水线中无需人工触发针对决策for beslutninger它验证的不是代码风格或单元行为而是我们当初做出的架构决策是否仍然成立。原文档同时指出两条直接收益适应度函数让决策变得可测试、可保证testbare og kontrollerbare并且对**质量保证kvalitetssikring、合规流程regulatoriske processer和治理目标governance-mål**有显著帮助。在 architecture-decision-record 仓库中这篇文章是英文源文档 fitness-functions-for-decisions-as-code 的丹麦语翻译丹麦语版本同时被收录进仓库根 README.md 的 Fitness functions for decisions as code 章节见 README.md并作为 12 篇核心文档之一在 spec/content.md 中被明文列出。如果你想阅读同主题的中文版本仓库还提供了 《将决策作为代码的适应度函数》 等 30 种语言的译文方便对照学习。适应度函数与 ADR 的分工文档记录决策代码执行决策原文档用一个非常简洁的公式定义了二者关系决策记录ADR负责记录决策适应度函数负责**执行håndhæver**决策。文档中的成对示例如下决策示例为满足审计要求我们采用事件溯源event sourcing适应度函数示例我们使用持续集成服务器来测试所有状态变更都必须产生事件。也就是说ADR 回答我们决定怎么做、为什么这么做而 fitness function 回答系统是否仍然按这个决定在运行。二者的角色差异可以归纳为下表维度决策记录ADR适应度函数Fitness Function形态人读的 Markdown 文档机器执行的程序代码作用记录决策及其背景、后果验证决策是否仍被遵守时效决策时刻的一次性产物可追加修订随每次 commit / build 持续运行的活规则判定靠人工评审与理解通过 / 失败的客观结果典型落点adr/或decisions/目录单元测试、CI 脚本、架构测试仓库中为记录决策这一半提供了大量模板例如 Michael Nygard 模板Title / Status / Context / Decision / Consequences 五段式以及 MADR 项目模板强调备选方案及利弊而执行决策这一半正是本篇文档的主题。仓库的 writing-guide.md 也把Fitness functions — making a decision testable, not just documented让决策可测试而不只是被记录单列为一节与本文档内容相互印证。为什么适应度函数有助于决策落地原文档给出四个核心理由逐一展开如下1. 客观度量工作结果清晰可见适应度函数要么通过、要么失败不存在模糊地带。相比代码评审时口头提醒大家遵守某某约定一条自动化检查给出的是确定的布尔结果任何人都能一眼看到当前系统是否满足决策要求团队工作状态变得透明。2. 持续使用随每次提交与构建运行的活规则适应度函数不是一次性审计而是常驻的规则——每次 commit、每次 build 都会执行。这意味着决策的遵守不是靠记忆或自觉而是靠流水线强制。这与本仓库自身的工程实践是同一思路仓库通过 scripts/audit-locales.py 把每个语言目录必须与英文源 en-001 完全对齐205 个文件、README.md 必须是 index.md 的软链接、所有相对链接与锚点必须可解析这一内容治理规则写成了可自动执行的检查并在 .github/workflows/ci.yml 中配置为每次 push 和 pull request 都运行。从源码结构看这正是一个针对内容同步决策的 fitness function 实例。3. 重构的信心自动捕获违反决策规则的错误重构时最怕结构变了但没人意识到某条决策被悄悄破坏。适应度函数会在重构代码的构建阶段自动发现此类偏差并让流水线失败把事后发现变成提交时发现为持续演进提供安全网。4. 可扩展的治理不制造瓶颈地保证标准人工审批会随着规则数量增长而成为瓶颈自动化检查则可以无限扩展——每条决策对应一条检查规则越多流水线越严格却不需要增加任何人力评审环节。这让治理从人的流程转变为代码的流程。用 AI 大语言模型充当适应度函数完整提示词原文档明确回答了适应度函数可以使用 AI 吗——可以。思路是让 AI 大语言模型针对我们的工作成果计划、代码、模式、API 等提出检查性问题从而充当一条广义的适应度函数。文档给出了可直接复用的完整提示词模板IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search. This is a fitness function to evaluate if our work is using all our decisions, and is correct and accurate. - Our decisions are here: {url} - Our work to evaluate is here: {url} Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.这份提示词可以从四个层面理解方便你按需调整推理模式指令前两行要求模型优先基于检索的推理而非基于预训练记忆的推理并开启扩展思考extended thinking、专家建议expert advice和搜索search能力——本质上是要求模型把决策文档和工作产物当作证据来源而不是凭训练语料里的泛化知识作答角色声明第三至五行明确这是一条评估我们工作是否使用了全部决策、是否正确且准确的 fitness function输入占位{url}需要替换为两处真实地址——决策存放处如 ADR 目录或文档链接与被评估的工作产物如 PR 变更、设计文档、API 契约输出要求最后一行要求模型直接、果断地指出错误、问题、缺口与弱点避免含糊其辞。同一份提示词也原样收录在 writing-guide.md 中说明它是仓库推荐的、经过项目团队验证的通用形态可以直接粘贴使用或在此基础上扩展。架构单元测试ArchUnit 与 ArchUnitTS当决策本身是代码的架构形态时例如分层依赖、包边界、禁止某类循环引用最自然的实现方式是把 fitness function 写成架构单元测试。原文档推荐了两个工具ArchUnitJava使用任何普通的 Java 单元测试框架如 JUnit来检查 Java 代码的架构规则。它把分层不得反向依赖领域层不得引用基础设施层这类规则写成可断言的测试随测试套件一起在 CI 中执行。下面是一段通用示意非本仓库代码具体 API 以工具当前版本为准// 示意用 ArchUnit 在 JUnit 中声明一条架构规则 AnalyzeClasses(packages com.example.app) public class ArchitectureRulesTest { Test void domain_should_not_depend_on_infrastructure() { noClasses().that().resideInAPackage(..domain..) .should().dependOnClassesThat().resideInAPackage(..infrastructure..) .check(new ClassFileImporter().importPackages(com.example.app)); } }ArchUnitTSTypeScript / JavaScript使用 Jest、Vitest、Jasmine 等测试框架检查 TypeScript 与 JavaScript 代码的架构规则为前端与 Node.js 项目提供同样的能力。它同样把架构约束表达为测试用例例如某个目录下的模块不得 import 另一个目录的模块失败即让测试套件报错。把这两类工具与前述 AI 提示词放在一起看可以梳理出一条完整的决策即代码落地路径能用确定性代码表达的架构决策 → 写成 ArchUnit / ArchUnitTS 之类的架构单元测试难以用代码表达的开放性决策如计划、文档、API 设计是否与全部决策一致→ 用 AI 提示词充当柔性检查。两者都挂进 CI就构成了既有硬约束又有软校验的双层保证。在本仓库中的落地路径与相关资源如果你希望基于本仓库进一步实践决策即代码可以从这几处切入阅读原文英文源文档 fitness-functions-for-decisions-as-code 与中文译本 《将决策作为代码的适应度函数》 内容完全对应适合对照研读查看集成位置根 README.md 的 Fitness functions for decisions as code 章节README.md把该主题与决策记录模板决策生命周期架构图与视图等内容并列帮助你理解它在整套 ADR 方法论中的位置结合相邻机制紧跟在 fitness functions 章节之后README 还介绍了Decision guardrails for pull requests见 README.md即 ADR Guard 之类的工具在 pull request 阶段自动拦截改动了受保护代码却未新增或更新 ADR的情况并支持显式的ADR-Exempt:豁免行——这是决策执行在代码评审环节的另一种自动化形态与本文主题形成互补复用 AI 检查提示词skills 目录下的 writing-guide.md 收录了同样的 fitness function 提示词说明该项目已把这一实践固化到面向 AI 编码代理的写作指南中可作为团队内部约定直接采用参考示例与模板仓库 示例目录 中有 40 个 ADR 实例如 环境变量配置、事件溯源相关的时间戳格式 等模板目录 提供 11 种决策记录模板可用来补齐记录决策这一半。需要提醒的是本文所述 fitness function 属于通用软件工程实践不同工具ArchUnit、ArchUnitTS的 API 与版本差异较大在关键系统中使用前请自行核验工具文档与项目实际情况这也是仓库 README 中明确给出的注意事项。总结一句话概括本文档的核心主张ADR 负责把决策写下来fitness function 负责让决策被执行。通过客观度量、随构建持续运行、为重构提供信心、以代码实现可扩展治理这四个价值点适应度函数把架构决策从纸面文档变成了可测试、可保证的工程资产。对于无法用确定性代码表达的开放性决策还可以借助 AI 大语言模型提示词充当柔性检查——原文档提供的完整提示词模板可以直接投入实战。结合 ArchUnit / ArchUnitTS 等架构单元测试工具你就能在 CI 中建立硬规则 软校验的双层决策保障体系。赞分享【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载相关推荐HCCL 集合通信算法全解Server 内 / Server 间 / 超节点间算法选型、HCCL_ALGO 配置与分级通信原理HCCL 集合通信算法全解Server 内 / Server 间 / 超节点间算法选型、HCCL_ALGO 配置与分级通信原理 集合通信算法是决定集群通信性能电视盒子变 Linux 服务器Armbian 移植实操指南电视盒子变 Linux 服务器Armbian 移植实操指南 amlogic s9xxx armbian 是一个开源项目可以把 Armbian基于 Debi从架构决策到代码实现architecture-decision-record的完整落地流程从架构决策到代码实现architecture decision record的完整落地流程 架构决策记录Architecture Decision Reco上一篇【亲测免费】 rCore-Tutorial-v3 开源项目指南下一篇MoA项目快速入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考