简介：当 AI 编码工具进入团队开发流程后，如何让它们准确理解项目规则、构建方式与编码约束，成为提升协作效率的关键。本文介绍一种在仓库中放置上下文文件来指导 AI 代理工作的通用做法，涵盖其由来、文件设计要点、monorepo 场景下的组织方式，以及从个人使用到团队落地的最佳实践，帮助开发者减少重复解释、降低 AI 误操作风险。
在软件工程中，README 早已成为项目入口的事实标准。它告诉新加入的开发者：这个项目做什么、如何启动、依赖什么环境、遵循哪些约定。但当协作对象从人类扩展为 AI 编码代理时，情况发生了变化。
AI 编码代理可以在几秒内扫描整个仓库，但它并不天然知道哪些目录是核心模块、哪些文件是自动生成的、哪些测试命令是必须通过的、哪些编码风格是团队强制要求的。如果每次会话都要重新解释这些规则，不仅低效，而且容易出现“代理按通用默认行为操作”导致的偏差——例如使用了项目禁用的依赖、忽略了特定的提交规范，或在不该修改的生成文件上动手。
解决思路非常朴素：把需要告诉 AI 的上下文，用一份结构化文件沉淀在仓库里，让代理在开始工作前自动加载。 这正是 AGENTS.md 这一类实践的核心价值。它不依赖任何特定工具或平台，本质是一种工程协作约定。
AGENTS.md 是一个放置在代码仓库中的 Markdown 文件，用于向 AI 编码代理提供项目级的工作指令。可以把它视为 AI 代理的“入职手册”——README 面向人类读者，AGENTS.md 则面向机器协作者。
一个典型的 AGENTS.md 通常包含以下内容：
| 内容类别 | 说明 | 示例 |
|---|---|---|
| 项目概述 | 一两句话说明项目用途与技术栈 | “这是一个基于事件驱动的订单处理服务，使用消息队列解耦生产与消费端。” |
| 构建与测试命令 | AI 需要用到的核心操作 | 使用包管理器安装依赖、执行单元测试、构建生产产物 |
| 代码风格与规范 | 命名约定、目录结构、禁用模式 | 接口命名以 I 开头，禁止在业务层直接访问数据库 |
| 架构约束 | 分层规则、依赖方向、模块边界 | 领域层不得引用基础设施层 |
| 安全注意事项 | 敏感信息处理、禁止操作 | 不得将密钥写入日志或提交到版本库 |
| 提交与部署规范 | commit message 格式、发布流程 | 提交信息遵循“类型(范围): 描述”格式 |
文件的格式没有强制标准，使用常规 Markdown 组织即可。标题层级、列表样式、代码块等都可以根据团队习惯自由定义。关键是内容对 AI 代理有实际指导价值，而不是“为了有文件而建文件”。
在 AI 编码工具兴起的早期阶段，各家产品各自定义了上下文文件的名称和加载规则。有的工具读取特定命名的文件，有的支持在配置目录中放置规则文件，还有的从特定路径加载指令。这种碎片化状态给团队带来了实际困扰：同一份项目规则，需要为不同工具维护多份内容几乎相同的文件，任何一次规则更新都涉及多处同步，遗漏几乎不可避免。
2025 年上半年，社区逐步意识到统一命名约定可以显著降低维护成本。经过讨论与收敛，AGENTS.md（复数形式）作为一种跨工具的文件命名约定被越来越广泛地接受。多种主流 AI 编码工具陆续支持自动发现并加载仓库中的 AGENTS.md 文件，将其内容作为系统提示的一部分注入模型输入。
这一过程反映了一个更普遍的规律：当 AI 成为开发流程中的常驻角色，工程团队的“文档对象”从纯粹的人类扩展为“人类 + 机器”，需要新的协作协议来适配。
创建文件只是第一步，真正有价值的是内容本身。以下是一些经过实践检验的设计原则。
AGENTS.md 不需要重复显而易见的信息。如果项目使用标准构建工具链、标准目录结构、通用框架约定，就不必在文件中赘述。重点放在非标准、非默认、容易出错的信息上：特殊的启动步骤、非典型的环境依赖、团队定制的代码规范、历史的架构决策及其原因。
一段反面示例：
# 项目说明本项目使用版本控制工具管理代码。请使用包管理器安装依赖。
这些内容对所有项目都通用，对 AI 代理没有增量价值。应当替换为：
# 关键约束- 本仓库包含两个独立服务：API 网关与后台任务处理器，共用共享类型包。- 后台任务处理器禁止直接调用 API 网关的 HTTP 接口，必须通过消息队列通信。- 数据库迁移文件按时间戳命名，禁止修改已合入主分支的历史迁移。
AI 代理需要明确的命令来构建、测试和运行项目。模糊的表述（如“运行测试”）会让代理自行猜测，而错误猜测可能造成显著后果。建议给出精确到参数的命令示例：
## 常用命令- 安装依赖：`npm ci`（禁止使用 `npm install`，后者会改动锁文件）- 运行单元测试：`npm run test:unit -- --coverage`- 运行集成测试：`npm run test:integration`，需要本地启动容器化依赖- 代码检查：`npm run lint`，提交前必须通过
AI 代理在自动修改代码时，可能触发敏感操作。AGENTS.md 中应明确列出禁止行为和强制行为：
## 安全红线- 禁止将任何密钥、令牌、连接字符串写入代码、日志或测试断言。- 禁止修改 .env 文件中的生产环境配置。- 禁止在未经确认的情况下执行数据库删除或清空操作。- 所有涉及认证逻辑的改动，必须附带安全审查注释。
AGENTS.md 不是一次性文档。当项目架构调整、构建方式变更、团队规范更新时，这份文件必须同步更新。一个过时的 AGENTS.md 比没有更危险——AI 代理会基于错误上下文做出错误决策。一种实用做法是将 AGENTS.md 的更新纳入常规代码评审流程，任何改变了项目“事实”的改动，都同时更新对应的上下文描述。
对于大型 monorepo，单个根目录下的 AGENTS.md 往往不足以覆盖所有子项目的特殊情况。常见的做法是在子目录中放置额外的 AGENTS.md 文件，AI 代理在操作某个子目录时，会优先读取最近层级的上下文文件，同时参考根目录的全局规则。
一个典型的目录结构：
repo-root/├── AGENTS.md # 全局规则：提交规范、通用安全要求、跨包约定├── services/│ ├── user-service/│ │ ├── AGENTS.md # 用户服务的领域规则、测试约束│ │ └── ...│ └── order-service/│ ├── AGENTS.md # 订单服务的状态机约束、事件发布要求│ └── ...└── packages/├── shared-types/│ └── AGENTS.md # 类型包不可引入运行时依赖└── ...
这种分层设计遵循了“局部优先”原则：越靠近代码的上下文文件，优先级越高，描述也越具体。根目录文件聚焦全局性规则，避免与子目录文件内容重复。
在管理大量 AGENTS.md 文件时，可以借助脚本检查各文件之间的规则冲突。例如，根目录声明“所有服务必须使用消息队列通信”，而某个子目录文件中出现了“该服务在本地开发时可绕过消息队列”，这种差异可能是合理的（仅限本地），也可能是不该出现的矛盾。定期审查可以保持上下文体系的一致性。
AGENTS.md 的生命力在于被真实使用并持续迭代。从个人尝试到团队推广，通常经历三个阶段。
第一阶段：个人试行。 开发者在自己的项目中创建 AGENTS.md，观察 AI 编码代理在加载上下文后的行为变化。此时文件内容可以相对灵活，重在快速验证哪些信息对代理产生了正向影响。
第二阶段：团队推广。 当个体实践产生可感知的收益（如代理误操作减少、代码风格偏差降低），就可以推动团队在共享仓库中建立统一的 AGENTS.md 规范。此时需要明确：文件由谁维护、更新流程是什么、评审机制如何运作。
第三阶段：工程体系集成。 成熟团队会将 AGENTS.md 纳入更广泛的工程治理体系。例如，通过 CI 检查 AGENTS.md 的存在性与新鲜度，在新项目脚手架中自动生成模板，在文档平台中自动索引各仓库的 AGENTS.md 内容。部分团队会结合云上的代码托管与协作平台能力，对上下文文件的版本变更进行追踪和审计。
问题一：文件过长，信息过载。 当 AGENTS.md 超过数百行，AI 代理可能无法有效利用全部信息。解决方案是精简核心规则，将详细说明拆分到独立文档中，在 AGENTS.md 中以链接形式引用。
问题二：规则抽象，缺乏可执行性。 “遵循良好的代码风格”这样的表述对 AI 几乎没有约束力。应该改为可验证的标准：“使用 4 空格缩进”“函数圈复杂度不超过 10”“公开 API 必须包含文档注释”。
问题三：多个上下文来源冲突。 当工具自身的配置、AGENTS.md、代码内注释同时给出指令时，可能出现矛盾。团队需要明确优先级规则，通常建议：AGENTS.md 中的项目级规则优先于通用默认行为，但代码内更具体的指令可以覆盖项目级规则，只要这种覆盖是经过审计的。
AGENTS.md 所代表的，是一种将“隐性工程知识”显性化的努力。它本身并无复杂的技术含量，但却直指一个核心问题：当 AI 越来越多地参与代码生产，团队如何系统性地传递那些“不在代码里、却决定代码质量”的信息？
从实践角度看，一份维护良好的 AGENTS.md 能够显著降低 AI 编码代理的试错成本，让自动化协作更贴近项目的真实约束。它同时也反过来推动团队更清晰地梳理自己的工程规范——因为要把规则写给机器看，就不得不把规则想清楚。这个“被迫想清楚”的过程，本身就是一种工程能力的提升。