版本说明：本文基于 Claude Code v1.x 与 OpenCode v1.2.x 的微服务项目接入实践撰写，适用于企业级多服务架构团队。

适用对象：架构师、技术负责人、高级开发者。

前置知识：第12篇项目接入AI、第14篇MCP企业级管理。

一、微服务项目的AI接入挑战

第12篇介绍了AI接入的通用方法，适用于单体应用或简单项目。但当项目演进到微服务架构时，AI接入的复杂度会呈指数级增长。

Martin Fowler 在其微服务指南中指出，微服务的核心特征是去中心化治理和去中心化数据管理 。这意味着每个服务有自己的技术栈、编码规范和数据模型。对AI来说，这直接导致三个问题：

这三个问题不是互相独立的——服务间依赖越复杂，需要跨仓库读取的文档越多，上下文窗口的压力就越大。

二、微服务文档体系设计

三层文档架构

解决上述挑战的核心手段是建立分层的文档体系。文档不是给AI看的说明书，而是AI的"项目地图"——告诉它这个项目有哪些服务、服务之间怎么交互、每个服务有什么特殊规则。

文档分为三层：

ArunIyer 在其文章中指出，AGENTS.md 不是给人看的文档，而是给 AI 队友的入职手册 。这个定位决定了总控文档（即 AGENTS.md）的写法：不是描述"这个项目是什么"，而是告诉AI"你应该怎么在这个项目里工作"。

总控文档与服务文档的分工

总控文档（仓库根目录）：
- 项目有哪些服务，各自的职责和端口
- 服务之间的调用关系和协议
- 全局编码规范（适用于所有服务）
- 公共依赖的版本和配置
- 团队联系人和服务Owner

服务文档（各服务根目录）：
- 本服务的架构和技术栈
- 本服务的编码规范和特殊约定
- 本服务的测试要求和覆盖率标准
- 本服务的环境配置要求
- 本服务的常见问题和FAQ

关键原则： 总控文档回答"全局是什么样"，服务文档回答"这个服务怎么改"。AI 先读总控文档建立全局认知，再深入具体服务的文档理解局部细节。

三、总控文档的企业级模板

AGENTS.md 标准模板

以下是一个适用于5个以上微服务项目的 AGENTS.md 模板：