本文作者：刘瑞洲

前言

过去十几年，互联网软件的后端系统核心目标大多围绕「人类工程师友好」展开：架构要清晰，接口要稳定，日志要可查，监控要完整，发布要可控，故障要可回滚。这些原则并没有过时，但在 AI Coding、Agentic Coding、Vibe Coding 逐渐进入工程现场之后，一个新的问题出现了：如果未来大量开发、排障、重构、测试、发布工作不再完全由人类手动完成，而是由 AI Agent 7 × 24 小时持续执行，那么现有后端系统是否足够「AI Friendly」？

在我看来，所谓 AI Friendly，并不是简单地「给项目加一份 README」，也不是「让代码风格更规范一点」。

真正的 AI Friendly，应该是让一个 AI Agent 能够在有限上下文、有限权限、有限试错成本的前提下，正确理解系统、定位边界、拆解任务、修改代码、验证结果、评估风险、生成变更说明，并在自动化规则约束下安全地推进系统演进。

换句话说，过去我们建设的是「可维护系统」，未来要建设的是「可被智能体维护的系统」。

这对后端分布式系统来说尤为重要。

一个现实中的大型互联网后端，往往包含几十个甚至上百个微服务，背后有 RDB、Redis、Kafka、RocketMQ、对象存储、搜索引擎、任务调度、配置中心、注册中心、网关、风控、权限、审计、灰度、监控、告警、数据仓库等一整套复杂基础设施。**人类老员工可以凭经验知道「哪个服务负责什么」、「这个字段不能乱动」、「这个 topic 有历史包袱」、「这个接口看起来没人用但其实小程序还在调用」，但 AI Agent 不知道。**它只能通过代码、文档、工具、日志、测试、历史变更、运行环境去推断。

所以，如果想把后端系统真正做成「AI Friendly」，本质是要把隐藏在人脑、群聊、口头约定、历史事故里的系统知识，显式化、结构化、可检索化、可执行化、可验证化。

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

系统知识需要从“人脑资产”变成“机器可读资产”

传统后端系统比较大的问题，是文档不可用或者过于落后，尤其互联网领域，系统迭代速度很快，往往文档都是落后于技术系统的。

很多团队都有接口文档、架构文档、数据库文档、部署文档，但它们常见的问题是：过期、不完整、分散、没有版本、没有 owner、没有和代码关联、没有和运行态关联。对人类来说，这些文档还能作为参考；对 AI 来说，这些文档会直接变成误导源。

AI Friendly 的第一步，是建立“机器可读的系统事实层”。

这个事实层至少包括几类内容。

第一类是架构事实

面对几十个甚至上百个微服务组成的后端系统，AI 首先需要的是一张全局架构地图。它需要知道系统整体分成哪些业务域，哪些是核心链路，哪些是支撑系统，哪些服务处在网关层、BFF 层、领域服务层、基础能力层、数据平台层；它还需要知道服务之间的调用拓扑、消息拓扑、数据流向、强弱依赖关系、同步与异步边界、核心技术栈、基础设施组件、发布单元、故障隔离边界和历史演进约束。

架构事实的价值，是帮助 AI 建立“系统级方向感”。没有架构事实，AI 只能在单个代码仓库里局部搜索，很容易把局部修复做成全局破坏。例如，把本应在网关或 BFF 层处理的兼容逻辑写进核心领域服务；把本应通过事件驱动解耦的流程改成同步调用；把只读依赖误判为可写依赖；把历史遗留服务继续当成新能力承载点；或者在核心交易链路中引入额外 RPC，造成延迟和稳定性风险。

因此，AI Friendly 的后端系统应该维护一份机器可读的全局架构说明。它至少包括：业务域划分、服务分层、核心链路、服务拓扑、消息拓扑、数据所有权、强弱依赖、同步异步边界、关键基础设施、灰度与发布边界、容灾与降级策略、历史遗留模块、未来演进方向。对 AI 来说，这相当于系统地图；对架构师来说，这也是架构治理从“口头共识”变成“可执行约束”的基础。

第二类是服务事实

每个微服务（Micro Service）必须清楚说明：服务名、业务域、核心职责、上游调用方、下游依赖、数据库依赖、缓存依赖、消息依赖、定时任务、外部三方依赖、核心接口、核心数据表、负责人、告警入口、发布方式、降级方式。最好用结构化文件维护，例如 service.yaml、domain.yaml、dependencies.yaml，而不是只写在一篇自然语言文档里。

第三类是领域事实

后端系统复杂，根源通常不在技术，而在业务领域构成的复杂度。

订单、支付、账户、会员、库存、风控、营销、内容、推荐、履约、结算，这些领域都有自己的实体、状态机、生命周期和约束。AI Agent 如果不了解这些领域模型，就很容易写出“语法正确、业务错误”的代码。因此，每个业务域都应该有明确的实体定义、状态定义、状态流转图、关键不变量、异常分支、幂等要求、补偿机制等等。

第四类是接口事实

接口不只是 URL、参数和返回值。

一个 AI Friendly 的接口文档应该包括：调用方是谁、接口是否幂等、是否可重试、超时时间、限流策略、鉴权方式、错误码含义、兼容性要求、字段废弃策略、灰度字段、历史坑点。

特别是 BFF、网关、APP 后端、开放平台这类接口，必须说明端版本兼容关系。否则 AI 修改一个字段，可能直接造成老版本客户端崩溃。

第五类是数据事实

数据库表结构、字段含义、索引设计、分库分表规则、冷热数据策略、归档策略、敏感字段、唯一性约束、状态字段枚举、逻辑删除规则、数据修复脚本，都应该是 AI 可以读取的事实。

尤其在大规模系统中，字段名经常不足以表达真实含义。比如 status=3 到底是“已支付”“已取消”还是“处理中”，必须有枚举说明。

AI 对字段语义的猜测，是未来自动化开发中最危险的风险点之一。

第六类是运行事实

AI 不能只看静态代码，还要知道系统真实运行情况。某个接口 QPS 多高、TP99 多大、错误率多少、是否核心链路、是否强依赖、是否有降级、最近是否发生过事故、哪个 consumer lag 经常上涨、哪个 Redis key 是热点，这些都应该被纳入 AI 可访问的观察层。

这六类事实合在一起，构成后端系统的“AI 可理解底座”。没有这层底座，AI Coding 只能停留在局部补代码；有了这层底座，AI 才可能参与系统级开发。

其中，架构事实提供全局地图，服务事实提供节点身份，领域事实提供业务语义，接口事实提供协作契约，数据事实提供状态基础，运行事实提供真实反馈。没有这层底座，AI Coding 只能停留在局部补代码；有了这层底座，AI 才可能从“看懂某个文件”升级为“理解整个系统”，从而参与跨服务开发、架构治理、排障修复和无人值守运维。

02 Architecture Map

先让 AI 看懂整个系统，而不是某个服务

如果是一个只有三五个服务的小系统，AI Agent 也许可以通过代码搜索、README 和接口文档，大致推断出系统结构。但对于一个由几十个甚至上百个微服务组成的后端系统来说，这种方式很快就会失效。

因为大型分布式系统的复杂性，首先不是来自某个服务内部，而是来自服务之间的关系：哪些服务属于核心交易链路，哪些服务只是后台运营系统；哪些调用是强依赖，哪些调用可以降级；哪些流程是同步链路，哪些流程是异步事件；哪些数据库属于某个服务私有，哪些数据通过事件同步；哪些系统是新的战略方向，哪些系统只是历史遗留；哪些服务可以承载新需求，哪些服务只应该维护不再扩展。

这些信息如果只存在于架构师脑中、团队群聊里、历史会议纪要里，AI Agent 就无法稳定获取。它只能在局部代码里寻找线索，然后根据文件名、接口名、调用关系进行推断。可是在大型后端系统中，局部推断经常是危险的。一个服务名叫 order-service，并不代表所有订单逻辑都应该继续放进去；一个接口还在被调用，并不代表它是推荐使用的新接口；一个数据库表能被查到，并不代表当前服务有权直接访问；一个 RPC 调用在代码中存在，并不代表新的链路应该继续增加这种强依赖。

因此，AI Friendly 的后端系统需要一份全局 Architecture Map。

Architecture Map 不是传统意义上放在 PPT 里的架构大图，也不是给新人培训时看一眼的系统概览图。它应该是一份可被人阅读、可被 AI 检索、可被工具引用、可被 CI 校验、可被 Harness 执行的系统级地图。

它的目标不是“画得漂亮”，是为了让 AI 在进入任何一个服务、修改任何一段代码之前，先获得系统级方向感。

一份合格的 Architecture Map，至少应该回答以下问题：

第一，系统有哪些业务域

比如用户域、商品域、订单域、支付域、库存域、履约域、营销域、风控域、结算域、内容域、推荐域、数据域。业务域划分能够帮助 AI 判断一个需求应该落在哪个边界里，而不是看到哪里有相似代码就改哪里。

第二，服务如何分层

比如网关层、BFF 层、应用服务层、领域服务层、基础能力层、数据平台层、运营后台层。分层信息能够告诉 AI 哪些逻辑应该放在接入层，哪些逻辑应该放在领域层，哪些能力应该沉淀为基础服务，哪些代码不应该发生反向依赖。

第三，核心链路如何流转

比如下单链路、支付链路、退款链路、履约链路、登录链路、风控链路、消息通知链路。AI 需要知道一条链路经过哪些服务，每一步是同步调用还是异步事件，失败后如何补偿，哪些步骤影响用户实时体验，哪些步骤允许最终一致。

第四，服务之间的调用拓扑是什么

哪些服务调用哪些服务，哪些是高频调用，哪些是低频调用，哪些调用在核心链路上，哪些调用只是后台任务。调用拓扑可以帮助 AI 评估新增依赖的风险，避免在高 QPS 或低延迟链路里随意增加远程调用。

第五，消息拓扑是什么

哪些服务生产哪些 topic，哪些服务消费哪些 topic，事件语义是什么，是否允许重复消费，是否要求顺序，是否有死信队列，是否有补偿任务。很多系统的真实业务流并不体现在同步接口里，而是体现在异步消息中。如果 AI 看不懂消息拓扑，就看不懂系统真正的状态流动。

第六，数据所有权如何划分

每张核心表、每类核心数据、每个缓存 key、每个搜索索引，应该有明确 owner。AI 必须知道哪个服务可以写，哪个服务只能读，哪个服务不能直接访问。否则它很容易为了“快速实现需求”，写出跨服务直连数据库、绕过领域服务、破坏数据边界的代码。

第七，强弱依赖如何定义

并不是所有依赖都一样。有些服务不可用会直接导致主链路失败，有些服务可以降级，有些依赖只影响推荐、展示、通知、埋点、异步统计。AI 在修改调用链路时，必须知道一个依赖是强依赖还是弱依赖，是否有缓存，是否有兜底，是否允许超时跳过。

第八，系统的发布边界和故障隔离边界在哪里

哪些服务可以独立发布，哪些服务需要联动发布，哪些配置可以灰度，哪些变更必须多服务协同；哪些故障可以通过降级隔离，哪些故障会传导到核心链路。没有这些信息，AI 即使写对了代码，也可能给出错误的发布方案。

第九，历史遗留和未来演进方向是什么

大型后端系统里，经常存在一些“仍在运行但不再推荐扩展”的服务、接口、表和链路。AI 如果不知道这些历史背景，很容易继续往遗留模块里增加新能力，让系统债务越来越重。

Architecture Map 应该明确标出：哪些模块是 legacy，哪些模块是 target architecture，哪些能力正在迁移，哪些接口只允许维护不允许扩展。

Architecture Map 的关键价值，是把系统从一堆孤立仓库，重新组织成一张可理解的全局网络。对 AI 来说，它相当于进入系统前的导航地图；对架构师来说，它是架构治理从口头共识变成工程资产的起点。

有了 Architecture Map，AI 在接到一个需求时，才能先回答几个系统级问题：这个需求属于哪个业务域？应该改哪个服务？是否影响核心链路？是否需要新增依赖？是否违反分层规则？是否涉及数据 owner？是否需要消息事件？是否需要灰度和回滚？是否应该在旧系统中维护，还是应该在新架构方向上实现？

没有 Architecture Map，AI 只能做局部代码助手；有了 Architecture Map，AI 才有可能成为系统级工程助手。

因此，对大型分布式后端来说，AI Friendly 的第一张图，不应该是某个服务的 README，而应该是全局 Architecture Map。README 解决的是“这个仓库如何启动”；Architecture Map 解决的是“整个系统为什么这样组织，以及哪些边界不能被破坏”。

在这张全局地图之后，AI 还需要进一步进入具体服务，理解每个服务的职责、数据、接口、消息、测试和发布方式。于是，Architecture Map 之后，才需要为每个微服务建立更细粒度的 Service Card。

03 System Card 服务身份证

从 README 到 System Card：每个微服务都需要一张“服务身份证”

在几十个、上百个微服务的架构里，AI Agent 最怕的不是代码多，而是边界不清。边界不清会导致它改错服务、调用错接口、重复造轮子，甚至在错误的层级解决问题。

因此，每个微服务都应该拥有一张标准化的 System Card，也可以叫 Service Card。它不是普通 README，而是给人和 AI 共同使用的服务身份证。

一张合格的 Service Card 应该包括：

• 服务定位：这个服务属于哪个业务域，解决什么问题，不解决什么问题。

• 核心职责：列出 3 到 7 条最重要职责。职责越多，越说明服务边界可能已经腐化。

• 核心实体：本服务直接拥有的实体是什么，例如订单服务拥有 Order、OrderItem、OrderStatus；支付服务拥有 Payment、Refund、PaymentChannel。

• 数据所有权：哪些表由本服务拥有，哪些表只能读不能写，哪些表禁止跨服务访问。

• 接口清单：核心 RPC / HTTP 接口、调用方、稳定性等级、是否对外暴露、是否允许新增字段。

• 消息清单：生产哪些 topic，消费哪些 topic，每条消息的语义、幂等 key、重试策略、死信处理方式。

• 依赖清单：依赖哪些服务、数据库、缓存、队列、三方平台；哪些是强依赖，哪些可降级。

• 运行特征：QPS、峰值、延迟目标、错误率目标、核心监控 dashboard、关键告警。

• 变更约束：哪些代码不能随便改，哪些字段必须兼容，哪些逻辑涉及资金、库存、权限、风控。

• 测试入口：单测命令、集成测试命令、契约测试命令、本地启动方式、mock 方式。

• 发布与回滚：发布平台、灰度策略、配置开关、回滚方式、数据回滚注意事项。

这类 Service Card 最好放在服务仓库根目录，且由 CI 检查它是否存在、是否包含必要字段、是否与实际依赖关系一致。更进一步，Service Card 不应该完全手写，而应该部分自动生成：接口从 IDL / OpenAPI 生成，依赖从调用链和配置生成，表结构从 schema 生成，监控链接从服务注册信息生成。人类只维护业务解释、边界约束和历史注意事项。

对 AI Agent 来说，Service Card 是进入一个服务前的“第一上下文”。

如果没有这张卡，它只能从代码里盲人摸象；有了这张卡，它可以先建立服务地图，再决定从哪里下手。

04 Domain Clarity 领域模型要显式化

让 AI 知道什么是“不能破坏的不变量”

后端系统最核心的资产不是代码，而是业务不变量。

例如订单系统中：

• 已支付订单不能随意回到未支付；

• 退款金额不能超过支付金额；

• 库存扣减必须和订单状态保持一致；

• 优惠券不能重复核销；

• 账户余额不能变成负数；

• 同一请求不能重复入账；

• 风控拒绝后的交易不能绕过审批。

这些规则往往散落在代码、数据库约束、消息消费、运营后台和人工流程中。人类开发者靠经验知道哪些地方不能动，但 AI Agent 不知道。如果不把这些规则显式化，它就可能在重构时把一个看似多余的判断删掉，或者在新增功能时绕开某个关键校验。

AI Friendly 的后端系统应该建立领域模型文档，重点描述四类内容。

第一是不变量

不变量，就是任何时候都必须成立的规则。例如“支付成功后必须生成唯一支付流水”“订单关闭后不能再次支付”“同一用户同一活动只能领取一次奖励”。不变量应该写成清晰、可测试、可断言的形式。

第二是状态机

很多业务 bug 都来自状态流转错误。订单状态、退款状态、审核状态、配送状态、账号状态，都应该有明确的状态枚举、可流转路径、禁止路径、触发事件和补偿动作。状态机最好不仅有图，还要有机器可读定义，能生成代码中的校验逻辑和测试用例。

第三是幂等与一致性策略

分布式系统里，重试、超时、重复消息、乱序消息是常态。AI 必须知道哪个接口依赖 requestId 幂等，哪个消息用 businessKey 去重，哪个流程允许最终一致，哪个流程必须强一致，哪个场景需要事务消息或 outbox。

第四是风险等级

资金、库存、权限、隐私、风控、结算属于高风险域；内容展示、运营配置、非核心推荐可能是中低风险域。AI Agent 在不同风险等级下，允许的自动化程度应该不同。低风险域可以自动提交 PR，高风险域必须强制人工 review 或双人审批。

未来真正成熟的 AI Friendly 系统，不会只让 AI 读代码，而是让 AI 先读领域模型，再读代码。因为代码告诉 AI “现在怎么做”，领域模型告诉 AI “为什么必须这么做”。

跨域链路模型

领域模型不能只停留在单个服务内部。对复杂后端系统来说，很多真正高风险的业务规则，存在于多个领域之间的协作链路中。

例如，下单链路可能涉及用户、营销、订单、库存、支付、风控、履约、通知等多个服务；退款链路可能涉及订单、支付、资金、库存、优惠券、结算、用户通知等多个系统；会员权益链路可能从支付成功开始，经过订单确认、会员开通、权益发放、消息通知和后台对账。任何一个局部服务的修改，都可能影响整条业务链路的一致性。

因此，AI Friendly 的后端系统不仅需要单领域模型，还需要跨域链路模型。AI 需要知道一条核心业务链路由哪些服务组成，每一步是同步调用还是异步事件，每一步失败后如何补偿，哪些步骤允许最终一致，哪些步骤必须强一致，哪些消息可以重复消费，哪些状态不能逆转，哪些异常需要人工介入。

如果没有跨域链路模型，AI 很可能在单个服务内部完成一个“局部正确”的修改，却在全局业务链路上制造不一致。比如它可能只看到订单服务需要新增一个状态，却不知道支付服务、履约服务、结算服务和运营后台都依赖原有状态语义；也可能只看到某个异步事件消费慢，就把异步流程改成同步调用，却破坏了原本用于削峰、隔离和补偿的架构设计。

所以，领域模型要回答“一个业务对象内部如何流转”，跨域链路模型要回答“多个业务域之间如何协作”。前者保护实体不变量，后者保护系统级一致性。

05 Skill-Based

把团队经验封装成 AI 可调用的工程能力

AI Coding 不是只靠大模型本身。真正影响效率的，是模型外部的工具、上下文、流程和约束，也就是广义上的 Harness。

在后端系统里，团队应该把高频工程任务沉淀为 SKILL。

这里的 SKILL 可以理解为一种可复用的任务包，包含任务说明、上下文入口、操作步骤、工具命令、校验方式、风险提示、输出格式。

它不是普通文档，而是给 AI Agent 执行任务时调用的“操作手册”。

典型案例：

例如，一个订单系统可以有这些 SKILL：

• 新增一个内部查询接口。

• 新增一个异步消息 consumer。

• 新增一个数据库字段并完成灰度兼容。

• 新增一个订单状态。

• 排查某个接口 TP99 升高。

• 排查 Kafka 消费堆积。

• 修复线上空指针异常。

• 给某个接口增加限流。

• 把同步调用改为异步事件。

• 为历史数据写一次性修复脚本。

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

第一，适用场景

告诉 AI 什么时候应该使用这个 SKILL，什么时候不应该使用。

第二，输入信息

比如服务名、接口名、实体名、字段名、topic 名、错误日志、traceId、需求描述。

第三，相关文件

比如 controller、service、repository、domain、DTO、mapper、schema、test、配置文件位置。

第四，操作步骤

比如先修改 IDL，再生成代码，再补业务逻辑，再补单测，再更新接口文档，再跑契约测试。

第五，风险检查

比如是否影响老版本客户端，是否需要灰度开关，是否涉及数据迁移，是否需要补偿脚本。

第六，验证命令

比如本地测试命令、集成测试命令、lint 命令、schema 检查命令。

第七，输出要求

比如 PR 描述必须包含变更点、兼容性、测试结果、回滚方式。

这样的 SKILL 越多，AI Agent 越不需要“猜”。它不再像一个刚入职的新人到处翻代码，而像一个被训练过的团队成员，知道这个团队做事的路径。

SKILL 化还有一个重要价值：它能把高级工程师的经验复制出来。很多团队的效率差异，不是工具差异，而是经验差异。

资深工程师知道“加字段要先兼容写、再兼容读、再回填、再切流量、最后清理旧字段”，新人和 AI 可能不知道。把这些经验沉淀成 SKILL，本质上是在把组织经验变成可执行资产。

06 Harness Augmentation

为 AI Agent 建立安全的执行轨道

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

对于后端无人值守开发来说，不能让 AI Agent 直接拥有无限权限。它必须运行在一套受控 Harness 里。

一个面向后端系统的 Harness 至少应该包含几层。

第一是上下文装载层

根据任务自动加载相关 Service Card、领域模型、接口文档、数据库 schema、最近 PR、相关事故、监控指标，而不是把整个代码库一股脑塞给模型。上下文要精准、分层、可追溯。

第二是工具层

AI 可以调用代码搜索、文件编辑、测试执行、依赖分析、日志查询、trace 查询、数据库只读查询、配置查询、接口 mock、文档生成等工具。工具必须有权限边界。例如生产数据库默认只读，敏感表脱敏，危险命令禁止执行。

第三是计划层

AI 在修改前必须输出计划，说明要改哪些文件、为什么改、预期影响是什么。低风险任务可以自动继续，高风险任务需要审批。

第四是执行层

每次修改应该在独立分支、独立 worktree、独立 sandbox 中完成。AI 不能污染主干环境，也不能直接修改共享开发环境。

第五是验证层

执行完成后，必须跑对应测试，包括单测、集成测试、契约测试、静态检查、安全扫描、schema 检查。没有验证的 AI 修改不应该进入 PR。

第六是审计层

AI 做过什么、读过什么、改过什么、执行过什么命令、为什么做这个决策，都要有记录。未来无人值守开发不是“不需要责任”，而是需要更强的可追溯性。

第七是回滚层

AI 生成的变更必须附带回滚方案。如果涉及配置、数据库、消息、缓存、数据修复，还要说明如何恢复。

Harness 的核心不是“让 AI 更自由”，而是“让 AI 在正确轨道上更高效”。越是大型后端系统，越不能依赖模型自觉，必须依赖工程化约束。

更进一步

Harness 不应该只是 AI 的执行环境，还应该成为全局架构规则的执行器。

架构师可以把系统分层、服务依赖方向、数据所有权、消息规范、核心链路约束、强依赖准入规则写成机器可检查的 Architecture Policy。

AI 在提交计划或修改代码时，Harness 自动检查这些变更是否违反架构边界。

例如，BFF 层是否直接写入核心业务库，非 owner 服务是否访问了其他服务私有表，核心交易链路是否新增了未登记的同步 RPC，基础服务是否反向依赖了业务服务，异步解耦链路是否被改成强同步调用。

这些问题过去依赖架构师 Code Review 发现，未来应该尽量通过 Harness 自动发现。

这意味着，AI Friendly 的架构治理不能只靠文档，而要变成可执行的策略。

07 Test-Gated AI Development

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

AI Friendly 的后端系统，测试不是锦上添花，依然是最关键的安全边界。

过去很多团队测试不足，是因为有人类经验兜底。开发知道哪些地方不能乱动，测试知道重点回归哪里，运维知道出问题怎么处理。

但 AI Agent 参与开发后，系统必须用自动化测试表达更多工程约束。

首先是单元测试

核心领域逻辑必须有足够的单测，尤其是不变量、状态机、金额计算、权限判断、风控规则。AI 修改代码后，单测应该能第一时间发现它破坏了业务规则。

其次是契约测试

微服务之间的接口（API）契约必须稳定。AI 新增字段、删除字段、修改枚举、调整错误码，都可能影响调用方。契约测试可以防止它只在当前服务内测试通过，却破坏跨服务兼容性。

第三是集成测试

尤其是订单、支付、库存、消息这类链路，必须有端到端测试环境。AI 不能只验证一个函数，它需要验证完整业务流。

第四是回归用例库

每次线上事故、重要 bug、历史兼容问题，都应该沉淀成回归用例。这样 AI 不会反复踩同一个坑。

第五是数据迁移测试

后端系统里最危险的变更之一是 schema migration。AI 新增字段、改索引、拆表、迁移数据时，必须验证兼容性、耗时、锁表风险、回滚脚本。

第六是性能测试

对于高 QPS 接口，AI 的修改可能引入 N+1 查询、缓存击穿、额外 RPC 调用、锁竞争。性能基准测试应该成为核心链路变更的必要门槛。

第七是架构验证—— AI 时代大型分布式系统更需要注意的

除了传统测试，AI Friendly 的后端系统还需要架构级测试。

架构级测试不是验证某个函数返回值，而是验证系统结构是否被破坏。例如服务依赖是否违反分层规则，领域服务是否被 BFF 反向污染，非 owner 服务是否直接访问了其他服务数据库，核心链路是否新增了未备案的强依赖，消息 schema 是否破坏兼容性，数据库 migration 是否可能造成锁表风险。

对人类来说，这些问题往往在架构评审或 Code Review 中发现；

对 AI 来说，必须尽量变成自动化检查。否则 AI 每次局部修改都有可能悄悄侵蚀系统边界。

我理解AI 时代测试体系的价值，不再只是告诉人“代码有没有错”，尤其Agent 时代，更需要告诉 AI “你有没有资格继续往下走”。测试会成为 AI Agent 的交通信号灯—— 或者也可以叫“关键checkpoint”。

08 AI-Observable Architecture

可观测性要变成 AI 的眼睛

无人值守开发不只包括写代码，还包括排障、修复、优化和自愈。

要做到这一点，AI 必须能看见系统运行状态。

传统可观测性主要面向人类：dashboard 给人看，日志给人查，告警发到群里。

AI Friendly 的可观测性要进一步结构化。

日志要有统一格式

必须包含 traceId、spanId、userId 或脱敏后的主体标识、bizId、errorCode、耗时、关键状态。自然语言日志可以保留，但关键字段必须结构化。

错误码要有语义

不能所有异常都叫 SYSTEM_ERROR。AI 需要通过错误码判断是参数问题、依赖超时、库存不足、权限失败、幂等冲突还是数据不一致。

Trace 要能关联业务实体

AI 排查订单问题时，应该能从 orderId 找到完整调用链、消息链、数据库变更和状态流转。

指标要有业务含义。除了 CPU、内存、QPS、延迟，还要有订单创建成功率、支付成功率、退款失败率、库存扣减失败率、消息积压量、风控拦截率等业务指标。

告警要有 Runbook

每个告警都应该关联处理手册：可能原因、排查步骤、常用查询、风险等级、临时止血方式、长期修复建议。没有 Runbook 的告警，对 AI 来说只是噪音。

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

其实在现在大型互联网公司的开发实践中，以上内容都有不同程度的实践和实现。不过我们仍然能看到有很多线上问题的排查是要依赖研发工程师 “Human Explanation” （人工解释）的。

在AI 时代，可观测过程的结构化，就会变得更重要。

09 Tiered Access Control 权限分级策略

数据和权限：AI Friendly 不能以牺牲安全为代价

大型后端系统一旦引入 AI Agent，就必须重新设计权限边界。

AI 可能需要读代码、查日志、跑测试、访问测试数据库、查询监控、读配置、操作分支、创建 PR。这些权限如果不分层，很容易出事故。

比较合理的做法是建立分级权限模型，比如我们尝试划分一下典型分层如：

分级权限模型

• L0：只读代码和文档。适合问答、解释、影响面分析。

• L1：允许在本地 sandbox 修改代码和运行测试，但不能访问真实数据。

• L2：允许查询脱敏日志、测试环境数据库、监控指标。

• L3：允许创建 PR、触发 CI、生成灰度配置，但不能直接发布。

• L4：允许在低风险服务上自动合并和发布，但必须满足测试、灰度、回滚条件。

• L5：允许执行生产修复动作，例如回滚、降级、扩容、切配置，但必须受到强审计、强策略和人类预授权约束。

AI Friendly 不是把权限全部给 AI，而是让 AI 在不同风险场景下获得刚好足够的权限。

这里列举得相对详细全面一些，实际过程中，集团内部或者相关BU 也在做一些比如代码分级、权限分级实践等。建议大家可以按照自己BU 或者业务特色进行思考与设计。

数据安全

数据安全也需要特殊处理，无论是国际化合规业务需要，还是目前按照中国的网络安全等相关法规的要求，数据安全也是非常重要的一环。按照目前各国法律的合规要求，以及历史开发经验，我们可以尝试进行类似下方的总结：

• 日志中的手机号、身份证、邮箱、地址、支付信息、token、cookie、密钥都必须脱敏。

• AI 不应该直接接触明文敏感数据。

• 生产数据库查询应该默认只读、限行数、限字段、限时间窗口，并且全量审计。

• 密钥、证书、生产配置必须通过专门的 secret manager 管理，不能出现在 prompt、日志或代码生成上下文里。

未来 AI Agent 越强，安全边界越重要。因为一个能力弱的 AI 最多写错代码，一个能力强但权限失控的 AI 可能直接制造生产事故。

10 Code Navigation Framework

代码结构要可导航：让 AI 少猜路径

AI 修改代码的效率，很大程度取决于代码结构是否可导航。

一个 AI Friendly 的后端代码库，应该有稳定的目录约定、命名约定和分层约定。例如 controller / application / domain / infrastructure / repository / client / config / test 的边界要清楚。DTO、DO、Entity、VO、Command、Event、Mapper 不要混用。服务调用、消息发送、缓存访问、数据库访问不要散落在任意位置。

更重要的是，代码中要减少“隐式魔法”。过度复杂的反射、动态代理、运行时拼接、隐式扫描、约定大于配置，如果没有足够文档，会让 AI 很难判断真实调用关系。不是说这些技术不能用，而是必须让它们可解释、可追踪、可测试。

代码还应该提供足够的“导航锚点”。例如：

• 每个接口有明确入口。

• 每个领域实体有独立文件。

• 每个状态机有集中定义。

• 每个外部依赖有 client 封装。

• 每个消息 topic 有 producer / consumer 定义。

• 每个配置项有说明和默认值。

• 每个数据库表有对应 repository。

这是为了降低 AI 的搜索成本和误判概率。AI 越容易找到正确位置，越不容易在错误层级乱改。

11 Docs/Architecture as Code

文档即代码：文档必须参与 CI

文档如果不进入工程流程，就一定会腐化。

AI Friendly 的文档应该遵循 Docs as Code 原则。

文档放在仓库里，和代码一起 review，一起版本管理，一起参与 CI 检查。

例如：

• 新增接口时，必须更新 OpenAPI 或 IDL。

• 新增数据库字段时，必须更新 schema 文档和字段说明。

• 新增消息 topic 时，必须更新消息契约。

• 新增配置项时，必须写明默认值、作用域、是否支持热更新。

• 新增领域状态时，必须更新状态机。

• 修改核心逻辑时，必须更新对应 SKILL 或 Runbook。

CI 可以检查这些内容是否缺失。

比如检测到新增 controller 但没有更新接口文档，新增 migration 但没有字段说明，新增 consumer 但没有 topic 文档，就阻止合并。

架构即代码：Architecture as Code

对大型后端系统来说，仅仅 Docs as Code 还不够，还需要 Architecture as Code。所谓 Architecture as Code，是把架构分层、服务归属、依赖方向、数据所有权、消息契约、核心链路、风险等级、发布边界等信息，用结构化文件维护，并让它们参与 CI/CD。

例如，可以用 architecture.yaml 描述业务域、服务分层、允许的依赖方向；用ownership.yaml 描述每张表、每个 topic、每个 API 的 owner；用 critical-path.yam 描述核心链路和延迟预算；用 risk-policy.yaml 描述不同风险等级下 AI 可以自动执行到哪一步。

这样，全局架构就不再只是 PPT 或 Wiki 页面，而是可以被 AI 读取、被 CI 校验、被 Harness 执行的工程资产。

这类规则对人类开发也有帮助，但对 AI 尤其关键。因为 AI 未来会频繁生成代码，如果没有文档同步约束，系统会很快进入“代码越来越多、知识越来越乱”的状态。

12 从 Copilot 到 Coworker，再到 Operator

我认为，后端系统 AI Friendly 的建设，可以分三个阶段。

第一阶段是 Copilot

AI 主要辅助人类写代码、补测试、解释代码、生成文档。此时系统只需要基本文档、代码规范和测试入口。在过去两年，大家已经经历过这个阶段，并已经快速过渡到了下面的第二阶段。

第二阶段是 Coworker

AI 可以独立完成中低风险任务，例如新增接口、修 bug、补单测、写 migration、改配置、生成 PR。此时系统需要 Service Card、SKILL、领域模型、契约测试、CI 约束。

目前业界众多的 Vibe Coding Agent 已经基本能做到这种能力水平，确实给广大开发者、工程师带来了巨大的效率提升。

在这个阶段之后，大家经常思考的就是，能不能把当前需要“人类干预”的阶段变得更少，从而使得整个流程更加高效呢？就类似于现代工业化“黑灯工厂、黑灯生产线”一样 —— 整个工厂里都是机器手臂、机器人在精确配合，不需要人类参与、不需要可视化的光源，所以可以直接关掉工厂可视化灯光，变成“黑灯工厂”。

第三阶段是 Operator

这个阶段，就是 Vibe Coding 时代的“黑灯工厂”了。

我们认为和希望在这个阶段，AI 可以参与线上值守，接收告警、分析日志、定位问题、提出修复、执行回滚、生成复盘、沉淀 Runbook。此时系统需要完整可观测性、权限分级、审计、自动化发布、灰度、回滚和安全策略。

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

13 Practical Roadmap

一个可落地的改造路线

如果一个团队现在有几十个微服务，想开始做 AI Friendly，不建议一上来搞宏大的平台。更现实的路线是分阶段推进。

更可行的方案是先建立一份最小可用的全局 Architecture Map。不需要一开始覆盖所有细节，但至少要标出业务域划分、核心链路、服务分层、核心依赖、数据所有权、消息主干、风险等级和历史遗留模块。它的作用不是追求完美，而是帮助团队和 AI 先获得系统级方向感。然后再不断细化、不断深入建设更多细节、支持更多研发阶段的自动化实践。

比如，我们总结了一个相对可行的 AI Friendly 改造 Roadmap：

• 第一步，选择一个中等复杂度、风险可控的业务域作为试点。不要选最边缘的玩具服务，也不要选支付、资金这类最高风险服务。最好选择有真实复杂度但可灰度、可回滚的服务。

• 第二步，先建立一份最小可用的全局 Architecture Map。不需要一开始覆盖所有细节，但至少要标出业务域划分、核心链路、服务分层、核心依赖、数据所有权、消息主干、风险等级和历史遗留模块。它的作用不是追求完美，而是帮助团队和 AI 先获得系统级方向感。初始阶段的 Architecture Map 可以很粗，但必须真实；可以不完整，但不能误导。后续随着 Service Card、领域模型、SKILL、Runbook 的沉淀，再逐步让这张地图变得更细、更准、更可执行。

• 第三步，为试点服务补齐 Service Card。把服务职责、依赖、接口、数据、消息、测试、发布、回滚写清楚。

• 第四步，梳理核心领域模型。至少明确核心实体、状态机、不变量、幂等规则。

• 第五步，沉淀 5 到 10 个高频 SKILL。比如新增查询接口、修复 bug、补单测、加字段、消费消息、排查告警。

• 第六步，补测试和契约。不要追求一次性覆盖所有代码，而是先覆盖核心链路和高频变更点。

• 第七步，建立 AI PR 模板。要求 AI 输出变更说明、影响面、测试结果、风险点、回滚方案。

• 第八步，把 CI 变成硬门槛。没有通过测试、文档检查、安全扫描的 AI 变更不能合并。

• 第九步，接入只读可观测工具。允许 AI 查询日志、trace、指标，但必须脱敏、限权、审计。

• 第十步，允许 AI 做低风险自动 PR。先不自动合并，让人类 review AI 的产出质量。

• 第十一步，逐渐扩大到更多服务和更复杂任务。

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

14 What’s the future ?

AI Friendly 最终改变的是软件组织方式

过去，一个优秀团队依赖人的经验、默契和长期积累。未来，一个优秀团队要把这些经验变成结构化资产，让 AI 可以读取、调用、执行、验证。过去，文档是给新人看的；未来，文档更是给 Agent 执行任务时装载上下文用的。

过去，测试是为了防止上线出 bug；未来，测试是为了约束 AI 的行动边界。

过去，Runbook 是故障时翻看的手册；未来，Runbook 是 AI 自动排障的操作图谱。

过去，架构治理靠会议和 review；未来，架构治理会越来越多地通过规则、元数据、CI、权限和 Harness 自动执行。

所以，后端系统要做到 AI Friendly，不是简单买一个 AI Coding 工具，而是要重新整理系统知识、工程流程和组织经验。

我们认为，一个真正 AI Friendly 的后端系统，应该具备这样的特征，是更加的AI 友好化，并且高效能的：

• AI 能快速知道每个服务负责什么。

• AI 能理解核心实体和业务不变量。

• AI 能找到正确代码位置，而不是全局乱搜。

• AI 能按照团队沉淀的 SKILL 完成任务。

• AI 能在受控 Harness 中修改、测试、提交。

• AI 能通过自动化测试验证自己的改动。

• AI 能读取脱敏后的运行态信息进行排障。

• AI 的每一步操作都有权限边界和审计记录。

• AI 生成的每个变更都有影响面分析和回滚方案。

• AI 在低风险场景中可以自动推进，在高风险场景中知道停止并请求人类决策。

这才是面向未来AI 友好化的后端系统。

AI Friendly 不是为了讨好 AI，而是为了让系统知识更清晰、工程流程更规范、风险控制更自动化。

即使没有 AI，这些改造也会提升团队效率；而一旦 AI Agent 成熟，这些改造会成为团队能否进入无人值守开发时代的分水岭。

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

谁先完成这层转变，谁就有可能更快的把 AI Coding 从“代码生成工具”升级成真正的“工程生产力系统”。