如何在 AI 时代做架构设计

声明：和 AI 协作完成的，文章内容和主体是个人写的，由 AI 润色完成。

如题，文章要叙述如何在 AI 时代做架构设计，解决 what / why / how 三个问题：AI 时代的架构设计到底是什么、为什么还需要它、以及具体怎么做。

what - 什么是 AI 时代的架构设计？

先回顾传统架构设计要解决哪些问题：

方法论与体系：采用 TOGAF、C4、Arc42 等框架定义架构工作的流程与产出规范；
原则与指导标准：定义架构原则（Principles）和指导标准（Guidelines），作为决策的约束边界；
架构实施：从需求输入出发，定义系统边界，产出分层架构设计（L1～L4），同时覆盖逻辑部署与物理部署；
决策记录：遇到方案取舍时，完成 ADR（Architecture Decision Record）或 KDD（Key Design Decision），通过讨论与评审流程完成决策并归档；
协作与治理：与上下游团队持续对接，确保架构上下承接一致，并持续演进和治理。

这些活动的产出物和目的在 AI 时代没有本质变化——系统仍然需要拆解、权衡仍然需要记录、架构仍然需要治理。真正变化的是生产方式和工作流。具体来说，AI 时代新增了三个维度：

第一，产出方式从「手写」变为「人机协作」。架构师不再从空白页开始画图、写文档，而是用 prompt 驱动 LLM 生成初稿，人做审阅、修正和最终决策。比如系统上下文图（C4 Level 1）可以从需求文档自动生成初版，架构师在此基础上调整边界和职责。

第二，架构产物从「给人看」变为「人 + AI 都能消费」。传统架构文档以图形和自然语言为主，人类能读懂但 AI 难以结构化处理。AI 时代的架构产出必须是结构化文本——比如用 LikeC4 的 DSL 描述 C4 模型、用 Mermaid 描述时序——这样 AI Agent 在下游可以直接消费架构设计来生成代码骨架或校验实现一致性。

第三，架构治理从「人工评审」变为「规则 + Agent 自动校验」。架构原则不再是贴在 Wiki 上的口号，而是写成结构化规则文件，由 Agent 在每次变更时自动检查——比如「是否引入了未经批准的跨系统直接调用」「新增服务是否符合技术栈规范」。

总结：AI 时代的架构设计 = 传统架构方法论 × Architecture as Code × AI Agent 协作。核心变化不是「要不要做架构」，而是「架构以什么形态存在、由谁和什么工具来生产」。

why - 为什么还需要架构设计？

这个问题其实需要拆成两层来回答。

第一层：架构设计这个活动为什么还需要？

从需求到实现，缺少前期设计和系统模块的拆解确认，后期一定会形成技术债。这和有没有 AI 无关——AI 可以帮助你更快地写出代码，但如果系统边界没划清楚、模块职责没定义好，AI 写的代码越快，积累的技术债越深。

架构设计过程中有大量不可逆的权衡：选择单体还是微服务、同步还是异步、强一致还是最终一致——这些决策一旦做出，后期改动的成本极高。AI 可以提供方案对比和数据分析，但它无法替代人对业务上下文、组织约束和长期演进方向的判断。

此外，康威定律依然有效——系统架构会反映组织的沟通结构。跨团队的系统交互设计，本质上是组织设计问题，这不是纯技术 AI 能解决的。

第二层：架构师这个角色还需要吗？

如果从 AI Native 组织架构和 AI Builder 的视角看，专职的、只做架构文档的架构师一定没需求了。原因很简单：当 AI 能根据需求自动生成架构初稿，一个能力全面的 AI Builder（既懂业务又懂技术又能驱动 AI）自己就能完成从需求到架构到代码的闭环，中间不需要一个「翻译层」。

但这不是说架构能力不重要了，而是架构能力需要重新分布：

能力左移：架构师（或承担架构职责的 AI Builder）需要更靠近业务侧，具备业务分析能力，能把业务需求直接转化为架构输入，而不是等 BA 或 PM 翻译好再接手；
能力右移：架构设计需要直接成为代码生成的有效输入。架构产物不再扔给开发团队自己去理解实现，而是作为 AI Agent 的上下文，驱动代码骨架、API 定义、数据库 Schema 的自动生成。

换句话说，架构师不会消失，但会融入 AI Builder 这个更大的角色中。纯「画图型」架构师被淘汰，能端到端交付的 Builder 成为主流。

新的挑战

团队协作中，如何让 Agent 输出的架构既被 AI 下游消费，又被人类团队理解和接受，是一个新的工程挑战。光有一堆结构化文件不够，还需要清晰的工作流、评审机制和质量标准。

how - 怎么做 AI 时代的架构设计？

核心理念：Architecture as Code（AaC）

选择 Architecture as Code（arch-as-code.org）作为基础范式，原因有三：

结构化文本是 AI 的最优输入：虽然现在的多模态模型能理解图片，但对于持续的演进和治理，结构化文本（DSL、Markdown、YAML）可 diff、可 review、可被 Agent 精确解析，远胜于 PPT 和白板照片；
版本控制是架构治理的基础：架构产物纳入 Git，变更历史可追溯，原则检查可自动化；
AI 可直接消费并驱动下游：Agent 读取架构设计文件后，可以直接生成代码、校验实现一致性、更新文档。

工具选择

LikeC4：提供结构化的 C4 模型 DSL，同时支持可视化。选它的核心原因是它的 DSL 是 AI 友好的结构化文本，而生成的图是给人看的——兼顾两者。
Mermaid：用于时序图、流程图等动态视角的描述，同样是文本 DSL，AI 生成和修改都很方便。
C4 模型：作为架构分层的方法论，从 System Context（L1）到 Component（L3）再到 Code Level（L4），层级清晰，适合渐进式细化。

注：LikeC4 有标准的项目组织结构，下文的设计需要在此基础上做适配调整。

项目组织结构

整个架构项目分为两层：

.harness/：架构的「控制面」——规则、流程、变更记录、AI 技能定义。这是让 AI 知道「怎么做好架构」的地方；
architecture/：架构的「数据面」——实际的架构设计产出。这是让 AI 知道「系统长什么样」的地方。

.harness/
  rules/                              # 架构规则与约束
    kdds/                             # KDD/ADR 结构化记录
      2026-001-选择单体而非微服务.md
      2026-002-采用事件驱动解耦订单与库存.md
    architecture-principles.md        # 架构原则（如 cloud-first、单体优先等）
    architecture-guidelines.md        # 架构指导规范
      design-process.md               # 设计流程定义
      design-standard.md              # 设计标准与约束
      design-techstack.md             # 技术栈规范
  changes/                            # 基于需求输入的架构变更（参考 SDD 格式）
    _template/
      spec.md                         # 变更规格说明
      summary.md                      # 变更摘要
      tasks.md                        # 变更任务分解
  skills/                             # 自定义 AI 技能定义

architecture/
  system-context.c4                   # C4 Level 1：系统上下文
  L1-design.c4                        # 平台级设计（解耦为多个系统）
  xx-system/
    L2-design.c4                      # C4 Level 2：系统解耦为多个子系统
    xx-subsystem/
      L3-design.c4                    # C4 Level 3：子系统解耦为多个组件
      xx-component/
        L4-design.c4                  # C4 Level 4：服务/API/数据模型设计
        sequences.mermaid             # 时序图
    deployment.c4                     # 部署架构

AGENTS.md                             # AI Agent 的项目上下文（入口文件）
CLAUDE.md                             # 指向 AGENTS.md
README.md                             # 项目说明

各目录职责详解

.harness/rules/——架构的「宪法」

这个目录定义了架构的约束边界，AI Agent 在做任何架构决策时必须参考。architecture-principles.md 是最高层级的决策原则，比如：

「单体优先，确有必要才拆微服务」——这是对微服务潮流的明确约束；
「cloud-first，所有新服务默认上云」——消除了每个项目重新讨论部署方案的摩擦。

architecture-guidelines.md 下设三个子文件，分别定义流程（怎么做架构设计）、标准（架构产出的质量标准）、技术栈（可用技术及版本约束）。这些不是给人看的文档，而是 AI Agent 在做架构生成和校验时的规则输入。

.harness/kdds/——关键决策的不可变记录

每个架构决策以独立文件记录，包含：背景、问题、考虑的方案、决策、后果。格式采用结构化 Markdown，方便 Agent 检索和应用。例如，Agent 在做新系统的技术选型时，可以检索所有 KDD 中关于「数据库选型」的决策，确保一致性。

.harness/changes/——架构变更的工程化入口

参考 SDD（Spec-Driven Development）的思路，每一次架构变更不是随意改文件，而是走「规格 → 摘要 → 任务拆解」的标准流程。_template/ 提供标准模板，每次新变更复制一份，Agent 按模板引导人类完成变更规格的填写，然后自动更新对应的架构文件。

.harness/skills/——自定义 AI 能力

存放项目特有的 AI 技能定义，比如「生成新系统的 L2 设计」「校验 L3 设计是否符合原则」等。这些技能可以被 CI 流程或开发时的 Agent 直接调用。

architecture/——架构设计的实际产出

按 C4 模型的层级组织：system-context.c4 描述系统与外部参与者的关系（L1），向下逐级细化到组件级（L3）和代码级（L4）。每个 .c4 文件是 LikeC4 DSL 结构化文本，.mermaid 文件是 Mermaid DSL。两个格式都是纯文本，可 diff、可被 Agent 精确读写。

AGENTS.md 和 CLAUDE.md

AGENTS.md 是整个项目的 AI 入口上下文文件，告诉 AI Agent 这个项目的性质（架构设计项目）、目录结构、工作方式。CLAUDE.md 是一个符号链接或引用文件，指向 AGENTS.md，确保不同 AI 工具都能找到项目上下文。

工作流示例

以「需要给订单系统设计异步通知能力」为例，走一遍完整流程：

发起变更：开发者复制 .harness/changes/_template/，填写 spec.md（描述业务需求：订单状态变更时通知下游）、summary.md（变更范围：新增消息队列，订单服务作为生产者）、tasks.md（拆解为 3 个任务：选型 MQ、定义消息格式、更新 C4 设计）；
AI 生成架构初稿：Agent 读取 spec.md 和 .harness/rules/（原则、技术栈规范），生成 L3-design.c4 的变更和一个 sequences.mermaid 时序图初稿。技术栈规范约束了 MQ 只能选 Kafka，Agent 自动遵循；
人工评审：架构师（或 Team Lead）review Agent 的产出，调整系统边界——比如决定通知服务是否需要独立的子系统还是作为订单系统的扩展组件；
记录决策：如果讨论中有取舍（比如「为什么不直接调 API 而要走消息队列」），用 KDD 模板记录决策，归档到 .harness/kdds/；
Agent 校验 + 驱动代码：CI 流程中，Agent 校验变更后的 .c4 文件是否符合 architecture-principles.md，然后基于 L3/L4 设计生成 Kafka topic 配置、消息 Schema 和生产者/消费者的代码骨架；
合入并演进：变更合入主分支，架构资产随代码一起版本化管理，后续任何人对架构有疑问，直接读 .c4 文件，不需要翻 Confluence 或过期的 Wiki。

ADR/KDD 模板示例

# KDD-2026-003：订单状态变更通知采用消息队列而非同步 API 调用

## 背景
订单服务完成状态变更后，需要通知下游（库存、物流、通知中心）。
当前方案是同步 HTTP 调用，下游增多后订单服务耦合严重。

## 决策
采用 Kafka 作为消息中间件，订单服务发布事件，下游各自消费。

## 考虑的方案
| 方案 | 优点 | 缺点 |
|------|------|------|
| 同步 HTTP | 实现简单，可立即获得结果 | 耦合重，下游故障影响上游 |
| Kafka 消息 | 解耦，下游可独立演进 | 引入 MQ 运维复杂度，需处理最终一致性 |
| gRPC Stream | 性能好 | 下游改造大，团队不熟悉 |

## 后果
- 订单服务不再感知下游数量变化
- 需新增 Kafka 集群运维（已在技术栈白名单中）
- 业务流程从同步变为异步，需调整监控和告警策略

常见反模式与风险

AI 生成的架构直接合入不加评审：AI 不了解组织的政治边界和团队的隐性约束，可能产出技术上合理但组织上不可行的方案。每次 AI 产出必须经过人工 review。
原则写得太大太空，Agent 无法执行：像「系统应该可扩展」这种原则对 AI 来说是噪音。原则必须具体到可被程序化检查——比如「系统间通信只能通过 API Gateway 或 Kafka，禁止直连数据库」。
过度依赖可视化，忽略结构化源文件：如果团队直接改图而不改 DSL 源文件，架构就退化成了传统的「画图存档」。必须坚持 DSL 是唯一真相源（Single Source of Truth），图只是渲染视图。
KDD 写了不维护：过期的 KDD 比没有 KDD 更危险——Agent 检索到旧决策可能做出错误约束。KDD 应该有生命周期管理，定期 review 和标记废弃。

成功度量

当以下现象出现时，说明 AI 时代的架构设计实践已经落地：

新系统的 L1～L3 设计初稿由 AI 生成，人工只做 review 和微调，耗时从天级降到小时级；
架构原则变更后，Agent 能自动扫描所有现有设计，列出不符合新原则的条目；
新人加入团队，通过读 .harness/rules/ 和 AGENTS.md 就能理解架构约束，不需要老员工口口相传；
代码实现与架构设计的偏差能被 CI 自动检测——比如代码中出现了架构设计里没有定义的服务间调用。

总结

AI 时代的架构设计不是要抛弃过去的方法论，而是把架构从「人写的文档」变成「人 + AI 协作的结构化资产」。核心三件事：用 Architecture as Code 让架构产物可机器消费、用规则文件让约束可自动执行、用 AI Agent 让生产和校验自动化。架构师这个头衔可能会淡化，但架构能力——拆解系统、权衡取舍、定义边界——永远需要，只是承载方式和协作模式变了。