像大多数团队一样我们第一次听说 AGENTS.md 时都以为它只是又一份“给 AI 看的 README”。真正意识到这件事没那么简单是在一次 Agent Context 治理把我们折磨得够呛之后——上下文动不动就溢出、AI 反复犯同一个低级错误、规则写了等于没写。回头看AGENTS.md 根本不是普通文档它是一个项目在 AI 时代最核心的上下文基线。这篇文章不聊概念只讲我们在一个真实项目里怎么把 AGENTS.md 从“摆设”变成“约束系统”的全过程包括踩过的坑、改过的话术、以及让规则真正生效的实操细节。适合正在用 AI 辅助写代码、又对上下文管理一头雾水的团队和个人。1. 从“给 AI 看的 README”到上下文基线1.1 为什么普通文档救不了 Agent你打开一个陌生仓库的 README通常会看到“项目简介”“安装步骤”“快速开始”这类内容那是写给人类看的。人会主动跳过已知信息也能靠目录快速定位到自己需要的段落。但 AI Agent 不太一样它在一个新会话里面对整个代码库时几乎没有“常识”可言——它不知道你的技术栈选型是什么、不知道哪些目录是生成产物不能乱碰、更不知道团队内部约定要优先遵循。一开始我们也天真地以为只要仓库文档齐全AI 就能表现良好。结果一测就露馅。它经常自信满满地改了不该改的配置文件或者在错误目录下新建了看似合理实际上完全脱离架构的模块。原因很简单文档存在并不等于文档进了模型的上下文。普通 README 不会在每次会话开始时被自动加载就算加载了它也不是为了“告诉 AI 什么能做、什么不能做”而设计的。AGENTS.md 解决的是另一个问题它要在对话真正开始之前成为唯一确定进入上下文的东西。它不是文档库里的一个可选项而是 AI 对项目建立初始认知的默认起点。我们后来把它称为“项目的意识基线”因为整个会话里的决策质量很大程度取决于开头这几屏内容。注意别再拿 README 改个名就充数。AGENTS.md 的写作逻辑和 README 完全相反它要的是操作指令不是项目介绍。1.2 Context 治理的本质是筛选信息不是压缩信息“Agent Context 治理”这个说法看起来高大上其实就是回答一个问题在有限的上下文窗口里什么东西值得被优先放进去很多人一听说上下文不够用第一反应是压缩——把所有信息搞成一段摘要让 AGENTS.md 尽量短。这是方向性错误。上下文治理的本质是筛选。你要决定的是哪 10% 的信息必须百分百出现在模型面前哪 90% 的信息该放在仓库其他位置等模型真正需要时再去读。AGENTS.md 该承载的是那些“你没说模型就一定会猜错”的关键信息而不是把项目的边边角角都塞进去。我拿 README 和 AGENTS.md 做过一个对比两者定位差异挺明显的维度READMEAGENTS.md读者人类开发者AI Agent核心目的让人理解项目、跑起来让 AI 遵守边界、按规则操作语气描述、解释命令、约束内容偏好功能特性、使用场景技术栈、目录边界、硬性规则维护节奏按版本迭代跟着每个翻车现场不断更新失效判定人看着别扭AI 开始做蠢事理解了这个差异你才会明白为什么 AGENTS.md 值得单独存在。它不是 README 的补充不是 .github 模板而是 AI 辅助开发时代项目里的独立基础设施。2. 真实项目里的混乱现场我们为什么开始治理2.1 项目背景一个逼着我们正视问题的模拟项目先说项目背景。我们小组维护一个数据可视化平台顺手起个代号“模拟项目X”技术栈大概是 Vue 3 TypeScript 做前端Python 负责数据处理接口再加几个跑定时任务的独立模块。代码量不算巨大但目录结构复杂内部还有一套自定义的数据接入规范。组里七个人都在重度使用 AI 编程助手日常写页面、改接口、修 bug 都会让 AI 代劳。最初的体验确实爽但随着项目越来越复杂AI 表现开始明显下滑。最让人崩溃的是同一个错误反复出现这周改了下周换个会话又给你犯一遍。我们当时以为问题是“AI 太笨”后来才慢慢发现问题出在我们自己身上——我们从没给 AI 提供一个稳定、高质量的项目认知起点。每次它都靠猜来起步那它每次跑偏的地方也都差不多。2.2 三个典型的翻车现场这里记录几个真实发生过的场景很多团队估计都有类似经历。第一个翻车现场AI 改错配置文件。平台有好几个环境配置入口真正生效的配置文件集中在deploy/config下而根目录也有一个.env.example只是一个模板。AI 收到“修改超时时间”的需求后没有看任何说明直接改了.env.example里的值然后信誓旦旦地告诉你已经完成。代码评审的时候才发现真正的配置一点没动。第二个翻车现场在错误的目录里实现功能。当时我们让 AI 在 service 层加一个数据导出的接口函数。正常来说这个函数应该放在src/services/export/下结果 AI 一通搜索后在src/utils/里新建了一个文件把导出逻辑写在“通用工具”里。功能倒是跑得通但代码归属完全混乱后续维护成本直线上升。第三个翻车现场忽略团队内部既有工具。项目里其实已经封装了一个内部时间处理函数专门处理数据平台的时间格式。AI 在实现时间范围筛选时却自己引入了date-fns没用内部封装。这个问题在代码评审里被拎出来的时候AI 还振振有词觉得自己引入标准库更合理。这三个场景都指向同一个本质当 AI 没有接收到项目特有的规则和边界信息时它会用自己的“平均先验”来补全。而项目恰恰是那个充满特有约定的地方平均先验必然翻车。2.3 把问题归类信息缺失、规则模糊、上下文膨胀复盘多了之后我们把问题归成了三类。第一类是信息缺失。AI 不知道项目的技术栈边界、不知道配置入口在哪、不知道内部工具已经存在。不是它能力不行是我们从来没给它讲清楚。第二类是规则模糊。很多团队约定只存在于口头交流、PR 评论或者某个群聊里。人可以靠社交记忆遵守这些约定AI 完全没有渠道知道。你不写进它肯定能看到的文件它就只能靠猜。第三类是上下文膨胀。长会话场景下对话轮次一多模型注意力会被各种无关信息稀释。它一开始可能还记得你的约束聊到后面就彻底忘了。我们后来发现AGENTS.md 能在一定程度缓解这个问题因为在长会话里它相当于一个随时可以回去“重新对齐”的基准点。这三类问题单独看都不致命合在一起就会让 AI 辅助开发的效率变得极不稳定。我们决定动手治理第一步就是从根目录放一个 AGENTS.md 开始。3. 从文档到基线AGENTS.md 的内容拆解与编写实操3.1 我们的第一版最小可用模型动手之前我们定了一个原则不求全求最小可用。第一版 AGENTS.md 被刻意控制在 80 行以内能少写就少写。以下是我们当时最终定稿的大纲现在看依然有参考价值# AGENTS.md ## 项目一句话 模拟项目X数据可视化平台负责指标接入、报表展示和定时导出。 ## 技术栈白名单 - 前端Vue 3 TypeScript Pinia - 后端Python FastAPI - 禁止引入未在 package.json / requirements.txt 中出现过的新库必须先讨论。 ## 目录地图 - src/services/所有业务接口实现新增接口函数必须放这里。 - src/utils/仅放与业务无关的通用纯函数禁止放业务逻辑。 - deploy/config/运行时配置真正读取的目录修改配置优先看这里。 - 根目录 .env.example只是模板修改它不会影响任何环境。 ## 常用命令 - 开发npm run dev - 测试npm run test - 格式检查npm run lint - 生成接口文档npm run gen:docs ## 硬性约束 - 时间处理必须使用 src/utils/datetime.ts 内的封装禁止直接引入第三方日期库。 - 所有外部数据接入必须走 src/services/ingestion/ 统一的入口。 - 定时任务必须通过调度器注册禁止在业务代码里自行创建循环线程。 - 新增配置项必须同步修改 deploy/config 下对应环境的默认值。 ## 常见陷阱 - 图表联动统一走 store 里的 chart 模块不要在各页面组件里各自拉取数据。 - 现有接口返回结构里 status 字段是字符串枚举不是数字避免类型误判。 - 导出文件名需要遵循既有命名规则report_YYYYMMDD_枚举.csv。 ## 工作流提示 - 修改代码前先找到对应目录确认修改范围。 - 涉及多个模块的改动先在 AGENTS.md 对应的章节里验证自己的理解。这一版虽然不完美但已经解决了 80% 的“AI 乱猜”问题。它把项目里最常见的认知盲区一次性摊开让 AI 第一次具备了相对准确的项目心智。3.2 每个板块为什么要存在很多团队写 AGENTS.md 时容易堆砌写出一堆 AI 根本用不上的废话。我们每个板块都经历了实际验证留下来的都有明确作用。技术栈白名单的作用是“防污染”。AI 模型训练数据里充满了各种技术方案你如果不声明边界它非常倾向于用自己最熟悉的方案而不是你这个项目实际使用的方案。在代码评审里看到模型私自引库基本都是没写白名单。目录地图的作用是“定边界”。AI 对文件路径的理解纯粹来自上下文里的线索。你不告诉它src/utils不能放业务逻辑它就真的会把业务代码写进去。这个板块是最直接的防呆设计建议用显式的“允许/禁止”句式不要用“建议”“应该”这类软性词。硬性约束板是全部规则里优先级最高的一档。我们故意和前面的目录地图分开因为有些规则跨越目录边界比如时间处理统一封装这件事它影响任何模块。当 AI 在多个任务之间切换时这栏内容就是那个“不管什么时候都不能破”的底线。常见陷阱板是效率利器。里面每一条都来自真实的翻车现场相当于我们提前把踩坑经验喂给 AI省得它每次都从头开始试错。后期迭代时这一栏增长得最快。实操心得如果你不确定某条规则该不该写进 AGENTS.md就问自己一句话如果我不写AI 会不会大概率做错会就写。不会就别写省点上下文空间。3.3 编写语言命令式、可验证、不留模糊地带这部分是最大的坑。一开始我们写“请保持代码清晰”“不要破坏既有结构”结果一点用都没有。原因也很简单这些说法根本没有可验证的边界AI 无法判断自己什么时候算“清晰”什么时候算“破坏”。后来我们摸索出一套写法核心就三个要点。第一用命令式语气直接给指令。“必须”“禁止”“唯一入口”这类词汇可以放开用它们不会冒犯 AI只会让规则更清晰。第二让规则能落地验证。比如我们不写“保持良好架构”而是写“新增业务接口函数必须放在 src/services 对应模块下”。AI 写代码时很容易检查自己有没有遵守这条规则约束力自然就强。第三不给模糊地带留空间。如果某个选择你们已经定了直接写死。之前我们在缓存方案上举棋不定AGENTS.md 里写了一堆“可以考虑用 XXX 或 YYY”结果 AI 每次选得都不一样还自以为做了技术选型。后来改成“缓存统一使用 Redis键规范为 projectX:模块:业务键”世界安静了。我们后来整理了一份正反例对照这里分享几个最典型的错误写法模糊正确写法可验证请保持项目整洁新增功能代码必须放到 src/services 对应模块禁止堆在 utils尽量使用现有组件UI 组件优先使用 src/components/ui 下的封装禁止在页面里直接引第三方组件库注意处理异常所有对外接口必须捕获异常并返回标准结构{code, message, data}性能要好列表页数据超过 500 条时必须走分页查询禁止一次性拉全量这套话术基本可以用到所有 AGENTS.md 里区别只是具体约束内容不同。4. 让 AGENTS.md 真正生效的四个迭代技巧4.1 让规则可被验证而不是可被感受第一部分提到了可验证原则这里展开讲一个具体做法给规则配备“检查动作”。每条规则最好都能对应到一次搜索、一次命令或一次代码定位AI 可以先执行检查动作再判断当前操作是否合规。举个例子。我们有一条规则是“所有数据接入必须走 ingestion 统一入口”为了让 AI 更容易验证我们补了一句“新增接入时先搜索register_ingestion确认入口函数签名”。这句话不是规则本身而是给 AI 一条自查路径它照着做就不容易出错。还有一条是“禁止手动创建循环线程执行定时任务”。为了让 AI 能验证我们写了“定时任务必须通过src/scheduler/中的注册函数添加修改前先查看scheduler/README.md”。AI 找到 README 后自然能看到正确用法。这就是我们后来总结的一个原则AGENTS.md 里的规则要让 AI 有办法“执行前自查”而不是只凭感觉干活。规则越具体AI 越不容易假装自己懂了。4.2 守住上下文预算AGENTS.md 本身不能太长AGENTS.md 存在的作用是管理上下文但它自己也在消费上下文。如果一份 AGENTS.md 写了两千行模型要么来不及读完要么读到一半就忘了前面反而制造新的信息干扰。我们给自己定了一个很朴素的预算AGENTS.md 主文件控制在 80 到 120 行之间。超过这个范围就会触发我们的“内容迁移流程”把某个板块细拆到独立文件里在主文件里只留一句“如需深入先读 docs/agents/xxx.md”。我们的预算分配经验大致是这样全局硬性约束25% 篇幅这部分最重要必须留在主文件。目录地图与边界20% 篇幅防止 AI 乱跑。常用命令与工作流15% 篇幅保证基本操作正确。常见陷阱与内部约定25% 篇幅提前避坑。其他说明与链接15% 篇幅作为补充索引。这个比例不是严格的但思路是对的把所有内容分成“必须在主文件”和“可以外链”两类别让主文件变成信息垃圾桶。上下文是一种稀缺资源你在 AGENTS.md 里多写一行废话AI 在处理真实任务时就多一分分心的可能。4.3 像维护代码一样维护 AGENTS.mdAGENTS.md 是活文档但它不能“活得太随意”。我们接手项目三个月后AGENTS.md 已经积累了不少过时内容最典型的是技术栈白名单里写着“暂不使用状态管理库”可项目早就引入了 Pinia。AI 基于过时信息干活效果比没有 AGENTS.md 还糟糕。从那以后我们把 AGENTS.md 纳入严格的版本管理。具体做法很简单所有修改都走 PR和普通代码一起评审。改动说明必须写明原因是哪个翻车场景推动了这次修改。废弃的规则直接删除不保留什么“历史说明”区块。旧版本信息留在 git 历史里就够了没必要在文档里继续占空间。这个习惯带来的额外好处是代码评审时大家会顺便看看 AGENTS.md 的变化团队共识因此不断被强化。以前约定只存在于某个人的脑子里现在所有规则都有一份明确的集体快照。4.4 用会话日志反推改写从哪里找规则素材AGENTS.md 最大的素材来源其实是你和 AI 的纠偏对话。每次你在对话里纠正 AI说“不对这里应该走 XXX”那都是一条潜在的 AGENTS.md 规则。我们后来养成了一个习惯周一早上花二十分钟把上一周 AI 会话里所有“纠偏”记录下来。不看技术细节只看重复出现的类型。如果某个纠正出现了三次以上它就不再是偶然问题而是系统缺陷必须写进 AGENTS.md。举例来说项目里的空值处理一度反复出问题。AI 经常默认字段一定有值导致统计数据异常。我们第一次发现后修了 bug第二次又犯第三次还在犯。有一次 PR 评审里有人扔了一句“空值处理必须先看 schema 默认值”这句话后来被我们原封不动地写进了 AGENTS.md 的常见陷阱区。从那以后这个问题基本绝迹。这个方法的关键是把“人的口头纠正”变成“机器的默认前提”。你的团队越依赖 AI越该建立这个反馈闭环。5. 常见问题与排查技巧实录5.1 常见问题速查表下面是我们团队在实践过程中整理的一份速查表适用于大多数已经引入 AI 辅助开发的项目问题现象可能原因排查思路与解决动作AI 完全不理会 AGENTS.md 里的规则工具版本不支持或文件位置不对确认工具文档支持哪个文件名大多数情况要求放在仓库根目录检查文件大小是否超过读取限制上下文窗口依然容易溢出会话里贴了太多代码全文把“贴代码”改成“引路径问题描述”并检查 AGENTS.md 是否塞入了可外链的冗余内容新旧规则冲突AI 行为飘忽规则增删没有清理旧描述打开 AGENTS.md 通读一遍删除所有互相矛盾的表述约定冲突时必须保留最新且最强约束AGENTS.md 写了不生效AI 自己另搞一套规则表述过于模糊把“应该”“尽量”改成“必须”“禁止”给每条规则配上检查动作AI 改 A 模块时受 B 模块规则干扰主文件上下文太杂拆分局部规则到子目录的 AGENTS.md主文件只留跨模块的全局约束多语言/多端项目规则相互打架目录归属混乱按模块拆分 docs/agents/并明确“改前端代码前只读前端相关章节”这张表不是一次性整理完的每一条背后都有过一次真实的痛苦经历。建议团队在落地 AGENTS.md 时把“问题台账”顺手维护起来比临时回忆靠谱得多。5.2 一次真实调试过程从翻车到规则落地拿我们前面提到过的图表联动问题来复盘一下。当时的任务是给平台某个报表页的图表增加联动筛选功能。合理范围是只改一个页面组件和对应 store 模块两三个文件就够。AI 第一次动手时直接跑去把所有 page 目录下的数据获取逻辑都改了一遍因为它“推测”联动应该全局生效。结果几个不相关的页面全被牵扯代码评审直接红了脸。我们第一反应是骂工具不行冷静下来后发现真正的问题是 AI 根本不知道“图表联动统一走 store 的 chart 模块”这个约定。这个约定此前只存在于一次会议讨论中没有任何文档记录。于是我们做了一次标准动作。第一步打开 AGENTS.md在“常见陷阱”区加了一条图表联动统一走 store 里的 chart 模块不要在页面组件里各自拉取数据。第二步在目录地图里标出src/store/chart.ts注明这是图表状态的唯一入口。第三步加了一个可验证提示接手图表相关任务时先搜索useChartStore确认当前状态管理方式。改完后我们做了同样的任务测试。AI 这次的改动范围收敛到了两个模块store 更新一个文件页面组件调整一个文件和我们预期完全一致。同类任务后续连续测试几次都没有再复发这个问题。这个案例给我的启发是很多“AI 能力不行”的结论其实都是“项目上下文缺失”的误判。5.3 排查时要有的心态AGENTS.md 的维护不是一次性能做完的它像一个规则搜索引擎需要持续收录新的边界和新陷阱。我们在排查过程中最大的切身体会就是别指望一次改到位特别是团队较大、AI 使用场景较杂时每两周固定做一次“规则体检”是合理频率。另外规则加多了之后评估机制也要跟上。我们后来每季度会做一次小测试随机挑三四个常见任务让 AI 从零开始做一遍观察它是否主动遵守 AGENTS.md 里的约束。这个测试成本很低但能帮你发现哪些规则已经被 AI 内化哪些规则只是躺在文件里当摆设。6. 更进一步分治、分工与 AGENTS.md 的边界6.1 用 docs/agents/ 做内容分治当项目规模变大单一 AGENTS.md 支撑不住所有信息时不需要硬撑。我们的做法是在仓库里建一个docs/agents/目录按模块拆分布局规则。根目录 AGENTS.md 只保留全局约定技术栈基线、跨模块硬性约束、全局命令和工作流提示。每个重点模块各放一个独立 AGENTS.md比如docs/agents/ frontend.md # 前端模块规则UI 组件边界 backend.md # 服务端规则接口规范 ingestion.md # 数据接入规则 deploy.md # 部署与配置规则根目录 AGENTS.md 负责“路由”写清楚类似这样的句子“当你需要修改前端页面时先读 docs/agents/frontend.md当你处理数据接入时先读 docs/agents/ingestion.md”。这样 AI 在打开会话时先建立全局框架等到具体任务时再按需加载对应子规则。这种分治的核心价值是让上下文更贴近任务本身。一个专门改前端页面的 AI 会话不需要知道部署模块的完整细节。信息越聚焦AI 的决策质量越高。实测下来同样的任务在分治前后回答的稳定性差距非常明显。6.2 和其他项目文档的分工协作很多人问 AGENTS.md 和 README、CONTRIBUTING 的关系。我们的分工原则是README 对外讲故事说明项目为什么存在、能解决什么问题CONTRIBUTING 面向人类贡献者说明提交流程和代码评审规范AGENTS.md 面向 AI说明操作边界和硬性约束。三者会有少量重叠但定位必须清晰。如果一份文档既想当 README 又想当 AGENTS.md往往两个角色都当不好。AI 会花大量上下文去理解项目历史和愿景却没记住最该遵守的边界规则。要特别注意AGENTS.md 不要写“历史上我们曾经……”也不要写“未来我们打算……”。它只关心一个问题此刻在这个仓库里AI 该怎么正确地工作。凡是不能直接指导当前操作的句子都属于多余内容。6.3 一个诚实的提醒AGENTS.md 不是银弹写了这么多实操我得诚实说一句AGENTS.md 不是银弹它有自己的边界。它解决的是“信息缺失”问题但解决不了“模型遵循能力不足”的问题。如果AI工具本身不读取这个文件或者模型对长文指令的理解能力有限AGENTS.md 写得再好也是白搭。好在我们用的主流 AI 编程工具基本都兼容这个约定而且会持续支持在这个生态里投入是值得的。另一个边界是规则过时会带歪 Agent甚至比没有规则更危险。我们踩过一次技术栈白名单里旧条目没清理AI 坚持使用一个我们早就废弃的库因为它认为“AGENTS.md 说的”就是权威。从那以后我们把 AGENTS.md 的定期清理看成和写代码一样重要的任务。总结下来AGENTS.md 的本质是把团队的隐性知识显性化再把它放到 AI 的视野内。这是一个持续投入、持续修正的过程不需要一次性做到完美但一定要开始做并且持续做下去。最后说一点我个人在实际操作里的感受。AGENTS.md 没有改变我们团队使用 AI 的方式但它改变了我们对“上下文”的理解。以前我担心的是会话太长、模型太笨现在我会换一个角度想问题如果明天这个会话从零开始它还能不能做出和今天一样的决定如果能说明项目上下文已经被治理好了如果不能那就把那条缺失的规则写进 AGENTS.md。每多写一条AI 就少一次自由发挥项目就多一分稳定。如果你读完也想试试建议只做一个小动作挑一个最常让 AI 出错的目录写五行动态规则放进去。你会发现同样的任务AI 的表现会有非常直接的改变。
