本文由 InfoQ 认证架构师在线课程的学员撰写，是其学习成果的集大成之作，反映了学员群体在 AI 与现代软件架构交叉领域的集体学习心得。
代码已成商品，对齐仍是难题
生成式 AI 大幅降低了编写代码所需的工作量，快速原型设计也变得越来越普遍。因此，如今软件开发生命周期的瓶颈已转变为组织将创意转化为匹配自身能力的成果并在整个系统中保持凝聚力的能力。
图 1. 来源：Eduardo Da Silva，经授权使用
一直以来，组织一直依赖人工流程与人工监督来保障架构的一致性。初创企业依靠核心技术人员捕捉架构设计与实际落地之间的偏差；大型企业则试图通过变更管理委员会、不断补充的 ADR（架构决策记录）及相关文档来维持架构凝聚力。但在这两种模式下，偏差的识别都十分缓慢，因为都需要同步依赖中心化的权威决策。对初创企业而言，开发团队需要等待忙碌的核心专家；对大型企业而言，则需要等待评审委员会审批，并在大量文档化规范中进行筛选，还往往面临内容已过时的问题。生成式 AI 进一步加剧了这一矛盾：以往开发者需要数天甚至数周才能完成代码编写，如今高管与产品经理仅需数分钟或数小时内氛围编程出功能原型。这使得开发团队陷入了两难困境：要么受制于人工审核速度而牺牲研发效率，要么在无法确认是否与整体架构对齐的情况下盲目推进进度。
随着时间推移，这些零散的推进不断累积，最终导致架构碎片化。组织往往通过增加流程、制定更严格的规范来应对，这反而进一步加大了发布对齐软件的难度。这一恶性循环拖慢了交付速度，也削弱了创新能力。
声明式架构，去中心化的对齐
要在生成式 AI 时代提升架构对齐能力，组织需要摆脱单纯依赖人工监督的模式，转向自动化防护机制，让团队能够自主做出合规且安全的决策。为此，我们提出声明式架构策略来实现架构治理的规模化扩展。
声明式架构将架构决策与约束提炼为可由机器强制执行的设计意图声明，从而支持安全、独立的研发行动。每个声明都管控着一个明确的作用范围，即在一个清晰界定的上下文内拥有执行权限。若缺乏这一边界约束，声明就会沦为它们本应取代的、臃肿散乱的设计指引。
声明式架构的目的并不是为了做出更优的决策，而是确保决策不会被忽视。相较于查阅解读架构文档、等待专家或评审委员会的意见，机器可读的架构意图声明让合规路径成为阻力最小的选择。合规验证不再依赖人为意识与记忆，而是被集成到开发者日常使用的工具中，包括编辑器、构建管道与代码审查工具。在这一框架下，机器可读性并非技术上的锦上添花，而是核心要求。仅能被人类理解的声明依然需要人工参与校验；只有可被机器推理的声明才能让治理能力超越个人或评审委员会的处理上限。后续章节中，我们将探讨从事件模型、OpenAPI 规范及 ADR 中提炼声明式架构的实际应用。
事件模型作为声明式架构
事件模型描述了信息在系统中的流转方式，通常通过协作建模来生成。
图 2. 带有高亮垂直切片（绿色矩形）的事件模型。每个切片是一个自包含的行为单元，拥有自己的命令、事件和读取模型。来源：Adam Dymitruk，Adaptech Group
画布上的可视化便签内容被一一对应转录为具备形式化 Schema 支持的 eventmodel.json 文件中。该 eventmodel.json 构成了系统的声明式架构：它是一份机器可读的架构意图蓝图，可据此生成符合规范的实现，也可让智能体对照着对实现进行评估。
图 3. 从事件模型到生成代码
1.为自动化提供支撑
垂直切片具有明确的边界范围，包含描述单个行为单元所需的声明。这种最小化范围是在各个层面实现自动化的关键。代码工件可使用代码模板从事件模型确定性地生成，无需依赖 AI。同时，由于每个切片都是自包含的，代码工件也按切片进行组织（参见垂直切片架构）；一旦出现问题，只需替换单个切片，而无需拆解复杂的依赖网络（仍需遵守对外部依赖的相关契约）。对于模板无法覆盖的场景，形式化 Schema 可让 AI 发挥更大作用。Nebulit 的 Martin Dilger 定义了一套 Claude 规则文件文件，用于分析代码库并从中生成事件模型。领域专家随后可以通过 AI 智能体审查和优化模型，实现比代码更高抽象层次的对话式编程。由于范围被最小化，人与 AI 均可聚焦于独立切片，大幅降低认知负荷。正是这种最小化范围使得 Ralph Loop（下文详述）得以实现，让每个切片成为 AI 智能体的独立迭代目标。
2.大规模去中心化架构对齐
事件模型能够实现去中心化，但其前提是建模过程必须跨团队协作进行。如果各团队在孤立环境中独立建模，每个团队的事件模型或许会在内部保持一致，但可能导致整个产品出现架构碎片化。Adaptech Group、Nebulit 等机构已实践了覆盖多个团队的多领域协作建模，验证了该模式可以拓展到单一团队边界之外。诸如 architecture.md、OpenAPI 校验工具（下文会提到）这类技术对齐机制能强制规范系统的构建方式，但无法保证团队协同构建出正确的产品。这就需要覆盖范围更广的共享建模，例如事件建模或其他协作式设计方法。好消息是：技术治理将人类的注意力从监督实现细节中解放出来，为实现产品级的架构对齐创造了空间。
3.Ralph Loop：从切片到交付
Ralph Wiggum Loop 是多种 AI 循环机制之一，智能体会反复执行任务，直至满足完成标准；每次迭代都会以全新上下文重新启动，避免推理能力退化。在早期迭代阶段，通常会由架构师参与其中，对配置进行调整与验证。这张图展示了 AI 辅助 ADDR 流程在第二次迭代中的输出结果示例。
事件模型中的每个垂直切片都对应一个迭代目标：智能体读取切片规范、完成实现，并对照 Given-When-Then 规范进行验证，循环执行直至验证通过。由于每个切片都采用最小化范围，能够适配单个上下文窗口，即便使用轻量化模型，在这种条件下也能产出可靠的结果。
规范 + 垂直切片 = AI 的糖果（来源：Martin Dilger）
图 4. Ralph Loop 文件结构
这个结构清晰地展现了整个流程：plan 文件夹相互独立，支持并行执行。每个文件夹都包含独立的进度标记、实现复选框与日志记录。反馈循环中产生的决策与经验会在各 plan 之间累积。当这些内容足够重要时，由开发人员进行审核，并更新 AGENTS.md。智能体的行为基于整理后的经验进行演进，而非自动自我修改。每次迭代都会产生组织知识，作为工作产出的副产品。[代码库链接]
4.事件建模的前景
图 5. Wardley 地图：事件模型工具演进
上面的 Wardley 地图展示了 AI 的工业化应用路径：将成熟的事件模型工具与新兴的模式标准相结合，催生出一种全新模式——对话式 AI 事件建模。这个过程将领域专家与生成式 AI 相结合，通过对话而非编写代码来完成系统建模。在上述事件建模工作流中，代码成为可丢弃的产物。切片具备最小范围且定义完整，受模板与架构的约束治理，无需人工维护，可直接从规范重新生成。这重新定义了遗留系统现代化的路径：不必重写数百万行代码，只需对领域建模并据此生成全新代码即可保证系统持续保持架构对齐。
事件建模在领域行为层面开展，将业务意图提炼为可由机器执行的切片。而这套声明式模式同样适用于领域边界之外。当行为完成建模并在内部实现后，外部接口也必须保持一致。声明式架构并非只局限于内部切片，还可延伸至维系系统协同的各类契约。
OpenAPI 验证器作为声明式架构
以一家中型企业为例，该企业运营着高度分布式的 SaaS 平台，包含数十个由自治团队负责的数百个组件，主要通过 HTTP API 进行交互。以往，该组织高度依赖隐性的个人架构负责制与“标准与实践”文档。所谓“正确”的做法，很大程度上取决于团队咨询了哪些人、最先查到哪些文档。团队往往难以找到最优方案，进而在项目初期就埋下架构偏离的风险。而在执行过程中，各类临时决策会进一步加剧这种偏离，导致架构设计意图与实际落地之间的差距不断扩大。
该组织正处于增长的关键节点，计划推出面向客户的 API 层。组织优先保障兼容性与易用性，以最大化这一新接口的使用率。同时，它也希望保留高度自治团队所带来的高效交付优势，并意识到当前临时化的架构治理方式已形成瓶颈。此外，该组织还希望确保架构能够持续适配不断变化的业务需求。
为了调和这种紧张关系，该组织采用了基于 OpenAPI 规范的声明式架构方案：由中央平台团队制定标准并提供校验工具（代码检查工具）。这些校验工具将平台团队的架构意图进行编码，向开发团队提供合规性自动反馈，并集成至 CI/CD 流程中，避免生产环境出现架构偏离。同时，这类工具也被整合进开发者工作流（如 IDE 插件、GitHub 状态检查），实现快速反馈并将偏差检测左移。这种集中决策、分散执行的模式保障了跨领域 API 在路径规范、版本控制与向后兼容、分页设计、错误结构等方面的一致性，最终为内部产品团队与外部 API 使用者提供流畅的开发者体验。
这种方法可以自然地融入到组织现有的软件生命周期中，而该生命周期本身就高度依赖声明式基础设施与独立可部署能力。每个团队的 OpenAPI 规范均作为 API 的部署配置来使用，平台会将 OpenAPI 文档转换为 API 网关配置、授权策略及面向用户的文档。由于所有开发团队共用一套标准化的构建、测试、部署流水线，平台团队只需通过一个统一且可预期的节点即可强制执行架构意图，无需逐一对各团队进行协调。各团队可继续沿用他们熟悉的现有流程，部署时的校验机制从根本上杜绝了架构偏离的可能性。只有验证通过部署才能成功，因此存在偏差的内容永远不会进入生产环境。
图 6. 包含构建时与部署时校验的 API 生命周期
这种模式旨在为开发团队降低认知负担、提升自治度，同时在生产环境中实现严格的架构一致性，最终为客户提供统一且直观的 API 体验。前期反馈表明，该方案正按预期落地：如今 API 团队可以直接将通过的验证结果作为客观依据，而这些治理需求以往需要数天甚至数周的人工审核。
由于架构意图已被编码为机器可验证的规则，架构对齐变得可观测。平台团队通过校验工具收集各类遥测数据，包括校验错误率、变更前置时间、产品团队反馈等，以此识别系统性的流程阻塞。重复出现的违规通常意味着标准不够清晰或不切实际；较长的前置时间可能表明约束过多；而持续较低的违规率则说明相关约定稳定可行。
正如 ADDR 流程中的 R 环节用于优化 API 设计，这类校验工具的反馈也能让架构意图本身持续迭代。平台团队基于实际观测到的行为优化规则，而非依靠定期修订标准或临时讨论。架构随业务同步演进，团队也能顺势做出调整。
确定性验证守护着系统边界，但架构远不止语法与结构。它是长期积累的判断力，而这种判断力无法被规整地写进检查规则里。
关于架构决策记录
“在项目生命周期中，各项决策背后的核心动机是最难追溯的内容之一。”——Michael Nygard，2011 年
架构决策记录（ADR）是软件开发项目中各项重大变更背后的推理依据。它能够将相关背景从决策者传递给后续负责维护系统的人员，而这类背景信息往往会因敏捷开发动态迭代的特性而丢失。
ADR 提供了一套聚焦于识别权衡方案与替代选项的决策框架，同时补充了各类上下文信息——这些信息对最终决策的影响往往甚于单纯挑选“更优方案”本身。ADR 也成为了驱动软件系统持续演进的集体决策历程记录。
然而，随着生成式 AI 的出现，研究时间大幅缩短，生产力预期也在不断提升，ADR 很可能难以有效地达成目标。人反而成了瓶颈，这在那些要求决策记录在实施前必须审批通过的组织中，问题会尤为突出。Michael Nygard 在 2011 年的博文中就曾提到，“没人会阅读长篇大论的文档”，这也是他设计 ADR 的初衷之一。可如今文档可以轻松批量生成，即便短小的文档也没人看时，又会发生什么？智能体会是解决方案吗？
architecture.md 作为声明式架构
利用架构适应度函数对 OpenAPI 规范进行静态分析只是第一步，而在规范驱动开发的当下，我们需要更进一步。确定性验证器固然可以校验语法、风格与结构，但应用程序本身的设计意图该如何保障？
确定性工具只知晓你明确告知它们的内容，它们无法指出一个完全有效的 REST 端点违反了要求内部通信使用异步事件的核心架构决策，除非依赖脆弱的白名单和例外。以往，我们试图通过“左移”和引导开发者查阅大量架构决策记录（ADR）维基文档来弥补这一差距，但这会给团队带来沉重的认知负担。我们并非真正做到左移，而是将负担直接转嫁给了开发侧，这必然会导致架构随着系统扩展逐渐偏离设计初衷。
我们需要一种既能理解指导方针的字面含义又能领会其核心精神的机制。我们需要将架构提炼为智能体模型可执行的格式，在开发过程中实时为开发者提供指导，而不只是对代码进行把关校验。
引入 architecture.md
这份文件是将我们的架构指南精简提炼为智能体友好型指令的成果，可在每次执行时灵活且一致地应用。将海量陈旧的维基文档直接交给智能体只会引发混乱与幻觉，甚至导致流水线停滞。因此，每份 ADR 都必须提炼成人类与智能体均可理解、并能应用到代码中的简洁指令：
我们做 X 而不是 Y。
当 C 为真时，我们优先选择 A 而不是 B。
每个 ADR 和技术要求都有独立的适用范围与处理方式，被封装为意图的原子单元。
# architecture.md# 可执行架构清单## 服务通信* [ADR-088] [警告] 服务间通信必须采用异步 Kafka 事件。除非与外部第三方厂商交互，否则禁止使用同步 REST 调用。* [ADR-012] [阻断] 所有面向公众的 API 必须在编写实现代码前，以 OpenAPI 3.1 格式完成定义。## 数据与持久化* [ADR-004] [阻断] 各服务必须自主管理自身数据。严禁直接连接其他服务的数据库模式。* [ADR-055] [警告] 高吞吐量、简单访问场景优先选用 DynamoDB。仅当领域需要复杂关系型连接时，方可使用 Postgres。## 基础设施与弹性扩缩容* [系统设计意图] [阻断] 所有微服务必须设计为无状态执行单元，以支持抢占式实例中断。会话状态必须外置存储至 Redis。* [信息安全] [阻断] 所有身份认证必须使用企业身份提供商（IdP）接口。禁止使用应用专属用户表。## 可观测性* [ADR-067] [警告] 日志信息必须采用结构化 JSON 格式，并包含请求上下文中的 `correlation_id`。* [ADR-073] [警告] 禁止记录包含个人可识别信息（PII）的请求体。日志记录前需通过 `Redact()` 工具对载荷进行脱敏处理。图 7. architecture.md 示例
闭环：自动化治理
如果我们放任静态文件过时，它们就变得毫无用处。为了避免 architecture.md 变成又一个陈旧的维基页面，我们将它作为代码进行管理。治理智能体可在每日夜间运行，将仓库清单与中央 ADR 语料库进行比对，若检测到新增或已被替代的决策，便会自动发起拉取请求更新规范，确保仓库始终不会偏离企业基准架构。
随着实现逐步成熟，你可能会遇到 architecture.md 变得臃肿的情况，但这个问题可以通过使用目录结构轻松解决（如这个提案，加上agents.md，将限定范围的片段放在单独文件中）。
有了经过验证的清单，运行时执行就变得简单。无论是以 GitHub Action 还是本地 IDE Copilot 的形式运行，智能体只需获取相关条款（例如仅在涉及 Schema 文件时加载数据规则），评估代码的语义意图，并提供就地修复方案。
如果你的架构是一份可执行清单，你的工具就不再是批评者，而是协作者。用于指导智能体进行代码审查的同一份文件既可以作为生成适应度函数的依据，也可以作为基础设施身份的验证依据。我们不只是在左移，而是为“左侧”提供了清晰的指引。
结论
在生成式 AI 时代，代码与文档的编写已趋于通用化，因此保障整个组织内的一致性与标准变得比以往更为关键。通过采用声明式架构与反馈循环，组织能够持续演进，并自动化地落实架构意图。运用事件建模、OpenAPI 校验、架构决策记录等行业标准实践，并将成果提炼为机器可执行的架构意图声明，组织可以让团队高效推进工作，同时保持高度一致且可靠的协同。这种模式可扩展至智能体流程，覆盖以往仅能由人工验证工作意图的场景。
为消除集中式治理带来的瓶颈，架构决策必须直接编码到用于生成和验证实现的工具中。合规路径应当是最简便的路径。生成器应在项目启动阶段及开发者工作流内部发挥作用。验证器则应集成到 IDE、拉取请求和部署环节中。交付管道之外的治理机制很容易被绕过，而嵌入到流程中的治理机制变得隐形且自动化。这些机制必须配备能够持续演进声明式架构的反馈循环。
代码如今已十分充足，但对齐一致性却并非如此。架构治理的未来不在于更多审查委员会或更完善的文档，而在于持续执行与优化声明式意图，使其与所治理的系统保持同速演进。
【声明：本文由 InfoQ 翻译，未经许可禁止转载。】
查看英文原文：https://www.infoq.com/articles/architectural-governance-ai-speed/
