---
title: "后端架构 AI Friendly 的标准与路径：面向无人值守开发时代的系统重构"
source_url: https://mp.weixin.qq.com/s/XpSpAiWY-nXjw8d8QPbabg
publish_date: 2026-06-15
tags: [wechat, article, ai-friendly-architecture, harness, sdd, skills, microservice, observability, access-control, alibaba]
review_value: 9
review_confidence: 8
review_recommendation: ingest
sha256: f47f4fb59f74d6c961b0a083b280a96a52161b6826ba660617b5c44953da7029
---
# 后端架构 AI Friendly 的标准与路径
> Source: https://mp.weixin.qq.com/s/XpSpAiWY-nXjw8d8QPbabg
> Author: 刘瑞洲 (阿里技术)
> Date: 2026-06-15
> Collected: 2026-06-16

## 核心判断

**AI Friendly 不是给项目加 README 或让代码风格更规范**。真正的 AI Friendly 是让 AI Agent 在有限上下文/权限/试错成本下，能正确理解系统、定位边界、拆解任务、修改代码、验证结果、评估风险、生成变更说明，并在自动化规则约束下安全推进系统演进。

> 过去建设的是「可维护系统」，未来要建设的是「**可被智能体维护的系统**」。

本质是把隐藏在人脑、群聊、口头约定、历史事故里的系统知识，**显式化、结构化、可检索化、可执行化、可验证化**。

## 一、Architecture Facts Clarity：第一原则，架构事实清晰

**系统知识需要从"人脑资产"变成"机器可读资产"**。互联网系统迭代速度快，文档常见问题：过期、不完整、分散、无版本、无 owner、与代码/运行态无关联——对 AI 是直接误导源。

AI Friendly 第一步是建立**机器可读的系统事实层**，6 类事实：

| 类型 | 关键内容 |
|---|---|
| **架构事实** | 业务域划分、服务分层、核心链路、服务拓扑、消息拓扑、数据所有权、强弱依赖、同步异步边界、关键基础设施、灰度与发布边界、容灾与降级策略、历史遗留模块、未来演进方向 |
| **服务事实** | service.yaml / domain.yaml / dependencies.yaml 维护服务名、业务域、核心职责、上下游、依赖（DB/缓存/消息）、核心接口、负责人、告警入口、降级方式 |
| **领域事实** | 每个业务域的实体定义、状态定义、状态流转图、关键不变量、异常分支、幂等要求、补偿机制 |
| **接口事实** | 调用方、是否幂等、可重试、超时、限流、鉴权、错误码、兼容性、字段废弃、灰度字段、历史坑点 |
| **数据事实** | 表结构、字段含义、索引、分库分表、冷热数据、归档、敏感字段、唯一性约束、状态枚举、逻辑删除 |
| **运行事实** | QPS、TP99、错误率、是否核心链路、是否强依赖、降级情况、最近事故、consumer lag、Redis 热点 |

**架构事实提供全局地图，服务事实提供节点身份，领域事实提供业务语义，接口事实提供协作契约，数据事实提供状态基础，运行事实提供真实反馈。**

## 二、Architecture Map：让 AI 看懂整个系统

大型分布式系统的复杂性首先来自服务**之间**的关系，不是服务内部。需要一张**可被人阅读、可被 AI 检索、可被工具引用、可被 CI 校验、可被 Harness 执行**的系统级地图——不是 PPT 里的架构大图。

合格的 Architecture Map 必须回答 9 个问题：

1. **系统有哪些业务域**（用户/商品/订单/支付/库存/履约/营销/风控/结算/内容/推荐/数据）
2. **服务如何分层**（网关层/BFF 层/应用服务层/领域服务层/基础能力层/数据平台层/运营后台层）
3. **核心链路如何流转**（下单链路每步是同步还是异步、失败后如何补偿）
4. **服务之间的调用拓扑**（高频/低频、是否在核心链路）
5. **消息拓扑**（哪些服务生产哪些 topic、是否允许重复消费、是否要求顺序、死信队列）
6. **数据所有权如何划分**（每张表/缓存 key/搜索索引明确 owner）
7. **强弱依赖如何定义**（强依赖/弱依赖/降级/超时跳过）
8. **发布边界和故障隔离边界**（哪些服务可独立发布、哪些可降级隔离）
9. **历史遗留和未来演进方向**（legacy / target architecture / 迁移中 / 只维护不扩展）

**关键价值**：把系统从一堆孤立仓库，重新组织成一张可理解的全局网络。AI 接到需求时先回答：这个需求属于哪个业务域？应该改哪个服务？是否影响核心链路？是否违反分层规则？是否涉及数据 owner？

> README 解决"这个仓库如何启动"；Architecture Map 解决"整个系统为什么这样组织，以及哪些边界不能被破坏"。

## 三、System Card（服务身份证）

每个微服务都需要标准化的 Service Card（不是 README），给人和 AI 共同使用。11 字段：

1. 服务定位（属于哪个业务域，解决/不解决什么问题）
2. 核心职责（3-7 条，越多说明边界腐化）
3. 核心实体（本服务直接拥有的实体）
4. 数据所有权（哪些表 owner / 只读 / 禁止跨服务访问）
5. 接口清单（RPC/HTTP 接口、调用方、稳定性等级、是否对外暴露）
6. 消息清单（生产/消费 topic、消息语义、幂等 key、重试策略、死信处理）
7. 依赖清单（服务/DB/缓存/队列/三方；强依赖/可降级）
8. 运行特征（QPS、峰值、延迟、错误率目标、核心 dashboard、关键告警）
9. 变更约束（哪些代码不能改、哪些字段必须兼容、涉及资金/库存/权限/风控的逻辑）
10. 测试入口（单测/集成/契约测试命令、本地启动方式、mock 方式）
11. 发布与回滚（发布平台、灰度策略、配置开关、回滚方式、数据回滚注意事项）

**实施要点**：CI 必须检查 Service Card 是否存在、字段是否完整、与实际依赖关系是否一致。**部分字段应自动生成**（接口从 IDL/OpenAPI、依赖从调用链、表结构从 schema、监控从服务注册），人类只维护业务解释、边界约束和历史注意事项。

## 四、Domain Clarity：领域模型要显式化

**后端系统最核心的资产不是代码，而是业务不变量。** 例如：
- 已支付订单不能随意回到未支付
- 退款金额不能超过支付金额
- 库存扣减必须和订单状态保持一致
- 优惠券不能重复核销
- 账户余额不能变成负数
- 同一请求不能重复入账
- 风控拒绝后的交易不能绕过审批

领域模型重点描述 4 类内容：

1. **不变量**：任何时候都必须成立的规则，写成清晰、可测试、可断言的形式
2. **状态机**：状态枚举、可流转路径、禁止路径、触发事件、补偿动作；最好机器可读，能生成代码中的校验逻辑和测试用例
3. **幂等与一致性策略**：哪些接口用 requestId 幂等 / 哪些消息用 businessKey 去重 / 哪些流程允许最终一致 / 哪些场景需要事务消息或 outbox
4. **风险等级**：资金/库存/权限/隐私/风控/结算 = 高风险（强制人工 review 或双人审批）；内容展示/运营配置/非核心推荐 = 中低风险（可自动 PR）

**跨域链路模型**：单领域模型只保护实体不变量，**跨域链路模型保护系统级一致性**。如下单链路涉及用户/营销/订单/库存/支付/风控/履约/通知等多个服务，AI 必须知道每步是同步还是异步、每步失败如何补偿、哪些步骤允许最终一致、哪些必须强一致、哪些消息可以重复消费、哪些状态不能逆转、哪些异常需要人工介入。

> 领域模型回答"一个业务对象内部如何流转"，跨域链路模型回答"多个业务域之间如何协作"。

## 五、Skill-Based：把团队经验封装成 AI 可调用的工程能力

SKILL 不是普通文档，而是 AI Agent 执行任务时调用的**操作手册**——可复用的任务包，包含任务说明、上下文入口、操作步骤、工具命令、校验方式、风险提示、输出格式。

典型案例（订单系统）：
- 新增一个内部查询接口
- 新增一个异步消息 consumer
- 新增一个数据库字段并完成灰度兼容
- 新增一个订单状态
- 排查某个接口 TP99 升高
- 排查 Kafka 消费堆积
- 修复线上空指针异常
- 给某个接口增加限流
- 把同步调用改为异步事件
- 为历史数据写一次性修复脚本

每个 SKILL 应包含 7 个明确结构：

| 字段 | 内容 |
|---|---|
| 适用场景 | 什么时候应该使用 / 不应该使用 |
| 输入信息 | 服务名、接口名、实体名、字段名、topic 名、错误日志、traceId、需求描述 |
| 相关文件 | controller、service、repository、domain、DTO、mapper、schema、test、配置位置 |
| 操作步骤 | 先改 IDL → 生成代码 → 补业务逻辑 → 补单测 → 更新接口文档 → 跑契约测试 |
| 风险检查 | 是否影响老版本客户端 / 是否需要灰度开关 / 是否涉及数据迁移 / 是否需要补偿脚本 |
| 验证命令 | 本地测试 / 集成测试 / lint / schema 检查 |
| 输出要求 | PR 描述必须包含变更点、兼容性、测试结果、回滚方式 |

**SKILL 化的核心价值**：把高级工程师的经验复制出来——资深工程师知道"加字段要先兼容写、再兼容读、再回填、再切流量、最后清理旧字段"，新人和 AI 可能不知道。

## 六、Harness Augmentation：为 AI Agent 建立安全的执行轨道

如果说 SKILL 是能力包，**Harness 就是执行框架**。它决定 AI 如何获得上下文、如何选择工具、如何执行命令、如何处理权限、如何验证结果、如何停止、如何上报。

面向后端系统的 Harness 应包含 **7 层**：

| 层 | 职责 |
|---|---|
| **上下文装载层** | 根据任务自动加载相关 Service Card、领域模型、接口文档、schema、最近 PR、事故、监控指标；不是把整个代码库塞给模型 |
| **工具层** | 代码搜索、文件编辑、测试执行、依赖分析、日志查询、trace 查询、数据库只读、配置查询、接口 mock、文档生成；**必须有权限边界**（生产 DB 默认只读、敏感表脱敏、危险命令禁止执行） |
| **计划层** | AI 修改前必须输出计划（要改哪些文件、为什么改、预期影响）；低风险自动继续，高风险需审批 |
| **执行层** | 每次修改应在独立分支/worktree/sandbox；不能污染主干、不能直接修改共享开发环境 |
| **验证层** | 执行后必须跑对应测试：单测、集成测试、契约测试、静态检查、安全扫描、schema 检查；**没有验证的 AI 修改不应该进入 PR** |
| **审计层** | AI 做过什么/读过什么/改过什么/执行过什么命令/为什么做这个决策，都要记录 |
| **回滚层** | AI 生成的变更必须附带回滚方案；配置/数据库/消息/缓存/数据修复要说明如何恢复 |

> Harness 的核心不是"让 AI 更自由"，而是"让 AI 在正确轨道上更高效"。

**Harness 的进阶角色**：不只是 AI 的执行环境，还要成为**全局架构规则的执行器**。架构师把分层/服务依赖方向/数据所有权/消息规范/核心链路约束/强依赖准入规则写成机器可检查的 **Architecture Policy**。AI 提交计划或修改代码时，Harness 自动检查是否违反架构边界：
- BFF 层是否直接写入核心业务库
- 非 owner 服务是否访问了其他服务私有表
- 核心交易链路是否新增了未登记的同步 RPC
- 基础服务是否反向依赖了业务服务
- 异步解耦链路是否被改成强同步调用

## 七、Test-Gated AI Development

测试体系从"防人出错"升级为"约束和指导 AI 行为"，不再是守门员而是**红绿灯、每一个 checkpoint 的守门人**。

7 类测试：

1. **单元测试** — 核心领域逻辑（不变量、状态机、金额计算、权限判断、风控规则）
2. **契约测试** — 微服务之间 API 契约稳定（新增/删除字段、修改枚举、调整错误码都不能破坏跨服务兼容性）
3. **集成测试** — 端到端业务流（订单、支付、库存、消息）
4. **回归用例库** — 每次线上事故/重要 bug/历史兼容问题沉淀
5. **数据迁移测试** — schema migration（新增字段、改索引、拆表、迁移数据的兼容性、耗时、锁表风险、回滚脚本）
6. **性能测试** — 高 QPS 接口（N+1 查询、缓存击穿、额外 RPC、锁竞争）
7. **架构验证（AI 时代独有）** — 验证系统结构是否被破坏：
   - 服务依赖是否违反分层规则
   - 领域服务是否被 BFF 反向污染
   - 非 owner 服务是否直接访问其他服务 DB
   - 核心链路是否新增未备案强依赖
   - 消息 schema 是否破坏兼容性
   - 数据库 migration 是否可能锁表风险

> AI 时代测试体系的价值，不再只是告诉人"代码有没有错"，尤其 Agent 时代，更需要告诉 AI "你有没有资格继续往下走"。

## 八、AI-Observable Architecture

无人值守开发包括排障、修复、优化和自愈。AI 必须能看见系统运行状态。

**结构化可观测 5 件套**：

| 件 | 要求 |
|---|---|
| 日志 | 统一格式：traceId、spanId、userId 或脱敏主体、bizId、errorCode、耗时、关键状态；自然语言可保留但关键字段结构化 |
| 错误码 | 不能都叫 SYSTEM_ERROR；必须能区分参数/依赖超时/库存不足/权限失败/幂等冲突/数据不一致 |
| Trace | 能关联业务实体（orderId → 完整调用链/消息链/DB 变更/状态流转） |
| 指标 | CPU/内存/QPS/延迟 + 业务指标（订单创建成功率/支付成功率/退款失败率/库存扣减失败率/消息积压/风控拦截率） |
| 告警 | 必须有 Runbook（可能原因/排查步骤/常用查询/风险等级/临时止血/长期修复） |

> AI Agent 接到告警后，可以自动读取告警上下文 → 查看最近发布 → 分析日志 → 查询 trace → 定位异常 commit → 生成修复 PR → 跑测试 → 提交灰度方案——这才是真正接近无人值守的工程闭环。

## 九、Tiered Access Control 权限分级策略

大型后端系统引入 AI Agent 后，必须重新设计权限边界。**AI Friendly 不是把权限全部给 AI，而是让 AI 在不同风险场景下获得刚好足够的权限**。

6 级权限模型：

| 级别 | 权限 |
|---|---|
| **L0** | 只读代码和文档（问答、解释、影响面分析） |
| **L1** | 在本地 sandbox 修改代码和运行测试，但不能访问真实数据 |
| **L2** | 查询脱敏日志、测试环境 DB、监控指标 |
| **L3** | 创建 PR、触发 CI、生成灰度配置，但不能直接发布 |
| **L4** | 在低风险服务上自动合并和发布，但必须满足测试/灰度/回滚条件 |
| **L5** | 执行生产修复（回滚/降级/扩容/切配置），但必须强审计 + 强策略 + 人类预授权 |

**数据安全**：
- 日志中手机号/身份证/邮箱/地址/支付信息/token/cookie/密钥都必须脱敏；AI 不直接接触明文敏感数据
- 生产 DB 查询默认只读/限行数/限字段/限时间窗口 + 全量审计
- 密钥/证书/生产配置必须通过 secret manager 管理，不能出现在 prompt/日志/代码生成上下文

> 一个能力弱的 AI 最多写错代码，**一个能力强但权限失控的 AI 可能直接制造生产事故**。

## 十、Code Navigation Framework：代码结构要可导航

稳定的目录/命名/分层约定：
- controller / application / domain / infrastructure / repository / client / config / test 边界清楚
- DTO / DO / Entity / VO / Command / Event / Mapper 不混用
- 服务调用/消息发送/缓存访问/数据库访问不散落任意位置
- **减少"隐式魔法"**：过度复杂的反射/动态代理/运行时拼接/隐式扫描如果没有足够文档，会让 AI 很难判断真实调用关系——不是说不能用，而是必须让它们可解释、可追踪、可测试

**导航锚点**：
- 每个接口有明确入口
- 每个领域实体有独立文件
- 每个状态机有集中定义
- 每个外部依赖有 client 封装
- 每个消息 topic 有 producer/consumer 定义
- 每个配置项有说明和默认值
- 每个数据库表有对应 repository

## 十一、Docs/Architecture as Code

**Docs as Code**：文档不进入工程流程就一定会腐化。
- 新增接口 → 必须更新 OpenAPI 或 IDL
- 新增 DB 字段 → 必须更新 schema 文档和字段说明
- 新增消息 topic → 必须更新消息契约
- 新增配置项 → 必须写明默认值/作用域/是否支持热更新
- 新增领域状态 → 必须更新状态机
- 修改核心逻辑 → 必须更新对应 SKILL 或 Runbook
- **CI 检查**这些内容是否缺失（新增 controller 但没有更新接口文档 / 新增 migration 但没有字段说明 / 新增 consumer 但没有 topic 文档 → 阻止合并）

**Architecture as Code**：全局架构不再只是 PPT 或 Wiki 页面，而是**可以被 AI 读取、被 CI 校验、被 Harness 执行的工程资产**：
- `architecture.yaml` — 业务域、服务分层、允许的依赖方向
- `ownership.yaml` — 每张表、每个 topic、每个 API 的 owner
- `critical-path.yaml` — 核心链路和延迟预算
- `risk-policy.yaml` — 不同风险等级下 AI 可自动执行到哪一步

## 十二、Copilot → Coworker → Operator

| 阶段 | AI 角色 | 系统要求 |
|---|---|---|
| **Copilot** | 辅助写代码/补测试/解释代码/生成文档 | 基本文档、代码规范、测试入口 |
| **Coworker** | 独立完成中低风险任务（新增接口/修 bug/补单测/写 migration/改配置/生成 PR） | Service Card、SKILL、领域模型、契约测试、CI 约束 |
| **Operator**（"黑灯工厂"） | 参与线上值守：接收告警/分析日志/定位问题/提出修复/执行回滚/生成复盘/沉淀 Runbook | 完整可观测性、权限分级、审计、自动化发布、灰度、回滚、安全策略 |

> 7×24 无人值守开发不是一步到位让 AI 接管生产，而是**逐步扩大 AI 的可信半径**。先让它在低风险、强验证的区域自动化，再逐步进入复杂系统和生产运维。

## 十三、11 步 Practical Roadmap

| 步骤 | 行动 |
|---|---|
| 1 | 选择中等复杂度、风险可控的业务域作试点（不要选最边缘或最高风险） |
| 2 | 先建立**最小可用**的全局 Architecture Map（业务域/核心链路/分层/依赖/数据所有权/消息主干/风险等级/历史遗留） |
| 3 | 为试点服务补齐 Service Card（职责/依赖/接口/数据/消息/测试/发布/回滚） |
| 4 | 梳理核心领域模型（实体/状态机/不变量/幂等规则） |
| 5 | 沉淀 5-10 个高频 SKILL（新增查询接口/修 bug/补单测/加字段/消费消息/排查告警） |
| 6 | 补测试和契约（不追求一次全覆盖，先覆盖核心链路和高频变更点） |
| 7 | 建立 AI PR 模板（变更说明/影响面/测试结果/风险点/回滚方案） |
| 8 | 把 CI 变成硬门槛（测试/文档检查/安全扫描不通过不能合并） |
| 9 | 接入只读可观测工具（日志/trace/指标，脱敏 + 限权 + 审计） |
| 10 | 允许 AI 做低风险自动 PR（先不自动合并，让人类 review AI 的产出质量） |
| 11 | 逐渐扩大到更多服务和更复杂任务 |

> 这条路线的关键是：**不要先追求"无人化"，而要先追求"可验证"**。无人化不是目标本身，可验证的自动化才是目标。

## 十四、最终愿景：AI Friendly 重塑软件组织方式

过去 → 未来的转变：

| 过去 | 未来 |
|---|---|
| 优秀团队依赖人的经验、默契和长期积累 | 优秀团队要把经验变成结构化资产，让 AI 读取/调用/执行/验证 |
| 文档是给新人看的 | 文档更是给 Agent 装载上下文用的 |
| 测试是为了防止上线出 bug | 测试是为了约束 AI 的行动边界 |
| Runbook 是故障时翻看的手册 | Runbook 是 AI 自动排障的操作图谱 |
| 架构治理靠会议和 review | 架构治理会通过规则/元数据/CI/权限/Harness 自动执行 |

**真正 AI Friendly 后端系统的 10 个特征**：
1. AI 能快速知道每个服务负责什么
2. AI 能理解核心实体和业务不变量
3. AI 能找到正确代码位置，而不是全局乱搜
4. AI 能按照团队沉淀的 SKILL 完成任务
5. AI 能在受控 Harness 中修改、测试、提交
6. AI 能通过自动化测试验证自己的改动
7. AI 能读取脱敏后的运行态信息进行排障
8. AI 的每一步操作都有权限边界和审计记录
9. AI 生成的每个变更都有影响面分析和回滚方案
10. AI 在低风险场景中可以自动推进，在高风险场景中知道停止并请求人类决策

> AI Friendly 不是为了讨好 AI，而是为了让系统知识更清晰、工程流程更规范、风险控制更自动化。即使没有 AI，这些改造也会提升团队效率；而一旦 AI Agent 成熟，这些改造会成为团队能否进入无人值守开发时代的分水岭。

未来的后端架构师，不仅要设计高并发/高可用/高扩展的系统，还要设计"**可被 AI 理解、可被 AI 修改、可被 AI 验证、可被 AI 运维**"的系统。