前两天看到一张图讲怎么在很多微服务之间使用 AI Agent。里面有个问题很典型。一个公司有十几个微服务现在想让开发用 Agent 来做系统设计和编码。但一个 user story 经常不是改一个服务就结束了它可能从前端进来穿过用户服务、订单服务、库存服务、支付服务最后还要落到消息队列和异步任务里。这时候你把任务丢给 Agent它要理解的就不是某一段代码。它要理解边界。哪个服务拥有用户状态哪个服务只是缓存一份投影哪个字段是外部合同哪个字段只是内部实现哪段逻辑能改哪段逻辑一改就会影响下游对账。问题就在这里。单体应用里Agent 至少还能在一个代码树里一路 grep 下去。微服务系统里真正麻烦的是那些没有写在一个文件里的知识职责边界、业务概念、调用约定、历史债、异常语义、重试策略、幂等规则。所以很多团队的第一反应是把所有微服务放到一个 workspace 下面每个服务配自己的文档让 AI 自己读。这个方向对吗我自己的判断是对但远远不够。把仓库放在一起只是把门打开了。Agent 能不能真的干活取决于你有没有给它一张地图以及它改完以后能不能自己验证。一个 workspace 是必要条件但不是充分条件先承认一点把多个服务放到一个 workspace 下确实是目前很务实的做法。如果你本来就是 monorepo那很适合 Agent。schema 定义、API 协议、共享类型、服务实现、测试代码都在一个地方。Agent 不需要在十几个仓库之间来回切换也不需要靠你一段段复制上下文。它可以自己搜索调用链自己找接口定义自己对照测试。这对 Agent 很重要。因为 Agent 最怕的不是代码多。它最怕的是缺关键上下文。一个用户故事跨了三个服务如果 Agent 只看到了其中一个服务它就很容易做出局部正确、系统错误的设计。它可能在订单服务里加了一个状态却不知道支付服务已经用另一个字段表达同一件事它可能改了一个返回结构却不知道前端 BFF 和下游数据同步任务都依赖这个结构。如果历史原因不方便合成 monorepo也没必要硬迁移。一个折中办法是虚拟 monorepo把多个仓库 clone 到同一个本地目录里外面套一层统一的 workspace。代码仍然是多个 repo日常发布和权限边界不变但 Agent 工作时能看到一个相对完整的系统视图。这一步能解决很多基础问题。但它解决不了全部。因为“看得到”不等于“看得懂”。十几个服务全部摊在 Agent 面前有时候不是帮助而是噪音。你给它一整座城市它也许能找到路也许会迷路。真正有用的不是把所有东西都塞进上下文而是告诉它从哪里开始哪些东西相关哪些东西暂时不用看。这就是 Context Engineering 的核心味道。Anthropic 在讲 context engineering 的时候有个判断我很认同Agent 不是上下文越多越好而是要在正确时间拿到正确上下文。上下文窗口再大也不应该变成垃圾场。放到微服务里这句话尤其要紧。Agent 需要的不是文档堆而是服务地图很多团队会说我们有文档。但你点进去一看经常是这种形态Confluence 里几百页接口文档散在几个目录架构图是三年前的某个 README 写着“详见新版本文档”新版本文档又链接回旧页面。人都不愿意看。Agent 更不会神奇地看懂。给 Agent 的文档最好不要从“大而全”开始而是从“地图”开始。我会建议做三层。第一层根目录放一份总索引。可以叫AGENTS.md也可以叫CLAUDE.md名字没那么重要关键是它的职责要清楚告诉 Agent 这个 workspace 里有哪些服务每个服务负责什么改某类需求时应该先看哪些目录哪些命令可以跑哪些命令不能随便跑。它不是百科全书。它是机场指示牌。比如/identity-service 负责用户身份、登录态、权限校验 业务概念User、Account、Session、Role 深入文档identity-service/AGENTS.md API specidentity-service/openapi.yaml 契约测试identity-service/contracts/ /billing-service 负责订阅、账单、支付状态同步 注意不拥有用户权限只消费 identity 的 account projection这种信息对 Agent 的价值非常高。它不需要一上来读完所有服务的所有文档。它先读根索引判断当前 user story 可能涉及 identity、billing、notification然后再去加载这几个服务的细节。第二层每个服务目录里放自己的边界说明。这份文档不要写成“本服务采用 Spring Boot MySQL Redis”。这些 Agent 读代码就能知道。真正该写的是代码里不容易直接看出来的东西这个服务拥有哪些业务事实哪些概念属于它哪些概念只是从别的服务同步过来的它对外承诺哪些 API 语义哪些字段不能随便改名哪些状态转换有业务含义哪些下游调用依赖幂等、重试、顺序或最终一致性这其实就是 DDD 里的 bounded context只是你不用把它写得像 DDD 教材。Agent 不需要口号它需要边界。第三层给 Agent 明确上下文路由规则。比如如果任务涉及“用户是否有权限购买套餐”先读 1. /identity-service/AGENTS.md 2. /billing-service/AGENTS.md 3. /contracts/identity-billing/ 不要直接修改 notification-service除非 contract test 指向它。这类规则很土。但很有用。它相当于把资深工程师脑子里的“先看哪里、别碰哪里、这里以前踩过坑”写下来。对人有帮助对 Agent 更有帮助。文档最大的问题是它会老但只靠文档还有一个硬伤。文档会老。而且微服务文档老得特别快。一次接口新增字段一次错误码调整一次异步事件 payload 改动一次数据库状态枚举扩展都可能让文档和代码开始偏离。人类工程师有时候还能靠记忆和群聊补齐Agent 没有这种组织八卦能力。它会相信你给它的上下文。过期文档对 Agent 的伤害比没有文档还大。没有文档时它至少会去读代码、跑测试、问你确认过期文档会给它一种虚假的确定感。所以我越来越倾向于一个原则能从代码或规格生成的就不要手写。OpenAPI spec 就是典型例子。一份写得好的 OpenAPI不只是给人看的接口文档。它还可以生成 SDK生成 mock server生成 contract test 的输入甚至作为 Agent 理解服务边界的机器可读材料。它比一段“用户服务提供登录接口”的自然语言可靠得多。因为它会告诉 Agent这个 endpoint 是POST /sessions。请求体有哪些字段。哪些字段必填。响应状态码有哪些。错误结构长什么样。这就从“描述”变成了“规格”。更进一步如果你已经有 Pact 契约文件或者有成熟的 consumer-driven contract testing那就更好。因为 contract test 本身就是活文档。它不是某个人写在 wiki 里的愿望而是调用方真实依赖的接口形状。调用方说我实际用了这些字段、这些状态码、这些交互序列。被调方每次变更都要验证自己仍然满足这些契约。这东西对 Agent 很值钱。它可以读契约知道服务之间真正发生了什么也可以改完代码以后跑契约测试知道自己有没有破坏别人。微服务里最容易出问题的地方恰好就是“我以为没人用”和“你怎么会这么用”。契约测试把这两句话提前变成测试失败。这比事后开会体面多了。真正难的是验证不是生成代码很多团队引入 Agent 的时候最先关注的是代码生成质量。这个当然重要。但在微服务场景里我觉得更应该先问另一个问题Agent 写完以后它怎么知道自己没搞坏单服务还好办。跑单元测试。跑类型检查。跑本地集成测试。最多再起一个数据库和 Redis。跨微服务就麻烦了。一个 user story 可能涉及三五个服务外加消息队列、对象存储、第三方支付、权限系统。你不可能让 Agent 每改一次代码就把完整生产级环境在本地跑起来。就算能跑成本也太高。于是很多 Agent 工作流会卡在这里它能写代码但验证不了它能解释方案但不知道方案在系统里能不能跑通。最后还是人来做集成验证人来盯日志人来判断哪里不对。这就回到了老问题。人重新变成循环里的慢部件。要让 Agent 真正参与系统设计和编码你得给它一个更轻的验证环境。我的建议是每个服务至少提供两类东西。一类是 mock server。它可以手写也可以基于 OpenAPI spec 自动生成。关键是 Agent 在改某个服务时不需要把所有依赖服务都真实启动起来。它可以面对一个足够稳定的模拟对手验证自己的请求格式、响应处理和异常分支。另一类是 contract test。它验证的不是“整个业务流程是不是完全正确”而是“服务之间约定的协议有没有被破坏”。这个边界很重要。端到端测试当然有价值但它太重不适合作为 Agent 高频自我修正的主循环。contract test 更轻、更快、更贴近服务边界适合放在 Agent 的本地工作流里。一个比较实用的闭环是这样Agent 读根AGENTS.md。定位相关服务。读取服务边界文档、OpenAPI spec、契约文件和相关测试。提出设计。修改代码。启动 mock server。跑 contract test。根据失败信息自我修正。再跑。直到测试通过或者明确停下来告诉人类当前契约和需求冲突需要你做产品或架构判断。这才是 Agent 真正能干活的地方。不是一次把代码写对。而是它写错了以后有一个系统能让它知道错在哪里。不要让 Agent 直接面对整个系统这里还有一个容易被忽略的点。很多人把“让 Agent 理解全局”理解成“让 Agent 读取全部”。这两个不是一回事。一个资深工程师做跨服务设计也不会把十几个服务每一行代码都读完。他会先建立系统地图找到相关边界再深入关键路径。Agent 也应该这么工作。所以 workspace 的设计目标不是让 Agent 一次性吞掉整个系统而是让它能按需导航。这也是我觉得根AGENTS.md特别重要的原因。它不是为了喂满上下文。它是为了减少上下文。好的索引会把 Agent 从“全仓库漫游”拉回“任务相关路径”。好的服务文档会把 Agent 从“读代码猜业务”拉回“先理解边界再看实现”。好的契约测试会把 Agent 从“我觉得这样没问题”拉回“协议有没有被破坏”。这三件事组合起来才像一个可运行的 Agent 工作台。Anthropic 在 long-running agents 那篇文章里提到一个很实在的做法长任务要给 Agent 搭 harness包括进度记录、验证脚本、干净的工作状态让它能跨长时间任务继续推进。放到微服务协作里harness 不是一个抽象概念。它就是这些东西AGENTS.md。服务边界文档。OpenAPI spec。mock server。contract tests。本地启动脚本。测试命令。失败时该看哪里的日志。哪些目录只读。哪些变更必须人工确认。这些东西看起来不酷。但它们决定 Agent 是“会写代码的聊天框”还是“能在你们系统里工作的工程同事”。一个更靠谱的三层搭法如果让我给一个十几个微服务的团队设计 Agent 工作方式我不会从“买哪个 Agent 产品”开始。我会先搭三层。第一层统一 workspace。能 monorepo 就 monorepo。不能就虚拟 monorepo。至少让 Agent 在一个地方看到相关服务、共享协议、测试和文档。这一层提供全局视图。第二层分层上下文。根目录有系统索引每个服务有边界说明协议规格尽量机器可读。人写的文档只写代码和 spec 难以表达的内容比如业务语义、历史决策、例外规则、危险区域。这一层提供精准上下文。第三层验证闭环。每个服务提供 mock server 或模拟依赖核心服务之间建立 contract test。Agent 改完以后必须能在本地跑一组足够快、足够准的验证而不是把所有风险都留给人类集成测试。这一层提供自我修正能力。这三层搭起来以后Agent 的工作方式会发生变化。以前你可能是这样用“帮我改一下订单状态逻辑。”然后你把相关代码贴给它它改一版你再告诉它哪里不对。新方式应该更像这样“根据根 AGENTS.md处理 story-123。先识别涉及的服务和契约提出设计不要修改无关服务。改完后启动 billing 依赖的 mock server跑 identity-billing 和 billing-notification 的 contract tests。失败就自我修正三轮仍失败再停下来说明原因。”这个 Prompt 不一定优雅。但它工程上更靠谱。因为它把 Agent 放进了一个可验证的循环里。写在最后我现在看 Agent 工程越来越觉得它和新员工入职有点像。你不能把一个新同事拉进几百个群丢给他十几个仓库然后说“你自己理解一下系统明天开始做跨服务设计。”这不叫授权。这叫放生。真正靠谱的团队会给他系统地图会告诉他服务边界会指明哪些文档可信哪些接口有契约哪些测试必须跑哪些地方以前出过事故。Agent 也是一样。它读得快写得快跑命令也快。但它不天然知道你们公司的业务边界不天然知道某个字段背后的历史包袱也不天然知道一个接口变更会把哪个下游打穿。所以问题不是“要不要把十几个微服务放到一个 workspace 下”。要。但更关键的问题是你们有没有把一个复杂系统整理成 Agent 可以导航、可以理解、可以验证的工作环境。统一 workspace 给它眼睛。分层文档和协议测试给它判断。mock server 和 contract test 给它反馈。三层都在Agent 才有机会从“帮我补几行代码”走到“参与跨微服务系统设计”。这件事说到底不是 AI 魔法。还是工程。只不过这一次我们不是只给人类工程师搭工程体系。我们也要给 Agent 搭。参考资料Anthropic, Effective context engineering for AI agents[1]Anthropic, Effective harnesses for long-running agents[2]Datadog Frontend Platform, Steering AI Agents in Monorepos with AGENTS.md[3]Pact, Consumer driven contract testing[4]引用链接[1]Effective context engineering for AI agents:https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents[2]Effective harnesses for long-running agents:https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents[3]Steering AI Agents in Monorepos with AGENTS.md:https://dev.to/datadog-frontend-dev/steering-ai-agents-in-monorepos-with-agentsmd-13g0[4]Consumer driven contract testing:https://docs.pact.io/