[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"$fuhzQn8ZzYQHnufJqwUUfg3y-EV-twj8-ZczxO2_BlNs":3},{"item":4,"related":51},{"id":5,"type":6,"title":7,"slug":8,"summary":9,"body":10,"coverUrl":11,"productScreenshots":12,"productLinks":13,"authorName":14,"authorUrl":15,"authorSubject":16,"category":17,"tags":22,"sourceLabel":39,"sourceName":40,"sourceUrl":41,"status":42,"seoTitle":43,"seoDescription":44,"canonicalUrl":45,"isFeatured":46,"sno":47,"sortOrder":48,"publishedAt":49,"updatedAt":50,"createdAt":50},"c32560f1-2916-4cb5-852a-f094830ab001","article","为什么 AI 编程项目开始需要 AGENTS.md？","agents-md-coding-agent-context","AGENTS.md 是给 AI 编程 Agent 看的项目协作说明，可以记录构建命令、测试方式、目录规则和安全注意事项。本文解释它为什么不同于 README，如何用嵌套文件管理 monorepo 规则，以及怎样避免写成无效的口号。","当 AI 编程 Agent 进入一个真实仓库，它面对的通常不是“写一个函数”这么简单。它还需要知道项目用什么命令启动、测试在哪里、哪些目录不能改、代码风格是什么、提交前必须通过哪些检查。\n\n这些信息如果只存在于人的记忆里，Agent 每次都要重新猜；如果全部塞进 README，又会让面向人的文档变得臃肿。AGENTS.md 的目标，就是给代码 Agent 提供一个稳定、可预测的项目上下文文件。\n\n## 先给结论：AGENTS.md 是给 Agent 看的项目协作说明\n\nAGENTS.md 官方网站把它比作“给 Agent 的 README”：它可以记录构建命令、测试方式、代码约定、安全注意事项和部署流程，同时不必把所有细节混进面向人类贡献者的 README。[AGENTS.md 官方说明](https:\u002F\u002Fagents.md\u002F)\n\n它不是新的编程语言，也不是一个需要注册的服务。它就是 Markdown 文件，但文件名和位置让不同的编码 Agent 可以用一致方式发现它。\n\n一个最小版本可以这样写：\n\n~~~markdown\n文件名：AGENTS.md\n\n## 项目概览\n\n这是一个使用 TypeScript 和 Vite 的前端项目。\n\n## 常用命令\n\n- 安装依赖：pnpm install\n- 启动开发环境：pnpm dev\n- 运行测试：pnpm test\n- 运行检查：pnpm lint\n\n## 修改约束\n\n- 不要直接编辑生成目录。\n- 修改 API 时同步更新测试。\n- 提交前运行相关测试和类型检查。\n~~~\n\n## 为什么 README 不够\n\nREADME 通常服务第一次接触项目的人，内容重点是项目是什么、怎么安装、如何快速运行。Agent 需要的上下文更偏向执行：\n\n- 哪个命令才是真正的测试入口；\n- monorepo 中应该进入哪个 package；\n- 哪些文件由代码生成器维护；\n- 修改某个模块后必须运行哪些专项检查；\n- 项目里有哪些看起来合理、实际上不能触碰的兼容逻辑。\n\n这些信息对人类也有价值，但不一定适合全部放在 README 首页。AGENTS.md 提供了一个专门位置，让 Agent 有机会在开始修改前主动读取。\n\n## 嵌套文件让大型仓库拥有局部规则\n\n一个仓库可以在根目录放一份通用规则，也可以在子目录里放更具体的 AGENTS.md：\n\n~~~text\nrepo\u002F\n├── AGENTS.md\n├── apps\u002F\n│   ├── AGENTS.md\n│   └── web\u002F\n│       └── AGENTS.md\n└── packages\u002F\n    └── api\u002F\n        └── AGENTS.md\n~~~\n\n当 Agent 修改 apps\u002Fweb\u002F 下的文件时，它需要同时理解根目录和更近的局部规则。AGENTS.md 官方说明建议使用“离目标文件最近的文件优先”的方式处理范围和冲突；用户在当前对话中的明确要求仍然应该拥有更高优先级。[层级与优先级说明](https:\u002F\u002Fagents.md\u002F#how-to-use-agents-md)\n\n这很像作用域：根文件定义整个项目的公共约束，子目录文件补充某个模块的特殊要求。它比“一份几千行全局说明”更容易维护，也更接近代码真正的边界。\n\n## 高质量的 AGENTS.md 应该写什么\n\n可以把内容分成四层：\n\n### 1. 让 Agent 快速定位\n\n说明项目结构、关键目录和入口。不要只写“这是一个前端项目”，而要告诉它页面、服务端、测试和生成文件分别在哪里。\n\n### 2. 让 Agent 能运行\n\n列出安装、开发、测试、构建和 lint 命令。命令要尽可能是仓库真实使用的命令，不要复制一份已经过期的脚本名。\n\n### 3. 让 Agent 知道怎么改\n\n写清代码风格、命名方式、错误处理、测试要求和 API 变更规则。比起“保持代码整洁”，更有用的是“新增服务函数时必须同时添加对应的单元测试”。\n\n### 4. 让 Agent 知道什么时候停下来问\n\n如果改动会涉及数据库迁移、凭据、生产环境、删除数据或破坏兼容性，文件应该明确要求先确认。Agent 的效率不应来自跳过风险控制。\n\n## 常见失败写法\n\n### 规则太抽象\n\n“写高质量代码”“遵循最佳实践”几乎不能帮助 Agent 做决定。规则应该连接到文件、命令或可验证结果。\n\n### 命令已经失效\n\n过期的测试命令会让 Agent 得出错误结论。AGENTS.md 不是一次性配置，而是随项目变化的活文档。\n\n### 把所有事情都禁止\n\n如果每条规则都是“不要做”，Agent 会变得过度保守，也会忽略真正重要的约束。应当同时写“可以做什么”和“遇到什么情况需要确认”。\n\n### 把秘密写进去\n\nAGENTS.md 会进入版本库，不能放 Token、密码、内部地址或任何不应公开的凭据。需要秘密时，说明变量名称和获取方式即可。\n\n## AGENTS.md、Skill 和 Prompt 的边界\n\n三者可以配合，但职责不一样：\n\n| 机制 | 最适合放什么 |\n| --- | --- |\n| Prompt | 当前任务的目标和临时要求 |\n| AGENTS.md | 这个仓库长期有效的工作规则 |\n| Skill | 可跨项目复用的专业工作流 |\n\n例如，“修复登录 Bug”是当前 Prompt；“修改认证模块后必须运行安全测试”是 AGENTS.md；“如何做一轮完整安全审计”则可以做成 Skill。\n\n## 最后用一个问题检查它\n\n把 AGENTS.md 交给一个刚加入项目的人，问他能不能回答：从哪里开始、怎么验证、哪些地方不能碰、什么时候要停下来确认。如果不能，问题通常不是文件不够长，而是缺少可执行的上下文。\n\n一句话总结：**AGENTS.md 不会让模型突然变聪明，但会让它少走很多本来不该走的弯路。**\n\n## 来源\n\n- [AGENTS.md 官方说明](https:\u002F\u002Fagents.md\u002F)\n- [OpenAI Codex：Custom instructions with AGENTS.md](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fguides\u002Fagents-md)","\u002Fuploads\u002F2026-09-08\u002F4c344fca-326c-4a51-8acb-95d39f6f927b.jpg",[],[],"Foundit","https:\u002F\u002Ffoundit.cn","foundit-ai-editorial",{"id":18,"name":19,"slug":20,"description":21},"6179d3b6-dc34-4483-9ded-3cd9f1b37a47","科普","abbreviation","介绍各领域新兴概念",[23,27,31,35],{"id":24,"name":25,"slug":26},"0848beb4-db26-4fb8-b391-f852a11be192","AI编程","ai-coding",{"id":28,"name":29,"slug":30},"144abe77-0dc6-4f66-a176-20bddb1c0bfa","编程","coding",{"id":32,"name":33,"slug":34},"a202d639-99a6-488a-a712-4d4c6ffd7e15","开发","dev",{"id":36,"name":37,"slug":38},"7c76bfc2-f80f-4ee0-a95d-27bd8708b434","技术","slug","AGENTS.md 官方说明","AGENTS.md","https:\u002F\u002Fagents.md\u002F","published","AGENTS.md 是什么：给 AI 编程 Agent 的项目说明书","介绍 AGENTS.md 如何补充 README、管理仓库级和目录级规则，并给出适合 AI 编程项目的上下文文件写法与常见陷阱。",null,false,58,0,"2026-09-08T00:00:00.000Z","2026-09-08T03:19:25.424Z",[52,61,69],{"id":53,"type":6,"title":54,"slug":55,"summary":56,"coverUrl":57,"authorName":14,"sno":58,"publishedAt":59,"createdAt":60},"54d83c94-d588-400d-9d13-42daa20331e2","CAS：文件的身份可以由内容决定","content-addressable-storage-ai-coding","内容寻址存储 CAS 用内容摘要识别文件和构建产物，解释 AI 编程工具、容器和缓存为什么能复用结果。","\u002Fuploads\u002F2026-09-14\u002F3fab23b3-8bcd-4a3b-bf5a-2ab895ce3a10.jpg",41,"2026-09-14T00:00:00.000Z","2026-09-14T15:01:41.114Z",{"id":62,"type":6,"title":63,"slug":64,"summary":65,"coverUrl":66,"authorName":14,"sno":67,"publishedAt":59,"createdAt":68},"1be15b45-ad30-4bbf-b711-718a9ffc58b3","Tree-sitter：为什么编辑器不用每次重读整个文件？","tree-sitter-incremental-parsing-ai-coding","Tree-sitter 用增量解析和语法树帮助编辑器与 AI 编程工具只处理代码变化的局部，让搜索、补全和结构化修改更高效。","\u002Fuploads\u002F2026-09-14\u002Fc4a4730d-34e0-43bb-8d5c-bd79b20e1969.jpg",47,"2026-09-14T15:01:26.675Z",{"id":70,"type":6,"title":71,"slug":72,"summary":73,"coverUrl":74,"authorName":14,"sno":75,"publishedAt":59,"createdAt":76},"373f9a49-3705-46dc-823c-7ef1923f1b54","OpenAPI 如何让 AI 同时写前后端不“各说各话”？","openapi-ai-frontend-backend-contract","AI 可以分别生成前端和后端，却容易在字段、错误和时间格式上互相错位。本文解释 OpenAPI 如何把接口输入输出变成共同契约，再连接生成代码和契约测试。","\u002Fuploads\u002F2026-09-14\u002F4e99751f-020c-45dd-a87d-1a9fbb8f0f83.jpg",48,"2026-09-14T11:00:08.021Z"]