1. 先搞清楚AGENTS.md 到底解决了什么问题1.1 从一场失控的“AI结对编程”说起前阵子我在维护一个内部的数据处理项目代码量不算大三万行出头模块边界也算清晰。但团队里接入了 AI 编程助手之后原本还算稳的代码库开始变得“陌生”了——新提交的代码里频繁出现风格不一致的函数命名某个本该沉淀在存储层的逻辑被直接写进了接口层更头疼的是AI 每次开工都要花大量时间四处翻文件才能找到入口文件有时甚至翻错了版本。一开始我以为是模型能力的问题换了好几个工具效果有改善但没根治。直到有一天我发现 AI 在一次会话里连续打开了十几个文件只为了确认一个配置项应该放在哪个目录——那一刻我意识到问题不在模型在于我压根没告诉它“这个项目长什么样、该怎么干活”。这就是我今天想聊的AGENTS.md 不是普通文档它是给 AI 协作工具体系里那位看不见的同事看的“入职手册”。所谓 AGENTS.md简单来说就是一份放在仓库根目录里、专门写给 AI 编程代理Agent看的说明文件。它告诉 Agent 项目的代码结构、技术栈、命令约定、变更规范避免它在每次对话里靠“猜”来理解你的项目。我在这类文件上的投入让 AI 生成的代码被直接采纳的比例从大概三成提到了七成左右这件事值得展开讲讲。1.2 Agent 上下文失控的三类典型症状先说症状方便你对号入座。如果你也在用 AI 编程工具且遇到下面这三种情况大概率不是模型问题而是项目上下文治理没做好。第一类是“地图迷失”。AI 不知道代码在哪问你“定时任务的入口在哪里”它先打开main.py找再翻utils/最后跑去tests/里碰运气。小项目还好几千个文件的工程里这种行为会浪费大量 token而且经常答非所问。第二类是“风格漂移”。团队约定变量用 snake_casePromise 链式调用优先错误必须先包装再抛出但 AI 每次生成的代码都在“猜”这些约定。这次对了下次又错了代码评审时满屏都是格式类修改真正该看的逻辑反而被淹没。第三类是“破坏性操作”。AI 在改一个模块时不小心动到了公共依赖或者在重构时遗漏了配套的测试更新。它其实没有恶意只是不知道“哪些文件是核心资产”“哪些操作需要额外小心”。你怪它也没用因为没人告诉过它。这三类症状有一个共同的根因Agent 的上下文里缺少结构化、可执行的项目规则。它手里只有代码库和对话历史而代码库本身不会说话。AGENTS.md 就是用来补上这张嘴的。1.3 为什么 README 顶不住它是给人看的不是给 Agent 用的有人会说我们仓库里有 README写得挺详细的还不够吗我的回答是README 是给人看的说明书AGENTS.md 是给 Agent 用的操作手册两者目标不同表达方式也不同。README 的读者是“路过的开发者”它要回答的是“这个项目是干什么的、怎么跑起来”。所以它会有大段的背景介绍、功能截图、架构图甚至团队文化。这些内容对 Agent 来说是噪音——它一目十行地扫过去很难从中提取出“修改src/services/report_service.py时必须同步更新tests/unit/test_report_service.py”这样精确的操作指令。更关键的是Agent 不擅长从长篇散文里做“信息检索”它更擅长按照清单和规则来执行。一份好的 AGENTS.md 应该像机场的地面标识线清晰、简短、直接指向动作。比如## Commands - Build: pnpm build - Test: pnpm test:unit - Lint: pnpm lint:es这种格式 README 里很少见但 Agent 读起来效率极高。它不需要理解“为什么用 pnpm”只需要知道“要跑测试就执行这一条”。2. 真实项目里的 AGENTS.md 设计思路2.1 项目背景与治理目标我先交代一下当时那个项目的实际情况方便你理解后面的设计决策。项目代号我暂且叫它“某数据清洗与报表服务”是一个典型的内部业务系统技术栈为 Python FastAPI 做后端接口Vue 3 TypeScript 做前端控制台PostgreSQL 存数据Redis 做缓存。仓库结构大概是backend/、frontend/、shared/、docs/、scripts/五个一级目录其中backend下又按业务模块拆了十几个子包。当时团队一共六个人三位写后端两位写前端我兼着做架构和 Code Review。AI 编程助手接入后最大的痛点不是“它不会写”而是“它写出来的东西不像是我们团队写的”。比如后端的异常处理我们约定所有业务异常必须继承自定义的BizError由全局异常处理器统一兜底但 AI 经常自作主张抛ValueError理由也许是对的但风格和现有代码完全不在一个频道上。所以这个 AGENTS.md 的治理目标非常明确不是教 AI“怎么写代码”那是模型的事而是告诉它“在这个仓库里按什么规则写代码才算合格”。具体拆成四层目标让 AI 在动手前能快速定位相关代码减少无效翻找让 AI 生成的代码符合团队约定减少评审时的风格纠偏让 AI 知道哪些操作是危险的避免它动到不该动的东西让 AI 在任何一次会话里都能快速恢复上下文而不是从头开始摸索带着这四个目标我开始搭 AGENTS.md 的骨架。2.2 我最终定下的目录骨架初版 AGENTS.md 我写了两千多字塞满了各种“应该怎么做”结果 AI 反而不听话了——上下文一长它像是在读论文抓不住重点。后来我参照一些成熟的开源项目做法把内容压缩重组最终形成了五段结构每段一个小标题# Project Overview # Repository Map # Development Workflow # Code Style Guide # Danger Zones这个骨架不是拍脑袋定的它对应 Agent 干活时需要依次回答的五个问题这是什么项目代码在哪里怎么构建和测试写出来的代码该长什么样有哪些事绝对不能碰关键是每个部分都要精简概览部分只写项目定位和核心技术栈不超过十行代码地图部分按目录逐个说明职责每行一条工作流部分是命令清单直接复制可用风格指南挑团队最在意的十条约不搞大而全危险区列出会导致线上事故或代码腐化的操作用“禁止”句式。2.3 每条规则背后的“为什么”这里我想特别强调一个容易被忽略的点AGENTS.md 里的每一条规则都应该有对应的“踩坑经历”在里面哪怕文件里不写原因你心里得清楚为什么要有这条。比如我在“禁止直接修改数据库迁移脚本”这条规则背后是因为我们真出过一次事故——某次 AI 在修复数据字段类型时直接把已经应用过的迁移文件改掉了导致同事拉代码后迁移校验失败整整排查了半天。所以这一类规则本质上不是审美偏好而是用真金白银换来的教训。另一条“新增公共依赖必须先在讨论区确认”背后是依赖冲突引发的连环问题。规则不需要解释来龙去脉但每条规则都得有它的分量AI 才会在决策时真正把这条当作硬约束而不是可选的风格建议。我通常的做法是写规则的同时在文件外的团队 Wiki 里记录具体事故案例AGENTS.md 只保留规则本身避免文件过长稀释注意力。3. 逐段解析一份可复用的 AGENTS.md 实例3.1 文件头部角色声明与上下文总览很多人写 AGENTS.md 一上来就铺目录结构我建议先加一小段角色声明告诉 Agent “你是谁、你在哪、你要干什么”。这段看着虚实际很有用——它相当于给 Agent 一个心理锚点避免它在处理具体任务时把自己当成普通聊天机器人。我当时的写法大致是# Project Overview You are working in the Data Cleaning Reporting Service repository. This is an internal data platform for transforming raw data into business reports. The primary language is Python 3.11 (backend) and TypeScript 5.2 (frontend). Follow the repository conventions below unless a task explicitly requires otherwise. If you are uncertain about a repository-wide change, ask before acting.这段信息量不大但它做了三件事亮明项目身份、确认技术栈基线、设定“不确定就先问”的行为基调。后两点对 AI 后续行为的影响非常直接。我对比过同一模型在有无这段声明时的表现有声明时 AI 更倾向于在动手前总结自己对任务的理解而不是直接开写。概览部分还有一个容易被忽略的细节写明项目的“非目标”。比如我们这个服务明确不做实时数据流处理这就避免了 AI 在某些任务里引入 Kafka 或者 Flink 这类完全不对路的方案。3.2 代码导航告诉 Agent 地图怎么画代码地图是这个文件里我最看重的部分。它的作用等同于给 Agent 一张标注了建筑物用途的城市地图——哪里是商场、哪里是地铁站、哪里是禁行区一眼就能看懂。我的写法是按一级目录逐条列出职责并顺手标注最常见的操作入口# Repository Map - backend/app/api/ — REST API 路由层。每个业务模块一个子目录 路由函数只做参数解析与响应封装业务逻辑一律下沉到 service 层。 - backend/app/service/ — 业务逻辑层。事务边界在这里控制 禁止在 route 层直接写数据库查询。 - backend/app/models/ — SQLAlchemy ORM 模型。新增字段时必须配套 编写 Alembic 迁移脚本不直接改动已发布的迁移历史。 - backend/app/common/ — 跨模块工具函数与通用组件。 包含统一异常类、分页组件、鉴权依赖等。修改此目录前先确认影响面。 - frontend/src/api/ — 后端接口封装层。所有 HTTP 请求统一走 该目录下生成的 client 模块不在组件里裸写 fetch。 - frontend/src/views/ — 页面级组件。路由对应的顶层页面 原则上只做组合与状态编排业务计算放入 composables/。 - shared/ — 前后端共享的 TypeScript 类型定义与常量表。 修改时注意两端同步发布。 - scripts/ — 本地开发脚本。数据库种子、代码生成器等 已在 package.json / Makefile 中暴露命令优先复用现有入口。这一段看起来只是目录说明但每个目录后面的那句“注释”才是真正的价值所在。Agent 读完之后至少能达成三个效果第一拿到需求后能直接定位应该动哪个目录第二知道跨层调用的“红线”在哪里不会再把 SQL 写在路由里第三修改公共目录时会多一分谨慎。如果你用的是支持“文件引用语法”的 AI 编程工具还可以在代码地图里直接写相对路径引用让它能点击跳转。不过可读性是第一位别为了炫技把文件撑得太长。3.3 命令与验证把“怎么做”写死这一段的思路很简单Agent 不需要猜怎么跑测试、怎么跑 lint直接把命令列出来它照着执行就行。但有一点要提醒命令部分不能只列“完美路径”还要告诉 Agent 遇到失败时怎么排查。我当时写的是# Development Workflow ## Backend (conda active env: py311) - Run dev server: uvicorn app.main:app --reload - Run unit tests: pytest tests/unit -x -q - Run integration tests: pytest tests/integration -x -q - Run linter: ruff check app tests - Run formatter: ruff format --check app tests ## Frontend - Install deps: pnpm install - Run dev server: pnpm dev - Run unit tests: vitest run --reporterverbose - Run linter: eslint src --ext .ts,.vue - Type-check: vue-tsc --noEmit在命令后面我补了一段“自动化验证”说明核心思想是任何改动在提交前必须让 Agent 自己能跑通的检查都跑一遍。这句话太重要了。我见过很多 AI 生成的代码逻辑看着合理结果一跑测试就挂——因为 AI 写代码时根本不跑测试它只是在“生成文本”。你在 AGENTS.md 里写清命令和验证要求实际上是在把 AI 的行为从“写代码”纠正为“开发代码”这是质的区别。有一个实操细节命令部分要写绝对命令别用“用包管理器安装依赖”这种模糊表述。AI 如果觉得项目用 npm 而实际上用了 pnpm后面所有操作都会错位。把命令写死就省了它猜的环节。3.4 变更流程约束 Agent 的“手”如果说前面几段是在教 Agent“怎么做对”那这段就是在教它“怎么避免做错”。我管它叫“变更流程约束”但实际内容更像一个分支条件和触发器清单。我的写法是用条件判断句式# Danger Zones - If you are about to modify files under backend/app/models/, you MUST create a matching Alembic migration script. - If you change a public function signature in shared/, you MUST update all call sites in both backend/ and frontend/. - If you add a new third-party dependency, you MUST NOT commit it directly. Add it to the proposal in the repo report file instead. - If you are going to delete or rename an existing API endpoint, you MUST check the frontend callers first and update them together. - You MUST NOT edit migration files under backend/alembic/versions/ after they have been merged to the main branch.有条件句式的规则对 Agent 特别有效因为它在生成代码时本质上是在做“下一个 token 的概率预测”条件句给了它清晰的触发器。相比之下像“注意保持代码整洁”这种模糊指令根本进不了它的决策层。另外我建议在变更流程里加一条针对“大改动”的兜底规则如果改动预计影响超过五个文件或者涉及数据库表结构变更先输出一份改动计划和影响清单再开始动代码。这条让 AI 从“闷头写代码”变成“先想后写”对多人协作的代码库来说非常救命。4. 实操中的坑与排查实录4.1 问题一上下文过长Agent 反而变笨刚开始我踩过一个大坑AGENTS.md 越写越长总觉得规则加得越多越安全。结果第一版上线之后AI 的表现反而变差了——它开始频繁“忘记”后面的规则或者在前面几条上过分纠结整体行为非常刻板。后来我想明白了Agent 的上下文窗口是有限的文件越长每条规则分到的“注意力权重”就越低。这就好比给新同事发了一本三百页的员工手册他不可能每条都记住反而会抓不住重点。解决办法是分层AGENTS.md 只留最核心的、影响“代码能否被接受”的规则大概二三十条更细的规范放到子目录的局部说明文件里比如backend/AGENTS.md只讲后端相关的约定frontend/AGENTS.md只讲前端约定。这样根目录文件瘦身到八百字左右AI 处理时轻快很多而且局部规则更容易命中。4.2 问题二规则定义模糊AI 理解偏离还有一次我在风格指南里写了“错误处理要统一”结果 AI 生成的代码里全是对try...except的滥用——它把普通的返回值校验也包成了异常处理看着规范实则画蛇添足。问题出在“统一”这个词它含义太泛了。AI 没有我们团队那种“约定俗成”的语境只有字面理解。后来我把这条改成了带正反例的说明- Error handling: business errors MUST be raised as BizError with a stable error code. Do NOT catch Exception at the route layer unless you are adding observability. Do NOT use assert for runtime business validation.改完之后效果立竿见影AI 生成的错误处理代码基本能直接用。这让我意识到一个原则写规则时不要用形容词要用动词和反例。每一条规则都应该是“可判定的”既让 AI 能执行也让人类评审时有据可依。4.3 问题三文档与代码脱节规则失效AGENTS.md 最大的风险不是写不好而是写完之后没人维护。代码库天天在变三个月后新增了workers/目录但 AGENTS.md 里的代码地图还是旧的AI 就会基于错误地图做决策比没有地图还糟糕。我在实践里定了一个硬规矩凡是 PR 里新增了一级目录或迁移了关键模块必须同步更新 AGENTS.md。这事一开始要靠人肉提醒后来我在代码审查清单里加了一条“Change Log Check”让检查项变成流程的一部分坚持几周就变成了团队肌肉记忆。另外我还会定期做一次“文档体检”随便挑一个重构类任务给 AI 设定成“只读模式”——只让它依据 AGENTS.md 输出改动方案不看实际代码。如果方案里出现了明显偏离实际结构的内容说明文档该更新了。4.4 附我常用的审查清单这里分享我每次给 AGENTS.md 做迭代时的自检清单你可以直接抄走检查项说明是否有项目概览一句话说明项目是做什么的技术栈是什么代码地图是否准确每个一级目录的职责描述和实际代码一致命令是否可直接复制构建、测试、lint 命令是否能在全新环境跑通风格规则是否可判定每条规则是否具体到能判断对错而非模糊的“要优雅”危险操作是否列出是否覆盖迁移脚本、公共接口、依赖变更、端到端破坏性改动是否设置了“不确定时先问”AI 在重大改动前有确认机制而不是闷头执行文件长度是否克制根目录文件尽量保持在一屏到两屏内细节下沉到子目录文档这七项我每次都会过一遍基本能做到“文档不拖后腿”。我个人在实际操作中的体会是AGENTS.md 这种文件本质上是在人和 AI 之间建立一份“可执行的默契”。它不需要多华丽也不需要覆盖所有边界但它必须精确、真话、有优先级。当这份默契建立起来之后AI 从“会写代码的实习生”变成“懂规矩的协作者”那种体验非常微妙——你不再需要逐行盯它的输出只需要在它给出方案时做决策就够了。这大概是 Agent Context 治理最迷人的地方不只是省 token、提效率而是让人和工具之间的协作边界变得更清晰、更舒适。