你让AI“优化一下”，它顺手重构了全项目；你让它“修一个小问题”，它顺手升级了依赖；你让它“整理文档”，它把你刚删的内容又补回来——这些不是AI故意添乱，而是它不知道项目的边界在哪里。AGENTS.md就是为这个问题准备的：一张贴在项目门口的工作规矩，告诉AI Agent哪些地方能碰、哪些不能碰、什么情况该停下来先问人。

AI Agent很能干，但它有一个天然问题：它不知道你的项目“哪些地方不能碰”。真实项目里，边界、历史、协作习惯、风险等级，往往比“多做一点”更重要。AGENTS.md的作用就是把这些长期规则提前写下来，告诉AI Agent：这个项目是做什么的、当前最重要的边界是什么、哪些文件不能乱动、哪些行为必须先问人、修改以后怎样验收、什么情况宁可停下来也不要自作主张。简单说，提示词管这一次任务，AGENTS.md管这个项目里的长期做事方式。

AGENTS.md不只对Codex有用，只要一个AI工具开始具备Agent能力（能读文件、改文件、运行命令、创建内容、调用工具），能力越强越需要项目级规则。不同工具读取规则文件的名字可能不同——有的读AGENTS.md，有的读CLAUDE.md。关键是理解这个核心思想：AI Agent需要一份稳定的项目上下文，不应该每次都靠你临时复制到聊天框里。

判断一条规则有没有用，可以问自己一句话：它能不能挡住一次真实翻车？比如你曾经遇到过AI把你删掉的段落又补回来，就写“当前文件内容是谁一有效基线，用户已经删除的内容不要自动恢复”。比如你遇到过AI修一个按钮顺手重构了全项目，就写“优先做最小改动，能局部修改就不要重构全项目”。比如你遇到过AI还没问清楚就开始改，就写“当目标不清楚、边界不清楚、可能影响已有成果时，先提问，不要直接动手”。

好规则不是摆在那里好看的，它应该来自你真实踩过的坑。

AGENTS.md最适合写五类内容。第一类项目目标——如“这是一个给新手使用的本地工具，优先保持简单、稳定、可解释”。第二类不能破坏的核心功能——如“必须保留现有导入、编辑、导出流程；必须保留当前已经通过验收的功能”。第三类禁止行为——如“不要删除文件；不要未经确认重命名文件；不要未经确认引入新依赖；不要把本地流程改成在线流程”。第四类协作流程——如“大改前先给计划，说明会影响哪些文件；如果用户只要求讨论，不要修改文件”。第五类验收方式——如“修改完成后说明改了什么、为什么改、用户应该怎样检查；涉及界面变化时尽量提供截图或明确的人工检查步骤”。

不适合写进AGENTS.md的内容包括：一次性任务（应写在本次提示词里）、互相打架的规则、太多口号（如“高级”“专业”“优雅”没有具体标准容易诱导自由发挥）。不要把AGENTS.md当成一劳永逸的文件——项目变了，规则也要变。

AGENTS.md可以放在不同层级。根目录的AGENTS.md管大范围规则（整个知识库、整个工作区、整个仓库），适合写长期底线——如“不要删除文件”“不要恢复用户已经删掉的内容”“不要把排版任务做成重写”“不要把局部修改扩大成整体改造”。项目目录里的AGENTS.md应该更具体。例如一个本地PDF工具项目可以写“这个项目的目标是本地打开、编辑、导出PDF；PDF文件不能上传到线上服务；默认导出新文件不覆盖原文件”。越靠近具体项目，规则越应该具体。根目录规则像底线，项目规则像施工说明，两者不是替代关系，而是叠加关系。

新手不要一上来追求完美模板。可以先写一个很短的版本：项目目标是本地练习项目，优先保持简单、稳定、可理解；修改边界是能局部修改就不要重构全项目、不要删除/移动/重命名文件除非明确要求、不要引入新依赖除非明确确认；协作方式是目标不清楚时先提问、大改前先说明计划和影响范围、修改完成后说明如何验收。这已经比没有规则强很多。等项目继续推进，再把真实踩过的坑补进去。AGENTS.md不是一次写完的，它应该随着项目长出来。

Karpathy式示范AGENTS.md提供了工程化模板，核心思想包括：先读README和现有代码再改；遵循项目已有的风格；不引入新框架/依赖/构建步骤；保持API和已有行为稳定；任务模糊时问简短问题；大改前解释计划和涉及文件；做最小改动；不相关重构不做；不删/不移/不重命名文件除非明确要求；跑最小相关测试；改完总结怎么验证；不覆盖用户工作；把当前工作树视为事实来源；不恢复已删内容除非明确要求；破坏性命令前停止并询问；沟通简洁、报告重要假设、说明风险和后续工作。