先交代一个经常被忽略的细节README.md 是给人类看的而 AGENTS.md 是给 AI 编程助手看的。过去几个月我在几个仓库里尝试给 AI 助手写“使用说明”发现最有效的做法并不是一开始就写一份宏大完整的规则文档而是从几行真正有用的约束起步让这份文件跟着仓库一起长。本文就围绕 AGENTS.md 的最小化起步思路讲讲它是什么、为什么要小、怎么写、什么时候扩展以及怎么避免常见的坑。1. 什么是 AGENTS.md给 AI 伙伴看的仓库说明书1.1 AGENTS.md 解决的是什么问题现在的 AI 编程助手不再只是帮你补全几行代码而是会读整个仓库、跨文件修改代码、执行构建和测试命令。它能理解“你这个仓库大概在做什么”但很难天然知道很多只有维护者才清楚的细节比如测试命令是pytest tests/还是python -m unittest。代码风格要求是什么新增文件要不要写类型注解。哪些目录不能乱动比如vendor/、generated/、dist/。项目有没有特殊约定比如错误码规范、日志格式、数据库迁移流程。如果这些信息只存在于你的脑子里AI 每次工作都是在猜。猜错一次不明显猜错十次就开始浪费大量时间。AGENTS.md 就是为了把这类“内部知识”写下来让 AI 在开始干活之前先读一遍。它本质上是一份“给 AI 的 README”。正如 README 帮助人类快速理解项目AGENTS.md 帮助 AI 快速理解这个仓库的工作方式和约束条件。1.2 为什么不能简单把 README 当作替代品有人会说项目已经有很好的 README为什么还要单独写 AGENTS.md原因在于两者目标不同。文档目标读者核心目标典型内容README.md人类开发者/用户快速上手、了解功能项目简介、安装方式、使用示例、截图AGENTS.mdAI 编程助手在仓库内安全高效地工作构建命令、代码风格、目录约束、常见陷阱README 更偏“对外”AGENTS.md 更偏“对内”。README 通常会讲解“这个项目有多棒、怎么跑起来”但不会告诉你“改完代码必须跑哪个测试目录”“不要在internal/里写任何新文件”。AI 需要的恰恰是后者。当然两者可以互相引用。AGENTS.md 里写一句“构建命令见 README.md 的开发环境部分”是完全合理的。1.3 为什么“最小化起步”反而是正确策略很多团队第一次听说 AGENTS.md 时容易走两个极端一端是完全不写继续让 AI 靠猜另一端是第一天就写出一份包含 200 条细则的巨型文档把团队约定、代码哲学、命名规范、历史包袱全塞进去。巨型文档的问题很明显维护成本高团队改一次规范就要同步改文件很难坚持。AI 上下文有限几百行规则会稀释真正重要的那几条约束。新成员读起来负担重。规则之间可能互相矛盾反而让 AI 行为变得不可预测。更好的方式是把 AGENTS.md 当作一个“会成长的文档”先写下当前最痛、最容易被违反、最影响工作结果的 3 到 5 条规则然后在实际使用过程中每次遇到 AI 犯的典型错误再把对应的规则补进去。就像养一株植物先种下再施肥而不是第一天就搭好一个塑料大棚。2. 环境准备与从零起步一个最小 AGENTS.md 应该长什么样很多 AI 编程工具目前对 AGENTS.md 的支持还处于快速演进阶段。不同工具读取这个文件的方式并不完全一致有的默认识别有的需要配置映射有的会在特定位置查找。因此本文不打算写死某个工具的具体配置而是聚焦最通用、最稳定的部分文件位置、命名、基础格式和编写思路。2.1 文件位置与命名AGENTS.md 最常见的放置位置是仓库根目录。这个位置好处很明显AI 助手在分析仓库结构时第一眼就能看到它。从命名稳定性来讲AGENTS.md这个全大写形式已经逐渐成为事实标准很多工具对它做了默认识别。但也有工具会找agents.md或AGENTS.txt。在没有统一标准之前建议根目录放一份AGENTS.md作为最通用、最稳妥的选择。如果某些子目录有特殊规则可以在子目录里再放一份局部规则例如src/platform/AGENTS.md。不要在仓库里同时维护多个不同大小写形式的同名文件比如AGENTS.md和agents.md同时存在这样会造成识别混乱。2.2 AGENTS.md 的基本语言与格式AGENTS.md 本质上是一个 Markdown 文件格式并不复杂。它不需要花哨的排版重要的是内容能被 AI 稳定解析。建议用清晰的标题、短句和列表避免大段散文。# AGENTS.md 本项目是一个基于 Python 的库存管理服务。 在开始工作之前请先阅读本文件。虽然这是一个非常简短的示例但它已经建立了两个重要的信号项目身份是什么以及“先读我”的优先指令。2.3 从这几条规则开始一个最小版本的 AGENTS.md不需要包含所有信息只需要覆盖下面四个维度的基础内容。维度需要回答的问题优先级项目身份这是什么项目技术栈是什么高常用命令构建、测试、运行分别用什么命令高目录结构哪些目录是关键目录哪些不要动高重要约束有哪些硬性要求或绝对不能做的事高这四条里命令和约束往往是 AI 最容易犯错的点。先写这个维度效果会最明显。下面给出一个真正可用的最小版本# AGENTS.md ## 项目概览 这是一个基于 Python 3.11 FastAPI 的图书管理 API 服务。 ## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reload ## 目录约束 - app/ 是业务代码目录新增接口放在 app/routers/ 下。 - tests/ 是测试目录修改代码时必须同步新增或调整对应测试。 - docs/ 只放文档不要在里面写业务代码。 ## 硬性约束 - 所有业务错误必须返回统一的 JSON 结构{code: 5001, message: xxx}。 - 不允许使用 print 调试统一使用 logging。 - 修改数据库模型后必须补齐对应的 Alembic 迁移文件。这个文件看起来不长但信息密度很高。AI 拿到它之后至少能避免三类典型错误跑错测试命令、在错误目录新增文件、忽略了错误返回格式。3. 逐段拆解一个最小 AGENTS.md 该怎么写很多人拿到一个模板就直接填结果写出来的文件不疼不痒。这里拆解一下上面的示例说明每一部分为什么重要、应该怎么写、不应该怎么写。3.1 项目概览让 AI 快速进入状态## 项目概览 这是一个基于 Python 3.11 FastAPI 的图书管理 API 服务。这句话回答的是“我在哪个世界工作”。AI 每次进入一个仓库如果上下文里没有项目身份描述它会根据文件名和代码结构去推断。推断通常能对但也会出现“把 TypeScript 项目当成 JavaScript 项目处理”这种低级错误。在项目概览里值得写的主要是项目语言和核心框架。项目是做什么的一句话即可。如果是微服务说明这个服务是哪个域的服务。不建议写项目历史、团队组织架构、已经废弃的旧架构。这些内容对 AI 完成当前任务没有帮助反而会占用有限的注意力。3.2 常用命令减少无意义的猜测## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reloadAI 在执行代码修改时经常需要运行测试来验证结果。如果不知道测试命令它会尝试各种命令比如python manage.py test、pytest、npm test最后可能还会问你要怎么跑。把最常用的几条命令写清楚能节省大量时间。需要注意的点命令要写得具体尽量带上参数。别只写“测试pytest”要写完整命令pytest tests/ -v。如果不同环境命令不同按环境分组说明。如果项目里有 Makefile直接写make test也可以。3.3 目录约束告诉 AI 哪里是安全区## 目录约束 - app/ 是业务代码目录新增接口放在 app/routers/ 下。 - tests/ 是测试目录修改代码时必须同步新增或调整对应测试。 - docs/ 只放文档不要在里面写业务代码。这段话实际上是一个“地图”。AI 在多文件操作时最怕的就是把代码放到错误的位置。比如它想在路由文件里加一个接口结果不知道路由文件在哪里就自己创建了一个新的app/routes.py导致项目结构越来越乱。目录约束不一定要把整个仓库都列一遍。只写关键目录和容易走错的目录。尤其要写清楚“哪些目录不要动”比如- 不要修改 vendor/ 目录下的任何文件。 - generated/ 目录内容是自动生成的不要手改。这样的负面约束比正面描述“应该做什么”更能防止事故。3.4 硬性约束把“绝对不能做”写清楚## 硬性约束 - 所有业务错误必须返回统一的 JSON 结构{code: 5001, message: xxx}。 - 不允许使用 print 调试统一使用 logging。 - 修改数据库模型后必须补齐对应的 Alembic 迁移文件。硬性约束是最有价值的部分也是最容易写偏的部分。很多人会把“代码风格偏好”写成硬性约束导致规则膨胀。正确的做法是只把违反后会导致返工或线上事故的规则放进来。比如“统一使用 logging 而不是 print”这个如果不写AI 很可能为了调试方便直接往代码里塞一堆print你还要花时间清理。“错误返回结构必须统一”如果不写AI 会按照自己见过的各种风格写可能这次返回{error: xxx}下次返回{code: xxx}。另外硬性约束的表述要尽量直接不要用太多修饰词。与其写“建议考虑使用环境变量来管理配置”不如写“配置必须通过 pydantic-settings 从环境变量加载禁止在代码中硬编码密钥”。4. 让 AGENTS.md 跟着仓库一起成长扩展路线图最小版本跑通之后难点就变成了“什么时候扩展”和“扩展什么”。这里给出一个比较务实的成长路线。4.1 触发扩展的信号不要按固定的时间周期去更新 AGENTS.md而是按“失败信号”去更新。当你发现 AI 在同一个类型的问题上犯错两次就应该考虑把对应的规则写进 AGENTS.md。常见的触发信号包括AI 用了错误的构建命令导致重复排查。AI 改了 A 模块的代码却没有更新 B 模块的对应逻辑。AI 新增了依赖却没有把依赖写进 requirements 或 pyproject.toml。AI 不理解项目的提交规范提交信息风格混乱。AI 在某个特殊目录里创建了文件而这个目录本应保持纯洁。每遇到一次这种问题就补一条规则。这样 AGENTS.md 的增长是“用教训换来的”而不是“拍脑袋写出来的”。4.2 第二阶段补充代码风格与提交规范当团队开始习惯 AGENTS.md 之后可以加入代码风格和提交规范。这一阶段适合写的内容有## 代码风格 - 所有函数必须包含类型注解。 - 新增模块必须包含模块级 docstring。 - 变量命名遵循 PEP 8类名使用 PascalCase。 - 单个函数控制在 50 行以内过长需要拆分。 ## 提交规范 - 提交信息使用 Conventional Commits 风格feat:, fix:, docs:, refactor:。 - 不要在一个提交里混合多个不相关的改动。注意代码风格条目不要贪多。挑三到五条最影响代码审阅效率的规则就够了。写得太多AI 反而会在小问题上反复纠缠耽误主任务。4.3 第三阶段补充架构说明与模块边界项目时间长一点后AI 最容易犯的错误是“跨模块乱改”。比如订单模块的 AI 任务顺手改了一个公共组件而它根本不知道这个组件被其他十几个模块依赖。因此在第三阶段建议加入模块边界说明## 架构与模块边界 - app/services/ 中的服务不允许直接依赖 app/api/ 中的请求/响应模型。 - app/models/ 只存放 ORM 模型不允许包含业务逻辑。 - 跨模块调用必须走 app/interfaces/ 中定义的接口不允许直接 import 其他模块的 service。这种信息能显著降低 AI 引入设计混乱的概率。但前提是仓库本身确实有清晰边界。如果项目本身已经是一团乱麻不建议在 AGENTS.md 里硬造一个“理想架构”因为 AI 照着写又会和现有代码不一致反而制造更多问题。4.4 第四阶段沉淀“已知陷阱”一个经历了长期演进的仓库一定有一批“踩坑记录”。这些知识散落在代码注释、团队成员聊天记录和 PR review 评论里。它们非常适合沉淀成 AGENTS.md 的“陷阱清单”。## 已知陷阱 - utils/cache.py 中的缓存默认不设置过期时间新增调用时必须显式指定 ttl。 - 不要直接调用 third_party/sms/send.py它已经废弃统一走 notifications/sender.py。 - 在 Windows 环境下scripts/build.sh 不会执行请使用 scripts/build.ps1。 - 修改 config.py 中的配置项后必须同步更新 .env.example。这些条目往往是用线上故障换来的经验价值非常高。它们没有固定的格式关键是要具体到“路径 行为 替代方案”让 AI 看到条目就能直接执行。4.5 一个成长后的 AGENTS.md 完整示例下面是一个经过几个阶段扩展后的示例你可以把它当作扩展的参考而不是直接套用的模板# AGENTS.md ## 项目概览 这是一个基于 Python 3.11 FastAPI 的库存管理服务提供商品、库存流水和预警能力。 ## 常用命令 - 安装依赖pip install -r requirements.txt -r requirements-dev.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reload - 数据库迁移alembic upgrade head ## 目录结构 - app/ 是业务代码目录路由放在 app/routers/业务逻辑放在 app/services/。 - app/models/ 只放 ORM 模型不允许写业务逻辑。 - app/schemas/ 放 Pydantic 请求响应的 Schema。 - tests/ 是测试目录修改代码必须同步调整测试。 - docs/ 只放文档。 - 不要修改 vendor/ 和 generated/ 目录。 ## 代码风格 - 所有函数必须包含类型注解。 - 使用 ruff 作为 lint 工具提交前必须通过 ruff check .。 - 异步接口使用 async def阻塞操作必须放到线程池。 ## 硬性约束 - 业务错误必须使用 app/core/errors.py 中定义的标准异常统一返回 {code: 5001, message: xxx}。 - 禁止硬编码密钥配置统一从环境变量获取通过 app/core/config.py 读取。 - 修改 ORM 模型后必须生成新的 Alembic 迁移文件。 - 新增第三方依赖必须给出理由并写入 requirements 文件。 ## 已知陷阱 - utils/cache.py 的缓存默认不设置过期时间新增调用时必须显式设置 ttl。 - 不要直接调用 legacy/notify.py请使用 app/services/notify.py。 - 商品库存扣减必须使用乐观锁禁止先查后改的普通更新。 - 所有对外接口的响应时间超过 1 秒必须打印 slow log。这个版本比最小版本长了很多但每一条都是实践教训的产物没有空话。它仍然是一个相对克制的文件。5. 常见问题与排查思路在实际使用 AGENTS.md 的过程中大家会遇到一些共性问题。这里整理成表格并针对几个典型问题做详细说明。问题现象常见原因排查与解决思路AI 助手没有读取 AGENTS.md工具不支持该文件名或文件位置不对确认工具文档看是否需要配置映射或调整文件命名规则写了但 AI 不遵守规则太长被其他指令覆盖精简规则数量把最重要的约束放到文件靠前位置AGENTS.md 和 .cursorrules 内容冲突多个配置文件并存AI 不知道优先级统一维护入口让其他配置文件引用 AGENTS.md文件更新不及时只写不改规则慢慢失效把 AGENTS.md 变更纳入代码 review 流程规则太抽象AI 理解有歧义使用了很多模糊形容词用具体路径、具体命令、具体示例替代抽象描述5.1 AI 完全没读取这个文件怎么办首先确认工具的版本以及它支持的文件命名。不同工具对 AGENTS.md 的支持程度不一样有的是原生识别有的是通过配置把 AGENTS.md 映射为 rules 文件有的需要放在.cursor/rules/之类的目录下。排查顺序确认文件名确实是AGENTS.md而不是Agent.md或agents.txt。确认文件在仓库根目录。查看工具文档中关于规则文件的说明。如果支持AGENTS.md但不能自动识别尝试把全局规则位置指向该文件。检查版本更新到最新版本后再测试。5.2 规则写了但 AI 违规这是最常见的问题。多数情况不是 AI“不听话”而是规则内容太宽泛或者被上下文中的其他信息覆盖了。比如你写了“代码质量要高”这种规则对 AI 来说没有操作意义。它不知道“高”具体指什么。好的写法是“新增函数必须包含类型注解必须编写对应的单元测试”这样 AI 就能照做。另外规则的顺序也很重要。AI 在读取大量内容时靠前的指令权重通常更高。把最重要的硬性约束放在文件前面能提高遵守率。还有一点如果某个工具的系统提示词本身就包含大量指令你的 AGENTS.md 只是其中一个信息源AI 不一定会严格遵循。这种情况下最好的办法是让 AGENTS.md 里的规则具体、可执行、可验证用事实性内容提高说服力。5.3 规则之间冲突怎么办一个大仓库里可能有多个规则来源比如团队内部开发规范、README、.cursorrules、CI 配置。这些来源如果各说各话AI 就会陷入矛盾。例如 README 里写“使用 npm 管理依赖”而 AGENTS.md 里写“使用 pnpm 安装依赖”。AI 读到之后可能一次用 npm一次用 pnpm。解决方式确定一个唯一权威来源让其他文件引用它。比如 AGENTS.md 作为 AI 规则的唯一入口里面写“依赖管理遵循docs/development.md中的说明”。这样即使其他地方有描述AI 也知道以哪个为准。6. 最佳实践与工程建议6.1 把 AGENTS.md 当成代码来维护AGENTS.md 不是写一次就永久有效的静态文档它应该像代码一样走 review、测试和迭代流程。在 PR 中新增 AGENTS.md 修改时应当在 PR 描述里说明为什么要加这条规则。团队定期比如每两周回顾一次 AGENTS.md删除已经失效的规则。把 AGENTS.md 纳入仓库的变更记录方便追溯哪条规则是什么时候加入的、为什么加入。6.2 控制规则的粒度一条规则好不好有一个简单的判断标准AI 读到这条规则后能不能不假思索地执行。如果不能说明还不够具体。反面示例请保证代码的可维护性。这个规则没有任何操作指导意义。正面示例新增公共函数时必须包含类型注解和 docstring并在tests/unit/下添加对应单测。这样 AI 知道要做什么、在哪里做、做到什么程度。不过也要小心过度具体。规则过于细致会让 AGENTS.md 变得像一本操作手册AI 可能每写几行代码就要检查一下规则反而拖慢速度。建议规则数量控制在 15 到 25 条之间覆盖项目概览、命令、目录约束、硬性约束和陷阱清单就足够。6.3 保持正面指令优先规则有两种写法一种是“不要这样”一种是“应该这样”。虽然负面约束有时更直接但长期维护时正面指令的效果通常更好。比如与其写不要在 service 层写 SQL。不如写所有数据库操作必须通过 repository 层完成。区别在于正面指令告诉 AI 正确的路径是什么而负面指令只是阻止它走一条路它可能又会试着走另一条错误的路。6.4 敏感信息不要进 AGENTS.mdAGENTS.md 和代码一样可能在团队内共享也可能被提交到公开仓库。因此绝对不要在里面写密钥、内部地址、未公开的接口细节等敏感信息。即使项目是私有仓库也应该养成“AGENTS.md 只写通用约定不写秘密”的习惯。这样以后做开源或者交接时会减少很多隐患。6.5 让 AGENTS.md 服务于人也服务于 AI我在实践中发现一个副产品AGENTS.md 写好了对人类新成员也很有帮助。因为它把“仓库里哪些地方是雷区、怎么跑测试、代码怎么组织”这些知识集中在一起新同学入职看一遍就能少踩很多坑。所以不要把它当成一个纯粹的“AI 配置文件”。它完全可以变成团队知识的沉淀载体。它的名字里虽然有 AGENTS但最终收益的其实是整个团队。6.6 定期验证规则有效性维护 AGENTS.md 最怕的是“写了但没人知道有没有用”。建议每过一段时间找一个对仓库不熟悉的同事或 AI 客户端让它根据 AGENTS.md 完成一个典型任务看它会不会犯错。如果它在已经覆盖的规则上仍然犯错说明规则的表达方式需要优化。这种验证方式成本低效果直观能让 AGENTS.md 一直保持“可用”而不是“存在”。7. 总结AGENTS.md 这个概念本身并不复杂它只是一份给 AI 助手看的项目说明书。真正值得思考的是它的维护方式。从实践来看最小化起步、随仓库成长是当前最稳妥也最有效的路径。刚起步时不需要追求完美找几条最影响 AI 工作质量的规则写下来让 AI 先“有规可依”。之后每遇到一个典型的失败信号就往里补一条具体的规则。文件会慢慢变长但每一条都有真实的场景和代价支撑不会变成空洞的套话。如果你还没有在仓库里引入 AGENTS.md建议现在就动手创建一个只有十条以下内容的最小版本用一次真实的 AI 任务去检验它。你会发现几行准确说明带来的效果远胜过一份没人维护的冗长文档。 AGENTS.md最小化起步：给AI编程助手的仓库说明书
先交代一个经常被忽略的细节README.md 是给人类看的而 AGENTS.md 是给 AI 编程助手看的。过去几个月我在几个仓库里尝试给 AI 助手写“使用说明”发现最有效的做法并不是一开始就写一份宏大完整的规则文档而是从几行真正有用的约束起步让这份文件跟着仓库一起长。本文就围绕 AGENTS.md 的最小化起步思路讲讲它是什么、为什么要小、怎么写、什么时候扩展以及怎么避免常见的坑。1. 什么是 AGENTS.md给 AI 伙伴看的仓库说明书1.1 AGENTS.md 解决的是什么问题现在的 AI 编程助手不再只是帮你补全几行代码而是会读整个仓库、跨文件修改代码、执行构建和测试命令。它能理解“你这个仓库大概在做什么”但很难天然知道很多只有维护者才清楚的细节比如测试命令是pytest tests/还是python -m unittest。代码风格要求是什么新增文件要不要写类型注解。哪些目录不能乱动比如vendor/、generated/、dist/。项目有没有特殊约定比如错误码规范、日志格式、数据库迁移流程。如果这些信息只存在于你的脑子里AI 每次工作都是在猜。猜错一次不明显猜错十次就开始浪费大量时间。AGENTS.md 就是为了把这类“内部知识”写下来让 AI 在开始干活之前先读一遍。它本质上是一份“给 AI 的 README”。正如 README 帮助人类快速理解项目AGENTS.md 帮助 AI 快速理解这个仓库的工作方式和约束条件。1.2 为什么不能简单把 README 当作替代品有人会说项目已经有很好的 README为什么还要单独写 AGENTS.md原因在于两者目标不同。文档目标读者核心目标典型内容README.md人类开发者/用户快速上手、了解功能项目简介、安装方式、使用示例、截图AGENTS.mdAI 编程助手在仓库内安全高效地工作构建命令、代码风格、目录约束、常见陷阱README 更偏“对外”AGENTS.md 更偏“对内”。README 通常会讲解“这个项目有多棒、怎么跑起来”但不会告诉你“改完代码必须跑哪个测试目录”“不要在internal/里写任何新文件”。AI 需要的恰恰是后者。当然两者可以互相引用。AGENTS.md 里写一句“构建命令见 README.md 的开发环境部分”是完全合理的。1.3 为什么“最小化起步”反而是正确策略很多团队第一次听说 AGENTS.md 时容易走两个极端一端是完全不写继续让 AI 靠猜另一端是第一天就写出一份包含 200 条细则的巨型文档把团队约定、代码哲学、命名规范、历史包袱全塞进去。巨型文档的问题很明显维护成本高团队改一次规范就要同步改文件很难坚持。AI 上下文有限几百行规则会稀释真正重要的那几条约束。新成员读起来负担重。规则之间可能互相矛盾反而让 AI 行为变得不可预测。更好的方式是把 AGENTS.md 当作一个“会成长的文档”先写下当前最痛、最容易被违反、最影响工作结果的 3 到 5 条规则然后在实际使用过程中每次遇到 AI 犯的典型错误再把对应的规则补进去。就像养一株植物先种下再施肥而不是第一天就搭好一个塑料大棚。2. 环境准备与从零起步一个最小 AGENTS.md 应该长什么样很多 AI 编程工具目前对 AGENTS.md 的支持还处于快速演进阶段。不同工具读取这个文件的方式并不完全一致有的默认识别有的需要配置映射有的会在特定位置查找。因此本文不打算写死某个工具的具体配置而是聚焦最通用、最稳定的部分文件位置、命名、基础格式和编写思路。2.1 文件位置与命名AGENTS.md 最常见的放置位置是仓库根目录。这个位置好处很明显AI 助手在分析仓库结构时第一眼就能看到它。从命名稳定性来讲AGENTS.md这个全大写形式已经逐渐成为事实标准很多工具对它做了默认识别。但也有工具会找agents.md或AGENTS.txt。在没有统一标准之前建议根目录放一份AGENTS.md作为最通用、最稳妥的选择。如果某些子目录有特殊规则可以在子目录里再放一份局部规则例如src/platform/AGENTS.md。不要在仓库里同时维护多个不同大小写形式的同名文件比如AGENTS.md和agents.md同时存在这样会造成识别混乱。2.2 AGENTS.md 的基本语言与格式AGENTS.md 本质上是一个 Markdown 文件格式并不复杂。它不需要花哨的排版重要的是内容能被 AI 稳定解析。建议用清晰的标题、短句和列表避免大段散文。# AGENTS.md 本项目是一个基于 Python 的库存管理服务。 在开始工作之前请先阅读本文件。虽然这是一个非常简短的示例但它已经建立了两个重要的信号项目身份是什么以及“先读我”的优先指令。2.3 从这几条规则开始一个最小版本的 AGENTS.md不需要包含所有信息只需要覆盖下面四个维度的基础内容。维度需要回答的问题优先级项目身份这是什么项目技术栈是什么高常用命令构建、测试、运行分别用什么命令高目录结构哪些目录是关键目录哪些不要动高重要约束有哪些硬性要求或绝对不能做的事高这四条里命令和约束往往是 AI 最容易犯错的点。先写这个维度效果会最明显。下面给出一个真正可用的最小版本# AGENTS.md ## 项目概览 这是一个基于 Python 3.11 FastAPI 的图书管理 API 服务。 ## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reload ## 目录约束 - app/ 是业务代码目录新增接口放在 app/routers/ 下。 - tests/ 是测试目录修改代码时必须同步新增或调整对应测试。 - docs/ 只放文档不要在里面写业务代码。 ## 硬性约束 - 所有业务错误必须返回统一的 JSON 结构{code: 5001, message: xxx}。 - 不允许使用 print 调试统一使用 logging。 - 修改数据库模型后必须补齐对应的 Alembic 迁移文件。这个文件看起来不长但信息密度很高。AI 拿到它之后至少能避免三类典型错误跑错测试命令、在错误目录新增文件、忽略了错误返回格式。3. 逐段拆解一个最小 AGENTS.md 该怎么写很多人拿到一个模板就直接填结果写出来的文件不疼不痒。这里拆解一下上面的示例说明每一部分为什么重要、应该怎么写、不应该怎么写。3.1 项目概览让 AI 快速进入状态## 项目概览 这是一个基于 Python 3.11 FastAPI 的图书管理 API 服务。这句话回答的是“我在哪个世界工作”。AI 每次进入一个仓库如果上下文里没有项目身份描述它会根据文件名和代码结构去推断。推断通常能对但也会出现“把 TypeScript 项目当成 JavaScript 项目处理”这种低级错误。在项目概览里值得写的主要是项目语言和核心框架。项目是做什么的一句话即可。如果是微服务说明这个服务是哪个域的服务。不建议写项目历史、团队组织架构、已经废弃的旧架构。这些内容对 AI 完成当前任务没有帮助反而会占用有限的注意力。3.2 常用命令减少无意义的猜测## 常用命令 - 安装依赖pip install -r requirements.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reloadAI 在执行代码修改时经常需要运行测试来验证结果。如果不知道测试命令它会尝试各种命令比如python manage.py test、pytest、npm test最后可能还会问你要怎么跑。把最常用的几条命令写清楚能节省大量时间。需要注意的点命令要写得具体尽量带上参数。别只写“测试pytest”要写完整命令pytest tests/ -v。如果不同环境命令不同按环境分组说明。如果项目里有 Makefile直接写make test也可以。3.3 目录约束告诉 AI 哪里是安全区## 目录约束 - app/ 是业务代码目录新增接口放在 app/routers/ 下。 - tests/ 是测试目录修改代码时必须同步新增或调整对应测试。 - docs/ 只放文档不要在里面写业务代码。这段话实际上是一个“地图”。AI 在多文件操作时最怕的就是把代码放到错误的位置。比如它想在路由文件里加一个接口结果不知道路由文件在哪里就自己创建了一个新的app/routes.py导致项目结构越来越乱。目录约束不一定要把整个仓库都列一遍。只写关键目录和容易走错的目录。尤其要写清楚“哪些目录不要动”比如- 不要修改 vendor/ 目录下的任何文件。 - generated/ 目录内容是自动生成的不要手改。这样的负面约束比正面描述“应该做什么”更能防止事故。3.4 硬性约束把“绝对不能做”写清楚## 硬性约束 - 所有业务错误必须返回统一的 JSON 结构{code: 5001, message: xxx}。 - 不允许使用 print 调试统一使用 logging。 - 修改数据库模型后必须补齐对应的 Alembic 迁移文件。硬性约束是最有价值的部分也是最容易写偏的部分。很多人会把“代码风格偏好”写成硬性约束导致规则膨胀。正确的做法是只把违反后会导致返工或线上事故的规则放进来。比如“统一使用 logging 而不是 print”这个如果不写AI 很可能为了调试方便直接往代码里塞一堆print你还要花时间清理。“错误返回结构必须统一”如果不写AI 会按照自己见过的各种风格写可能这次返回{error: xxx}下次返回{code: xxx}。另外硬性约束的表述要尽量直接不要用太多修饰词。与其写“建议考虑使用环境变量来管理配置”不如写“配置必须通过 pydantic-settings 从环境变量加载禁止在代码中硬编码密钥”。4. 让 AGENTS.md 跟着仓库一起成长扩展路线图最小版本跑通之后难点就变成了“什么时候扩展”和“扩展什么”。这里给出一个比较务实的成长路线。4.1 触发扩展的信号不要按固定的时间周期去更新 AGENTS.md而是按“失败信号”去更新。当你发现 AI 在同一个类型的问题上犯错两次就应该考虑把对应的规则写进 AGENTS.md。常见的触发信号包括AI 用了错误的构建命令导致重复排查。AI 改了 A 模块的代码却没有更新 B 模块的对应逻辑。AI 新增了依赖却没有把依赖写进 requirements 或 pyproject.toml。AI 不理解项目的提交规范提交信息风格混乱。AI 在某个特殊目录里创建了文件而这个目录本应保持纯洁。每遇到一次这种问题就补一条规则。这样 AGENTS.md 的增长是“用教训换来的”而不是“拍脑袋写出来的”。4.2 第二阶段补充代码风格与提交规范当团队开始习惯 AGENTS.md 之后可以加入代码风格和提交规范。这一阶段适合写的内容有## 代码风格 - 所有函数必须包含类型注解。 - 新增模块必须包含模块级 docstring。 - 变量命名遵循 PEP 8类名使用 PascalCase。 - 单个函数控制在 50 行以内过长需要拆分。 ## 提交规范 - 提交信息使用 Conventional Commits 风格feat:, fix:, docs:, refactor:。 - 不要在一个提交里混合多个不相关的改动。注意代码风格条目不要贪多。挑三到五条最影响代码审阅效率的规则就够了。写得太多AI 反而会在小问题上反复纠缠耽误主任务。4.3 第三阶段补充架构说明与模块边界项目时间长一点后AI 最容易犯的错误是“跨模块乱改”。比如订单模块的 AI 任务顺手改了一个公共组件而它根本不知道这个组件被其他十几个模块依赖。因此在第三阶段建议加入模块边界说明## 架构与模块边界 - app/services/ 中的服务不允许直接依赖 app/api/ 中的请求/响应模型。 - app/models/ 只存放 ORM 模型不允许包含业务逻辑。 - 跨模块调用必须走 app/interfaces/ 中定义的接口不允许直接 import 其他模块的 service。这种信息能显著降低 AI 引入设计混乱的概率。但前提是仓库本身确实有清晰边界。如果项目本身已经是一团乱麻不建议在 AGENTS.md 里硬造一个“理想架构”因为 AI 照着写又会和现有代码不一致反而制造更多问题。4.4 第四阶段沉淀“已知陷阱”一个经历了长期演进的仓库一定有一批“踩坑记录”。这些知识散落在代码注释、团队成员聊天记录和 PR review 评论里。它们非常适合沉淀成 AGENTS.md 的“陷阱清单”。## 已知陷阱 - utils/cache.py 中的缓存默认不设置过期时间新增调用时必须显式指定 ttl。 - 不要直接调用 third_party/sms/send.py它已经废弃统一走 notifications/sender.py。 - 在 Windows 环境下scripts/build.sh 不会执行请使用 scripts/build.ps1。 - 修改 config.py 中的配置项后必须同步更新 .env.example。这些条目往往是用线上故障换来的经验价值非常高。它们没有固定的格式关键是要具体到“路径 行为 替代方案”让 AI 看到条目就能直接执行。4.5 一个成长后的 AGENTS.md 完整示例下面是一个经过几个阶段扩展后的示例你可以把它当作扩展的参考而不是直接套用的模板# AGENTS.md ## 项目概览 这是一个基于 Python 3.11 FastAPI 的库存管理服务提供商品、库存流水和预警能力。 ## 常用命令 - 安装依赖pip install -r requirements.txt -r requirements-dev.txt - 运行测试pytest tests/ -v - 启动服务uvicorn app.main:app --reload - 数据库迁移alembic upgrade head ## 目录结构 - app/ 是业务代码目录路由放在 app/routers/业务逻辑放在 app/services/。 - app/models/ 只放 ORM 模型不允许写业务逻辑。 - app/schemas/ 放 Pydantic 请求响应的 Schema。 - tests/ 是测试目录修改代码必须同步调整测试。 - docs/ 只放文档。 - 不要修改 vendor/ 和 generated/ 目录。 ## 代码风格 - 所有函数必须包含类型注解。 - 使用 ruff 作为 lint 工具提交前必须通过 ruff check .。 - 异步接口使用 async def阻塞操作必须放到线程池。 ## 硬性约束 - 业务错误必须使用 app/core/errors.py 中定义的标准异常统一返回 {code: 5001, message: xxx}。 - 禁止硬编码密钥配置统一从环境变量获取通过 app/core/config.py 读取。 - 修改 ORM 模型后必须生成新的 Alembic 迁移文件。 - 新增第三方依赖必须给出理由并写入 requirements 文件。 ## 已知陷阱 - utils/cache.py 的缓存默认不设置过期时间新增调用时必须显式设置 ttl。 - 不要直接调用 legacy/notify.py请使用 app/services/notify.py。 - 商品库存扣减必须使用乐观锁禁止先查后改的普通更新。 - 所有对外接口的响应时间超过 1 秒必须打印 slow log。这个版本比最小版本长了很多但每一条都是实践教训的产物没有空话。它仍然是一个相对克制的文件。5. 常见问题与排查思路在实际使用 AGENTS.md 的过程中大家会遇到一些共性问题。这里整理成表格并针对几个典型问题做详细说明。问题现象常见原因排查与解决思路AI 助手没有读取 AGENTS.md工具不支持该文件名或文件位置不对确认工具文档看是否需要配置映射或调整文件命名规则写了但 AI 不遵守规则太长被其他指令覆盖精简规则数量把最重要的约束放到文件靠前位置AGENTS.md 和 .cursorrules 内容冲突多个配置文件并存AI 不知道优先级统一维护入口让其他配置文件引用 AGENTS.md文件更新不及时只写不改规则慢慢失效把 AGENTS.md 变更纳入代码 review 流程规则太抽象AI 理解有歧义使用了很多模糊形容词用具体路径、具体命令、具体示例替代抽象描述5.1 AI 完全没读取这个文件怎么办首先确认工具的版本以及它支持的文件命名。不同工具对 AGENTS.md 的支持程度不一样有的是原生识别有的是通过配置把 AGENTS.md 映射为 rules 文件有的需要放在.cursor/rules/之类的目录下。排查顺序确认文件名确实是AGENTS.md而不是Agent.md或agents.txt。确认文件在仓库根目录。查看工具文档中关于规则文件的说明。如果支持AGENTS.md但不能自动识别尝试把全局规则位置指向该文件。检查版本更新到最新版本后再测试。5.2 规则写了但 AI 违规这是最常见的问题。多数情况不是 AI“不听话”而是规则内容太宽泛或者被上下文中的其他信息覆盖了。比如你写了“代码质量要高”这种规则对 AI 来说没有操作意义。它不知道“高”具体指什么。好的写法是“新增函数必须包含类型注解必须编写对应的单元测试”这样 AI 就能照做。另外规则的顺序也很重要。AI 在读取大量内容时靠前的指令权重通常更高。把最重要的硬性约束放在文件前面能提高遵守率。还有一点如果某个工具的系统提示词本身就包含大量指令你的 AGENTS.md 只是其中一个信息源AI 不一定会严格遵循。这种情况下最好的办法是让 AGENTS.md 里的规则具体、可执行、可验证用事实性内容提高说服力。5.3 规则之间冲突怎么办一个大仓库里可能有多个规则来源比如团队内部开发规范、README、.cursorrules、CI 配置。这些来源如果各说各话AI 就会陷入矛盾。例如 README 里写“使用 npm 管理依赖”而 AGENTS.md 里写“使用 pnpm 安装依赖”。AI 读到之后可能一次用 npm一次用 pnpm。解决方式确定一个唯一权威来源让其他文件引用它。比如 AGENTS.md 作为 AI 规则的唯一入口里面写“依赖管理遵循docs/development.md中的说明”。这样即使其他地方有描述AI 也知道以哪个为准。6. 最佳实践与工程建议6.1 把 AGENTS.md 当成代码来维护AGENTS.md 不是写一次就永久有效的静态文档它应该像代码一样走 review、测试和迭代流程。在 PR 中新增 AGENTS.md 修改时应当在 PR 描述里说明为什么要加这条规则。团队定期比如每两周回顾一次 AGENTS.md删除已经失效的规则。把 AGENTS.md 纳入仓库的变更记录方便追溯哪条规则是什么时候加入的、为什么加入。6.2 控制规则的粒度一条规则好不好有一个简单的判断标准AI 读到这条规则后能不能不假思索地执行。如果不能说明还不够具体。反面示例请保证代码的可维护性。这个规则没有任何操作指导意义。正面示例新增公共函数时必须包含类型注解和 docstring并在tests/unit/下添加对应单测。这样 AI 知道要做什么、在哪里做、做到什么程度。不过也要小心过度具体。规则过于细致会让 AGENTS.md 变得像一本操作手册AI 可能每写几行代码就要检查一下规则反而拖慢速度。建议规则数量控制在 15 到 25 条之间覆盖项目概览、命令、目录约束、硬性约束和陷阱清单就足够。6.3 保持正面指令优先规则有两种写法一种是“不要这样”一种是“应该这样”。虽然负面约束有时更直接但长期维护时正面指令的效果通常更好。比如与其写不要在 service 层写 SQL。不如写所有数据库操作必须通过 repository 层完成。区别在于正面指令告诉 AI 正确的路径是什么而负面指令只是阻止它走一条路它可能又会试着走另一条错误的路。6.4 敏感信息不要进 AGENTS.mdAGENTS.md 和代码一样可能在团队内共享也可能被提交到公开仓库。因此绝对不要在里面写密钥、内部地址、未公开的接口细节等敏感信息。即使项目是私有仓库也应该养成“AGENTS.md 只写通用约定不写秘密”的习惯。这样以后做开源或者交接时会减少很多隐患。6.5 让 AGENTS.md 服务于人也服务于 AI我在实践中发现一个副产品AGENTS.md 写好了对人类新成员也很有帮助。因为它把“仓库里哪些地方是雷区、怎么跑测试、代码怎么组织”这些知识集中在一起新同学入职看一遍就能少踩很多坑。所以不要把它当成一个纯粹的“AI 配置文件”。它完全可以变成团队知识的沉淀载体。它的名字里虽然有 AGENTS但最终收益的其实是整个团队。6.6 定期验证规则有效性维护 AGENTS.md 最怕的是“写了但没人知道有没有用”。建议每过一段时间找一个对仓库不熟悉的同事或 AI 客户端让它根据 AGENTS.md 完成一个典型任务看它会不会犯错。如果它在已经覆盖的规则上仍然犯错说明规则的表达方式需要优化。这种验证方式成本低效果直观能让 AGENTS.md 一直保持“可用”而不是“存在”。7. 总结AGENTS.md 这个概念本身并不复杂它只是一份给 AI 助手看的项目说明书。真正值得思考的是它的维护方式。从实践来看最小化起步、随仓库成长是当前最稳妥也最有效的路径。刚起步时不需要追求完美找几条最影响 AI 工作质量的规则写下来让 AI 先“有规可依”。之后每遇到一个典型的失败信号就往里补一条具体的规则。文件会慢慢变长但每一条都有真实的场景和代价支撑不会变成空洞的套话。如果你还没有在仓库里引入 AGENTS.md建议现在就动手创建一个只有十条以下内容的最小版本用一次真实的 AI 任务去检验它。你会发现几行准确说明带来的效果远胜过一份没人维护的冗长文档。