AGENTS.md 真的有用吗最近圈子里的项目越建越多很多人开始在自己的代码仓库里放一个AGENTS.md文件。我最早看到这个文件的时候其实没太当回事心想这不就是给 AI 看的一份说明文档吗直到后来我负责的一个 agent 项目反复出现低级错误——明明代码规范写得很清楚AI 却总是视而不见同一个项目换个 AI 工具来改效果差得离谱。我才意识到问题不在 AI 本身而在于我们根本没把这些工具真正带进门。这篇文章就来聊聊 AGENTS.md 这个看似不起眼的 Markdown 文件它到底是不是真的有用什么时候有用怎么用才能发挥出效果。我会结合自己做 agent 开发、折腾过多个 agent 框架的实操经验把它拆开揉碎讲清楚。如果你正在用 Cursor、Copilot、Claude Code 这类 AI 辅助编码工具或者在做 agent 项目、想把团队的历史经验沉淀给 AI那这篇内容大概率能帮你少走不少弯路。1. AGENTS.md 到底是个什么来头1.1 从 README 到 AGENTS 的演进逻辑每个有点规模的项目都有 README它是给人类看的项目是什么、怎么安装、怎么跑起来。但 AGENTS.md 的出现本质上是把文档的目标读者从人扩展到了 AI。我把它理解成一个给 AI 同事的入职手册。你招了一个新工程师不会直接甩给他代码库就让他改需求你会先让他看架构文档、了解代码规范、搞清楚构建命令、知道哪些目录是核心逻辑。AGENTS.md 做的事情完全一样只不过这个新工程师是 AI agent。我见过不少团队已经进化到这种程度仓库里有 README、CONTRIBUTING、ARCHITECTURE还有一堆 ADR架构决策记录。但 AI 工具并不会主动去翻这些它们默认只会看当前打开的文件、跑一下命令行反馈。你会发现让 AI 改代码时它经常在一个很小的上下文窗口里盲猜猜错了就乱改一通。AGENTS.md 就是给 AI 指路的那个总入口。1.2 AGENTS.md 与普通文档的本质区别最核心的区别在于普通文档是给人查阅的AGENTS.md 是给 AI 加载的。你在里面放什么AI 在多大程度上能记住并执行取决于几个非常实际的机制在 Cursor 这类编辑器里AGENTS.md 经常会被当作项目级指令自动加载相当于每次都带着一份潜意识在干活。在 Claude Code 里你可以通过AGENTS.md这样的方式显式引用也可以配置为自动读取类似 system prompt 的一部分。在 agent 框架里比如 LangChain、CrewAI 这类AGENTS.md 可以被读入作为 agent 的 system prompt 补充源让 agent 在规划任务时就能参考到这些约束。换句话说AGENTS.md 的意义关键在于它处在最高优先级的上下文中。它不像一个藏在 docs 目录里可能永远没被 AI 注意到的 markdown 文件而是能直接注入到 AI 每次决策前的那段系统指令里。理解了这一点你才会明白为什么有人靠一份几百行的 markdown 就能让 AI 的产出质量大幅提升。2. 它到底解决了什么痛点实操里的观察2.1 让 AI 从蒙眼写码变成带地图干活我先讲三个自己项目里真实踩过的场景场景一我在做一个 Python 的 agent 项目结构是 src/ 和 tests/ 分离的测试命令是pytest tests/ -q但 AI 每次都会自作主张跑python -m unittest。报错了它也不看项目里的 pytest.ini而是去改代码。你翻聊天记录会发现它每次都在猜测试框架是什么。后来我在 AGENTS.md 里写清楚本项目使用 pytest不要改测试配置命令是 xxx那一刻 AI 突然就开窍了。场景二项目里有明确的模块依赖方向core层不允许 importadapter层的任何东西。AI 改代码时经常无视这个方向直接把 adapter 的类 import 到 core 里。我试过在 review 时反复纠正但每次新对话它又忘了。最后把这条约束写进 AGENTS.md 后至少能拦住八成的情况。场景三一个人多眼杂的团队项目大家用的 AI 工具不一样有人用 Cursor有人用 Copilot还有人直接调 API 跑 agent。同一个需求不同工具生成出来的代码风格千奇百怪。后来我们统一在仓库里放 AGENTS.md里面写了代码风格、命名规范、提交信息格式、单测要求。一周之后所有 AI 生成内容的风格明显收敛了。这三个场景其实说明同一件事AI 工具的性能再强它默认的世界观是通用代码库。你的项目有自己的规矩、约束、潜规则如果不显式告诉它它就只能靠猜而猜的结果就是频繁的小错误、无效的尝试、以及你花时间去 review 和纠正。2.2 收益不完全在写代码上也在上下文省钱上作为一个经常跟 API 打交道的人我其实还特别在意一件事token 开销。如果你把各种规范分散在几十个文档里那 AI 遇到问题的时候它要么看不到要么反复去翻、去读每次读取都在消耗上下文窗口。而 AGENTS.md 的存在相当于把最关键的、每次都要遵守的规则压缩到了一个文件里只在一个固定位置加载。上下文窗口是有限的你把重要的规则放在显眼的位置AI 反而有更大机会在关键时刻用上。我有个很直观的对比同一个稍微复杂一点的重构任务不加 AGENTS.md 的时候AI 经常理解错需求来回改三轮才稳定加了之后第一版就能贴合项目的约束顶多再微调一下。这不仅仅是体验变好了算上耗时和 token其实是省钱省力。3. 一份高质量 AGENTS.md 应该怎么写3.1 结构拆解五个核心模块很多人的 AGENTS.md 写不好是因为把它当成 README 的简单翻版。我根据自己反复迭代的经验建议按下面五个模块来组织内容模块一项目速览。用三到五句话说明这个项目是干什么的、核心业务逻辑是什么、属于哪一类系统。这个模块的目的是让 AI 在动手之前先有个全局心智模型。模块二技术栈与目录结构。明确列出语言、框架、包管理器、目录划分、核心模块的功能。最好配一个简短的树形目录图AI 对路径的感知比对文字描述要强得多。模块三关键命令。包括安装依赖、启动服务、运行测试、代码检查、构建产物这些命令。注意一定要给完整命令不要写运行测试这样模糊的话AI 需要知道的具体命令是pytest tests/ -q -m not integration这种级别的精确信息。模块四代码约定与约束。这是 AGENTS.md 里最值钱的部分。写清楚命名规范、模块依赖规则、错误处理风格、禁止使用的反模式、必须遵守的安全红线。模块五工作流说明。比如提交 PR 前要跑什么检查、新功能是否需要写测试、AI 生成代码后是否需要人工复核、格式化工具的配置文件在哪。这些流程性信息很容易被忽略但对 AI 协作至关重要。3.2 一份可以直接改用的模板我把自己正在用的模板删去项目具体信息后放在下面。这个模板不是说唯一正确但你可以直接套用再根据自己项目的特性来增删# AGENTS.md ## 项目速览 - 项目定位一句话说清楚这个系统做什么。 - 核心概念列出 3~6 个领域关键词并各用一句话解释。 - 目标用户这个系统服务谁关注什么指标 ## 技术栈与目录结构 - 主语言Python 3.11 - 框架FastAPI, SQLAlchemy 2.x, Pydantic v2 - 包管理uv - 关键目录 - app/core领域模型与业务规则禁止依赖外部服务 - app/adapters数据库、消息队列、第三方 API 适配层 - app/apiHTTP 接口层只做参数接收与响应组装 - tests/unit单元测试不访问网络 - tests/integration集成测试需要本地依赖服务 ## 关键命令 - 安装依赖uv sync - 启动服务uvicorn app.main:app --reload --port 8000 - 运行全部测试pytest tests/ -q - 运行单元测试pytest tests/unit -q - 代码检查ruff check . mypy app - 格式化ruff format . ## 代码约定 - 命名函数使用 snake_case类用 PascalCase常量用 UPPER_SNAKE_CASE。 - 错误处理业务异常必须使用 app/core/exceptions.py 中自定义异常禁止裸抛 RuntimeError。 - 日志统一使用 structlog禁止 print 调试输出除非是 CLI 工具。 - 数据库禁止在 app/api 层直接执行 SQL一律走 repository 层。 - 测试新增业务逻辑必须伴有单元测试测试文件命名 test_module.py。 ## 工作流说明 - 开发步骤理解需求 - 定位影响模块 - 查看现有实现 - 修改 - 补测试 - 本地运行相关测试。 - 完成定义所有涉及模块的单元测试通过ruff 无警告mypy 无类型错误。 - 注意无论何时都不要修改 app/core 模块的对外接口除非需求本身要求破坏性变更。这个模板看起来很简单但它的好用之处在于信息密度高、路径明确、禁止项写得清清楚楚。AGENTS.md 真正的价值不在于字数多而在于它能精准约束 AI 行为。我见过有人写到几千行结果 AI 反而抓不住重点因为上下文里塞满了废话。3.3 老项目改造如何把历史经验沉淀进去很多人问我新项目好写 AGENTS.md那存量老项目怎么办我自己的做法是分三步第一步翻历史 commit 和 code review 记录。找那些反复出现过的问题比如别用全局变量改状态不要在 util 里塞太多函数连接数据库必须用连接池这些就是最有价值的第一手素材。第二步跑一遍项目的完整流程。从拉代码到启动、测试、构建把每一步实际用到的命令记录下来。你会发现 README 里的命令很多早就过时了正好借这个机会更新。第三步找项目里最有经验的人访谈。让他说出在日常开发中最烦的三件事、最容易被新手弄坏的地方、最不希望 AI 乱动的模块在哪。这些信息写进 AGENTS.md比任何空泛的规范都管用。我在给一个老项目补 AGENTS.md 的时候就是靠这三步一个小时不到就把核心约束摸清了。后来团队里有人让 AI 改代码明显感觉 AI 的分寸感好很多不该碰的地方基本不碰了。4. 实践中踩过的坑与排查实录4.1 为什么我的 AGENTS.md 失灵了实话实说AGENTS.md 不是放进去就万事大吉。我自己至少踩过这几个坑写出来给大家做参考。坑一位置不对。有人把 AGENTS.md 放在 docs/ 子目录下或者在子项目里放了一堆同名文件。大部分 AI 工具在查找上下文文件时默认找的是仓库根目录下的 AGENTS.md。你藏在三四个层级之下工具根本不会主动加载。我一开始就吃过这个亏写了满满一份结果 AI 一次都没读到后来把它挪到根目录才生效。坑二内容太软。AGENTS.md 里写了一大堆应当尽量保证代码质量注意模块间解耦这种话。AI 看到这种建议性的语句执行权重是很低的。它会当成参考意见而不是硬性规则。你必须把它写成不可协商的命令式语句禁止从 adapter 导入到 core所有对外接口必须写 docstring。坑三上下文冲突。有次我既在 AGENTS.md 里写了使用 pytest又在某个子模块的 README 里写了使用 unittestAI 在决策时出现了上下文冲突最后它选了 README 里的内容。这提醒我AGENTS.md 的有效性取决于它和其他文档的一致性。你必须在整个仓库范围内消除矛盾否则 AI 会无所适从。坑四没有负面约束。很多人写 AGENTS.md 只写应该做什么不写绝对不要做什么。但据我观察AI 犯错往往不是因为不知道该干什么而是因为不知道有什么禁区。它在重构的时候胆子很大敢动那些不该动的接口就是因为没人明确说过这个东西不能碰。现在我的 AGENTS.md 里专门有一块是禁止清单效果立竿见影。坑五没有版本管理意识。AGENTS.md 也是要演进的。项目经历了大规模重构、换了框架、改了目录结构但 AGENTS.md 还停留在半年前的状态那它反而会误导 AI。我踩过一次重构后核心目录从lib/改成了src/AGENTS.md 没同步AI 每次都在老路径上打转。后来我把 AGENTS.md 的更新写进了重构的完成清单里才算根治。4.2 常见问题速查表问题现象可能原因解决方法AI 完全无视 AGENTS.md文件不在项目根目录编辑器未开启读取项目指令选项移到根目录检查 Cursor / Copilot 的项目级指令配置AI 只是读了但没执行内容太软建议性语气太多指令和代码库现状冲突改成命令式表达消除文档冲突在子目录中上下文丢失工具只在根目录加载 AGENTS.md子目录的请求没有带入在子目录放精简版 AGENTS.md只写该目录相关约束修改多轮后 AI 逐渐遗忘规则上下文窗口被长对话占满早期指令被挤出明确要求 AI 在每次修改前快速回顾 AGENTS.md 关键约束或拆分任务为多个短对话生成的代码风格仍然不一致AGENTS.md 里没有具体格式化命令和工具配置写明命令行ruff format .、prettier --write .等新旧规范冲突AI 行为随机多个文档规则矛盾统一收敛到 AGENTS.md废弃过时文档或加注已由 AGENTS.md 取代我特别想强调最后一行文档的一致性太重要了。AI 不像人有常识它面对互相矛盾的信息时经常随机挑选一个来执行。你写完 AGENTS.md 之后可以试着在仓库里搜一遍不要应该注意这类词看有没有旧文档里的建议跟 AGENTS.md 冲突。这种行为叫指令审计每次做完AI 的表现都会上一个台阶。5. 对 AI 的驯化边界与更宏观的工作流设计5.1 不要指望一份 Markdown 解决所有问题AGENTS.md 能提升 AI 的下限但它不是银弹。遇到几个方向性的问题一份文件解决不了它依然挡不住 AI 在业务逻辑层面的根本性误解。AGENTS.md 能告诉 AI 应该遵守什么规则但很难传达这个产品为什么这样设计。如果需求本身描述不清AI 可能在规则之内做出一版完全错误的实现。它也无法替代代码评审。AI 读得再认真也只是在尽量模仿人类的判断力。像性能瓶颈、可维护性、长期演进这类需要全局视角的问题目前还是要靠人来兜底。我遇到过一种更隐蔽的情况AGENTS.md 写得越详细AI 就越守规矩但同时也变得小心翼翼。有次我问它能不能做一个有创意的方案重构它全程在纠结我写的那条禁止修改公共接口的规则最后给出的方案非常保守。这说明AGENTS.md 里的规则如果写得太死反而会压制 AI 在合理范围内的灵活性。所以我现在会把规则分成两档硬性约束红线和软性偏好建议让 AI 在守住红线的前提下保留判断空间。5.2 AGENTS.md 在 agent 项目中的扩展玩法前面聊的多是人用 AI 辅助编码的场景但 AGENTS.md 在 agent 项目里的角色还可以更重。我在做一个自动化 agent 的时候发现可以直接把 AGENTS.md 的内容当 system prompt 的补充源来用我在 app/agents/ 目录下放了一个专门的 AGENTS.md里面写清楚了这个 agent 的职责边界、能调用哪些工具、遇到什么情况必须停止并向用户确认、哪些回复必须遵循的格式。然后在代码里启动 agent 时直接把文件内容读入 contextwith open(agents/intent_router/AGENTS.md, encodingutf-8) as f: system_prompt_supplement f.read() agent create_agent( system_promptSYSTEM_PROMPT_TEMPLATE \n\n---\n system_prompt_supplement, tools[...], )这样做的好处是改 agent 行为不用改代码直接改 Markdown 就行。团队里不会写代码的产品同学也能参与调教 agent 的行为。这个模式我用下来非常顺手甚至比在代码里去维护一堆 if-else 分支清晰得多。更进一步我观察到社区里有的项目开始用AGENTS.md配合context.md做分级上下文。根目录的 AGENTS.md 放全项目全局约束子模块的 AGENTS.md 放局部细节。AI 工具在深入某个子模块时可以同时加载全局文件和局部文件既不会丢失全局视野也能获得局部精度。这种分层上下文的思想本质上和我们在写代码时做模块化是一样的我后面打算把团队里所有 agent 项目都改成这种结构。6. 最后的建议如果你现在打算开始用6.1 从最小可行版本开始别一上来就求全我一直觉得AGENTS.md 最忌讳的是一步到位。你第一次写只要覆盖四件事就够了项目一句话定位。怎么跑测试这一条能直接带来收益。代码命名和格式化命令。三条你最在意、AI 最容易违反的硬性约束。写这么多就够了。花二十分钟放到仓库里跑一天试试效果。你会很快发现哪些内容真正被 AI 用到了哪些内容它根本无视然后再迭代。很多人上来就写上千行结果大部分内容是 AI 用不上的空话反而掩盖了真正重要的规则。6.2 用提问测试法验证你的 AGENTS.md 有没有用最后分享一个我每次写完 AGENTS.md 都会做的验证方法姑且叫提问测试法新建一个空对话不提供任何额外提示直接问 AI 三个问题这个项目是干什么的怎么运行单元测试修改代码时最重要的三条约束是什么看 AI 能不能准确回答。如果它说错了说明你的 AGENTS.md 没有被正确加载或者写得不清晰。如果它能准确说出来说明后续的自动改代码大概率会遵守这些约束。这个测试我每次做完都会有新发现有一次发现 AI 把另一个项目的技术栈都算到这个项目头上了排查半天发现是它在缓存里读取了旧项目的 index。我自己用 AGENTS.md 已经有小半年了最大的感受是它不是玄学也不是银弹就是在 AI 时代给项目补上的一份使用说明书。和所有工程实践一样它的价值取决于你怎么写、怎么维护、怎么和实际的工作流结合。你不一定要紧跟这套做法但如果团队里 AI 辅助编码经常出现低水平重复错误那我建议你别急着换更强的模型先试试把约束写进 AGENTS.md 里。很多时候换模型不如换上下文。
AGENTS.md 实战指南：让 AI 编码不再“蒙眼”的关键配置
AGENTS.md 真的有用吗最近圈子里的项目越建越多很多人开始在自己的代码仓库里放一个AGENTS.md文件。我最早看到这个文件的时候其实没太当回事心想这不就是给 AI 看的一份说明文档吗直到后来我负责的一个 agent 项目反复出现低级错误——明明代码规范写得很清楚AI 却总是视而不见同一个项目换个 AI 工具来改效果差得离谱。我才意识到问题不在 AI 本身而在于我们根本没把这些工具真正带进门。这篇文章就来聊聊 AGENTS.md 这个看似不起眼的 Markdown 文件它到底是不是真的有用什么时候有用怎么用才能发挥出效果。我会结合自己做 agent 开发、折腾过多个 agent 框架的实操经验把它拆开揉碎讲清楚。如果你正在用 Cursor、Copilot、Claude Code 这类 AI 辅助编码工具或者在做 agent 项目、想把团队的历史经验沉淀给 AI那这篇内容大概率能帮你少走不少弯路。1. AGENTS.md 到底是个什么来头1.1 从 README 到 AGENTS 的演进逻辑每个有点规模的项目都有 README它是给人类看的项目是什么、怎么安装、怎么跑起来。但 AGENTS.md 的出现本质上是把文档的目标读者从人扩展到了 AI。我把它理解成一个给 AI 同事的入职手册。你招了一个新工程师不会直接甩给他代码库就让他改需求你会先让他看架构文档、了解代码规范、搞清楚构建命令、知道哪些目录是核心逻辑。AGENTS.md 做的事情完全一样只不过这个新工程师是 AI agent。我见过不少团队已经进化到这种程度仓库里有 README、CONTRIBUTING、ARCHITECTURE还有一堆 ADR架构决策记录。但 AI 工具并不会主动去翻这些它们默认只会看当前打开的文件、跑一下命令行反馈。你会发现让 AI 改代码时它经常在一个很小的上下文窗口里盲猜猜错了就乱改一通。AGENTS.md 就是给 AI 指路的那个总入口。1.2 AGENTS.md 与普通文档的本质区别最核心的区别在于普通文档是给人查阅的AGENTS.md 是给 AI 加载的。你在里面放什么AI 在多大程度上能记住并执行取决于几个非常实际的机制在 Cursor 这类编辑器里AGENTS.md 经常会被当作项目级指令自动加载相当于每次都带着一份潜意识在干活。在 Claude Code 里你可以通过AGENTS.md这样的方式显式引用也可以配置为自动读取类似 system prompt 的一部分。在 agent 框架里比如 LangChain、CrewAI 这类AGENTS.md 可以被读入作为 agent 的 system prompt 补充源让 agent 在规划任务时就能参考到这些约束。换句话说AGENTS.md 的意义关键在于它处在最高优先级的上下文中。它不像一个藏在 docs 目录里可能永远没被 AI 注意到的 markdown 文件而是能直接注入到 AI 每次决策前的那段系统指令里。理解了这一点你才会明白为什么有人靠一份几百行的 markdown 就能让 AI 的产出质量大幅提升。2. 它到底解决了什么痛点实操里的观察2.1 让 AI 从蒙眼写码变成带地图干活我先讲三个自己项目里真实踩过的场景场景一我在做一个 Python 的 agent 项目结构是 src/ 和 tests/ 分离的测试命令是pytest tests/ -q但 AI 每次都会自作主张跑python -m unittest。报错了它也不看项目里的 pytest.ini而是去改代码。你翻聊天记录会发现它每次都在猜测试框架是什么。后来我在 AGENTS.md 里写清楚本项目使用 pytest不要改测试配置命令是 xxx那一刻 AI 突然就开窍了。场景二项目里有明确的模块依赖方向core层不允许 importadapter层的任何东西。AI 改代码时经常无视这个方向直接把 adapter 的类 import 到 core 里。我试过在 review 时反复纠正但每次新对话它又忘了。最后把这条约束写进 AGENTS.md 后至少能拦住八成的情况。场景三一个人多眼杂的团队项目大家用的 AI 工具不一样有人用 Cursor有人用 Copilot还有人直接调 API 跑 agent。同一个需求不同工具生成出来的代码风格千奇百怪。后来我们统一在仓库里放 AGENTS.md里面写了代码风格、命名规范、提交信息格式、单测要求。一周之后所有 AI 生成内容的风格明显收敛了。这三个场景其实说明同一件事AI 工具的性能再强它默认的世界观是通用代码库。你的项目有自己的规矩、约束、潜规则如果不显式告诉它它就只能靠猜而猜的结果就是频繁的小错误、无效的尝试、以及你花时间去 review 和纠正。2.2 收益不完全在写代码上也在上下文省钱上作为一个经常跟 API 打交道的人我其实还特别在意一件事token 开销。如果你把各种规范分散在几十个文档里那 AI 遇到问题的时候它要么看不到要么反复去翻、去读每次读取都在消耗上下文窗口。而 AGENTS.md 的存在相当于把最关键的、每次都要遵守的规则压缩到了一个文件里只在一个固定位置加载。上下文窗口是有限的你把重要的规则放在显眼的位置AI 反而有更大机会在关键时刻用上。我有个很直观的对比同一个稍微复杂一点的重构任务不加 AGENTS.md 的时候AI 经常理解错需求来回改三轮才稳定加了之后第一版就能贴合项目的约束顶多再微调一下。这不仅仅是体验变好了算上耗时和 token其实是省钱省力。3. 一份高质量 AGENTS.md 应该怎么写3.1 结构拆解五个核心模块很多人的 AGENTS.md 写不好是因为把它当成 README 的简单翻版。我根据自己反复迭代的经验建议按下面五个模块来组织内容模块一项目速览。用三到五句话说明这个项目是干什么的、核心业务逻辑是什么、属于哪一类系统。这个模块的目的是让 AI 在动手之前先有个全局心智模型。模块二技术栈与目录结构。明确列出语言、框架、包管理器、目录划分、核心模块的功能。最好配一个简短的树形目录图AI 对路径的感知比对文字描述要强得多。模块三关键命令。包括安装依赖、启动服务、运行测试、代码检查、构建产物这些命令。注意一定要给完整命令不要写运行测试这样模糊的话AI 需要知道的具体命令是pytest tests/ -q -m not integration这种级别的精确信息。模块四代码约定与约束。这是 AGENTS.md 里最值钱的部分。写清楚命名规范、模块依赖规则、错误处理风格、禁止使用的反模式、必须遵守的安全红线。模块五工作流说明。比如提交 PR 前要跑什么检查、新功能是否需要写测试、AI 生成代码后是否需要人工复核、格式化工具的配置文件在哪。这些流程性信息很容易被忽略但对 AI 协作至关重要。3.2 一份可以直接改用的模板我把自己正在用的模板删去项目具体信息后放在下面。这个模板不是说唯一正确但你可以直接套用再根据自己项目的特性来增删# AGENTS.md ## 项目速览 - 项目定位一句话说清楚这个系统做什么。 - 核心概念列出 3~6 个领域关键词并各用一句话解释。 - 目标用户这个系统服务谁关注什么指标 ## 技术栈与目录结构 - 主语言Python 3.11 - 框架FastAPI, SQLAlchemy 2.x, Pydantic v2 - 包管理uv - 关键目录 - app/core领域模型与业务规则禁止依赖外部服务 - app/adapters数据库、消息队列、第三方 API 适配层 - app/apiHTTP 接口层只做参数接收与响应组装 - tests/unit单元测试不访问网络 - tests/integration集成测试需要本地依赖服务 ## 关键命令 - 安装依赖uv sync - 启动服务uvicorn app.main:app --reload --port 8000 - 运行全部测试pytest tests/ -q - 运行单元测试pytest tests/unit -q - 代码检查ruff check . mypy app - 格式化ruff format . ## 代码约定 - 命名函数使用 snake_case类用 PascalCase常量用 UPPER_SNAKE_CASE。 - 错误处理业务异常必须使用 app/core/exceptions.py 中自定义异常禁止裸抛 RuntimeError。 - 日志统一使用 structlog禁止 print 调试输出除非是 CLI 工具。 - 数据库禁止在 app/api 层直接执行 SQL一律走 repository 层。 - 测试新增业务逻辑必须伴有单元测试测试文件命名 test_module.py。 ## 工作流说明 - 开发步骤理解需求 - 定位影响模块 - 查看现有实现 - 修改 - 补测试 - 本地运行相关测试。 - 完成定义所有涉及模块的单元测试通过ruff 无警告mypy 无类型错误。 - 注意无论何时都不要修改 app/core 模块的对外接口除非需求本身要求破坏性变更。这个模板看起来很简单但它的好用之处在于信息密度高、路径明确、禁止项写得清清楚楚。AGENTS.md 真正的价值不在于字数多而在于它能精准约束 AI 行为。我见过有人写到几千行结果 AI 反而抓不住重点因为上下文里塞满了废话。3.3 老项目改造如何把历史经验沉淀进去很多人问我新项目好写 AGENTS.md那存量老项目怎么办我自己的做法是分三步第一步翻历史 commit 和 code review 记录。找那些反复出现过的问题比如别用全局变量改状态不要在 util 里塞太多函数连接数据库必须用连接池这些就是最有价值的第一手素材。第二步跑一遍项目的完整流程。从拉代码到启动、测试、构建把每一步实际用到的命令记录下来。你会发现 README 里的命令很多早就过时了正好借这个机会更新。第三步找项目里最有经验的人访谈。让他说出在日常开发中最烦的三件事、最容易被新手弄坏的地方、最不希望 AI 乱动的模块在哪。这些信息写进 AGENTS.md比任何空泛的规范都管用。我在给一个老项目补 AGENTS.md 的时候就是靠这三步一个小时不到就把核心约束摸清了。后来团队里有人让 AI 改代码明显感觉 AI 的分寸感好很多不该碰的地方基本不碰了。4. 实践中踩过的坑与排查实录4.1 为什么我的 AGENTS.md 失灵了实话实说AGENTS.md 不是放进去就万事大吉。我自己至少踩过这几个坑写出来给大家做参考。坑一位置不对。有人把 AGENTS.md 放在 docs/ 子目录下或者在子项目里放了一堆同名文件。大部分 AI 工具在查找上下文文件时默认找的是仓库根目录下的 AGENTS.md。你藏在三四个层级之下工具根本不会主动加载。我一开始就吃过这个亏写了满满一份结果 AI 一次都没读到后来把它挪到根目录才生效。坑二内容太软。AGENTS.md 里写了一大堆应当尽量保证代码质量注意模块间解耦这种话。AI 看到这种建议性的语句执行权重是很低的。它会当成参考意见而不是硬性规则。你必须把它写成不可协商的命令式语句禁止从 adapter 导入到 core所有对外接口必须写 docstring。坑三上下文冲突。有次我既在 AGENTS.md 里写了使用 pytest又在某个子模块的 README 里写了使用 unittestAI 在决策时出现了上下文冲突最后它选了 README 里的内容。这提醒我AGENTS.md 的有效性取决于它和其他文档的一致性。你必须在整个仓库范围内消除矛盾否则 AI 会无所适从。坑四没有负面约束。很多人写 AGENTS.md 只写应该做什么不写绝对不要做什么。但据我观察AI 犯错往往不是因为不知道该干什么而是因为不知道有什么禁区。它在重构的时候胆子很大敢动那些不该动的接口就是因为没人明确说过这个东西不能碰。现在我的 AGENTS.md 里专门有一块是禁止清单效果立竿见影。坑五没有版本管理意识。AGENTS.md 也是要演进的。项目经历了大规模重构、换了框架、改了目录结构但 AGENTS.md 还停留在半年前的状态那它反而会误导 AI。我踩过一次重构后核心目录从lib/改成了src/AGENTS.md 没同步AI 每次都在老路径上打转。后来我把 AGENTS.md 的更新写进了重构的完成清单里才算根治。4.2 常见问题速查表问题现象可能原因解决方法AI 完全无视 AGENTS.md文件不在项目根目录编辑器未开启读取项目指令选项移到根目录检查 Cursor / Copilot 的项目级指令配置AI 只是读了但没执行内容太软建议性语气太多指令和代码库现状冲突改成命令式表达消除文档冲突在子目录中上下文丢失工具只在根目录加载 AGENTS.md子目录的请求没有带入在子目录放精简版 AGENTS.md只写该目录相关约束修改多轮后 AI 逐渐遗忘规则上下文窗口被长对话占满早期指令被挤出明确要求 AI 在每次修改前快速回顾 AGENTS.md 关键约束或拆分任务为多个短对话生成的代码风格仍然不一致AGENTS.md 里没有具体格式化命令和工具配置写明命令行ruff format .、prettier --write .等新旧规范冲突AI 行为随机多个文档规则矛盾统一收敛到 AGENTS.md废弃过时文档或加注已由 AGENTS.md 取代我特别想强调最后一行文档的一致性太重要了。AI 不像人有常识它面对互相矛盾的信息时经常随机挑选一个来执行。你写完 AGENTS.md 之后可以试着在仓库里搜一遍不要应该注意这类词看有没有旧文档里的建议跟 AGENTS.md 冲突。这种行为叫指令审计每次做完AI 的表现都会上一个台阶。5. 对 AI 的驯化边界与更宏观的工作流设计5.1 不要指望一份 Markdown 解决所有问题AGENTS.md 能提升 AI 的下限但它不是银弹。遇到几个方向性的问题一份文件解决不了它依然挡不住 AI 在业务逻辑层面的根本性误解。AGENTS.md 能告诉 AI 应该遵守什么规则但很难传达这个产品为什么这样设计。如果需求本身描述不清AI 可能在规则之内做出一版完全错误的实现。它也无法替代代码评审。AI 读得再认真也只是在尽量模仿人类的判断力。像性能瓶颈、可维护性、长期演进这类需要全局视角的问题目前还是要靠人来兜底。我遇到过一种更隐蔽的情况AGENTS.md 写得越详细AI 就越守规矩但同时也变得小心翼翼。有次我问它能不能做一个有创意的方案重构它全程在纠结我写的那条禁止修改公共接口的规则最后给出的方案非常保守。这说明AGENTS.md 里的规则如果写得太死反而会压制 AI 在合理范围内的灵活性。所以我现在会把规则分成两档硬性约束红线和软性偏好建议让 AI 在守住红线的前提下保留判断空间。5.2 AGENTS.md 在 agent 项目中的扩展玩法前面聊的多是人用 AI 辅助编码的场景但 AGENTS.md 在 agent 项目里的角色还可以更重。我在做一个自动化 agent 的时候发现可以直接把 AGENTS.md 的内容当 system prompt 的补充源来用我在 app/agents/ 目录下放了一个专门的 AGENTS.md里面写清楚了这个 agent 的职责边界、能调用哪些工具、遇到什么情况必须停止并向用户确认、哪些回复必须遵循的格式。然后在代码里启动 agent 时直接把文件内容读入 contextwith open(agents/intent_router/AGENTS.md, encodingutf-8) as f: system_prompt_supplement f.read() agent create_agent( system_promptSYSTEM_PROMPT_TEMPLATE \n\n---\n system_prompt_supplement, tools[...], )这样做的好处是改 agent 行为不用改代码直接改 Markdown 就行。团队里不会写代码的产品同学也能参与调教 agent 的行为。这个模式我用下来非常顺手甚至比在代码里去维护一堆 if-else 分支清晰得多。更进一步我观察到社区里有的项目开始用AGENTS.md配合context.md做分级上下文。根目录的 AGENTS.md 放全项目全局约束子模块的 AGENTS.md 放局部细节。AI 工具在深入某个子模块时可以同时加载全局文件和局部文件既不会丢失全局视野也能获得局部精度。这种分层上下文的思想本质上和我们在写代码时做模块化是一样的我后面打算把团队里所有 agent 项目都改成这种结构。6. 最后的建议如果你现在打算开始用6.1 从最小可行版本开始别一上来就求全我一直觉得AGENTS.md 最忌讳的是一步到位。你第一次写只要覆盖四件事就够了项目一句话定位。怎么跑测试这一条能直接带来收益。代码命名和格式化命令。三条你最在意、AI 最容易违反的硬性约束。写这么多就够了。花二十分钟放到仓库里跑一天试试效果。你会很快发现哪些内容真正被 AI 用到了哪些内容它根本无视然后再迭代。很多人上来就写上千行结果大部分内容是 AI 用不上的空话反而掩盖了真正重要的规则。6.2 用提问测试法验证你的 AGENTS.md 有没有用最后分享一个我每次写完 AGENTS.md 都会做的验证方法姑且叫提问测试法新建一个空对话不提供任何额外提示直接问 AI 三个问题这个项目是干什么的怎么运行单元测试修改代码时最重要的三条约束是什么看 AI 能不能准确回答。如果它说错了说明你的 AGENTS.md 没有被正确加载或者写得不清晰。如果它能准确说出来说明后续的自动改代码大概率会遵守这些约束。这个测试我每次做完都会有新发现有一次发现 AI 把另一个项目的技术栈都算到这个项目头上了排查半天发现是它在缓存里读取了旧项目的 index。我自己用 AGENTS.md 已经有小半年了最大的感受是它不是玄学也不是银弹就是在 AI 时代给项目补上的一份使用说明书。和所有工程实践一样它的价值取决于你怎么写、怎么维护、怎么和实际的工作流结合。你不一定要紧跟这套做法但如果团队里 AI 辅助编码经常出现低水平重复错误那我建议你别急着换更强的模型先试试把约束写进 AGENTS.md 里。很多时候换模型不如换上下文。
