AI 概述
本文详解AGENTS.md的作用与价值，它是专为AI编码Agent设计的仓库规则文档，区别于面向人类的README.md，用于规范AI的项目操作边界。文章介绍其核心撰写板块、通用模板，适配主流AI工具，讲解撰写避坑技巧，指出该文件已是AI开发场景下的新型项目基础设施。
目录
文章目录隐藏
很多同学应该都有这样的感觉：
以前我们接手一个项目，第一件事是看 README.md。
现在让 AI Agent 接手一个项目，它也会先问几个问题：
如果这些内容只散落在 README、Confluence、飞书文档、口头约定、CI 报错里，那人类同学还能靠经验猜一猜，AI Agent 就很容易一脚踩进去。
这也是我最近特别建议大家给代码库加一个 AGENTS.md 的原因。
它看起来只是一个 Markdown 文件，但它解决的是一个很现实的问题：给 AI Agent 一份进入代码库前必须先读的工作说明书。
好了，开始我们的正文学习吧。
最近有一个挺有意思的信号：SQLite 仓库里也出现了 AGENTS.md。
SQLite 是一个很老牌、很克制、很工程化的项目。它不是那种为了赶 AI 热点每天换架构的项目，所以它加 AGENTS.md 这件事本身就很有意思。
我去看了一下 SQLite 当前仓库里的 AGENTS.md，第一句话是：
Guidance for AI coding agents working in this repository.
翻译过来很直白：这是给在这个仓库里工作的 AI 编码 Agent 的指导。
注意，这句话没有说“这是 README 的升级版”，也没有说“以后人类不用看文档了”。它说的是：AI coding agents working in this repository。
也就是说，README.md 更多是给人看的，告诉你项目是什么、怎么开始、怎么贡献；AGENTS.md 更像给 AI Agent 的“入场规则”，告诉它在这个仓库里怎么工作、怎么验证、哪些事不能乱来。
这件事看起来不大，但真正用起来很关键。
因为 AI Agent 最大的问题，往往不是不会写代码，而是不知道这个项目里的“规矩”。
看完本文后，你应该能弄清楚这几件事：
文章不准备只讲概念，重点还是落到“你今天回去怎么加”。
一句话解释：
AGENTS.md 是写给 AI 编码 Agent 的项目说明文档。
更准确一点，它是一份仓库级别的上下文文件，用来告诉 Agent：
官方的 AGENTS.md open format 给它的定位也很简单：Think of AGENTS.md as a README for agents.
OpenAI Codex 的官方文档也明确写到，Codex 会在工作前读取 AGENTS.md，并且支持全局、仓库、子目录多层叠加。也就是说，你可以在 ~/.codex/AGENTS.md 写自己的通用偏好，也可以在项目根目录写项目规则，还可以在某个服务目录下写更细的约束。
这和我们以前写文档的思路不太一样。
以前的文档大多是“给人介绍项目”：
# README.md 这是一个订单系统。 ## Quick Start npm install npm run dev
现在的 AGENTS.md 更像“给 Agent 分配工作边界”：
# AGENTS.md ## Project Overview This is a Node.js order service. It uses Nest.js, TypeORM, and Redis. ## Commands - Install: pnpm install - Dev: pnpm dev - Test: pnpm test - Lint: pnpm lint ## Working Rules - Do not modify database migrations unless the task explicitly asks. - After changing service logic, run pnpm test. - Keep DTO validation decorators in sync with API docs.
你会发现，它不需要写得很漂亮，但一定要写得很清楚。
标题里说“告别 README”，这里先打个补丁：不是说 README.md 没用了。
README.md 依然很重要，它解决的是人类协作问题：
但 AI Agent 进项目以后，它更需要的是另外一类信息：
这些内容放在 README 里不是不行，但会让 README 越来越臃肿。
更合理的方式是分工：
| 文件 | 主要读者 | 重点内容 |
|---|---|---|
| README.md | 人类开发者、开源用户、贡献者 | 项目介绍、安装、快速开始、贡献指南 |
| AGENTS.md | AI coding agent，也包括想了解项目规则的人 | 工作规则、验证命令、目录边界、禁区、任务流程 |
| CONTRIBUTING.md | 贡献者 | PR 流程、分支规范、代码审查规则 |
| CLAUDE.md / GEMINI.md / .clinerules | 特定工具 | 某个工具自己的长期上下文或规则 |
所以不是 README 被淘汰了，而是 AI Agent 需要一份更适合它的说明书。
很多 AI 编码工具现在已经能做不少事：改 bug、补测试、迁移组件、解释代码、生成 PR。
但你会发现，只要项目稍微复杂一点，它最容易翻车的地方不是语法，而是上下文：
npm install；这些问题靠模型“聪明”并不稳定，最靠谱的方式还是写清楚。
我们以前也会把规则写在聊天里，比如：
你改完以后记得跑测试。
问题是这句话只对当前对话有效。
换一个 Agent、换一个会话、换一个同事，规则又没了。
AGENTS.md 的价值就在这里：它把团队规则变成代码库的一部分。只要 Agent 支持读取这个文件，它进入仓库时就能自动拿到这些上下文。
这就像以前我们把构建流程从“口头约定”搬到 package.json scripts，把格式化规则从“大家自觉”搬到.prettierrc。
现在轮到 AI Agent 的工作规则了。
以前一个项目可能只接一个 IDE 插件，现在不一样了。
一个团队里可能同时有人用：
如果每个工具都维护一份自己的规则文件，很快就会出现一个问题：规则不同步。
今天 CLAUDE.md 说用 pnpm，明天.cursorrules说用 npm，后天.github/copilot-instructions.md忘了更新测试命令。
最后不是 Agent 傻，是我们自己给了它好几份互相打架的说明书。
所以我更建议把 AGENTS.md 当成“跨 Agent 的主入口”，再按工具需要做薄薄的适配。
这部分是本文重点。
我建议先别追求大而全，先写四个板块，今天就能用起来。
Agent 需要先知道自己在哪。
这里不用写公司战略，也不用复制 README，写清楚技术栈和核心目录就够了。
## Project Overview This repository is a monorepo for the train growth system. - `apps/web`: React frontend - `services/bff`: Nest.js BFF service - `packages/ui`: shared UI components - `packages/utils`: shared utilities Main stack: - TypeScript - React - Nest.js - pnpm workspace
这块的目标不是让 Agent 读懂整个公司业务，而是让它别一上来就找错目录。
这块非常重要。
很多 Agent 不是不会改，而是不知道改完怎么证明自己没改坏。
你需要明确告诉它：
## Commands Use `pnpm`, not `npm`. - Install dependencies: `pnpm install` - Start frontend: `pnpm --filter web dev` - Start BFF: `pnpm --filter bff dev` - Run unit tests: `pnpm test` - Run lint: `pnpm lint` - Type check: `pnpm typecheck`
如果项目很大，最好再补一句：
For small changes, prefer the most specific test command for the touched package. Do not run full e2e tests unless the task explicitly asks for it.
这样 Agent 就不会每次都跑一个半小时的全量测试，也不会完全不跑测试。
这块用来告诉 Agent：什么是“符合本项目风格”的代码。
例如：
## Code Style - Keep code in TypeScript. - Reuse existing utilities before adding new helpers. - Follow the current module structure. - Do not introduce new state management libraries. - Do not add production dependencies without asking. - Keep public API response shapes backward compatible unless requested.
这里有一个小技巧：不要只写“保持代码质量”，这种话太虚了。
要写具体规则：
Agent 需要的是可执行规则，不是口号。
这是 AGENTS.md 和普通 README 最大的区别。
你可以直接告诉 Agent 工作方式：
## Agent Workflow - Before editing, inspect existing patterns in nearby files. - Keep changes focused on the requested task. - Do not refactor unrelated code. - If a change touches payment, auth, or permissions, explain the risk before editing. - After editing, summarize changed files and verification results.
如果是生产项目，我还建议加一段安全边界：
## Safety Rules - Never print secrets, tokens, cookies, or private keys. - Do not modify `.env`, deployment configs, or CI secrets unless explicitly requested. - Do not run destructive database commands. - Ask before changing migrations or data backfill scripts.
这些规则平时看着啰嗦，但真出事时很值钱。
下面这份模板可以直接放到项目根目录。
如果你的项目比较简单，先用这版就够了。
# AGENTS.md Guidance for AI coding agents working in this repository. ## Project Overview Describe this repository in 3-5 lines: - Main product or service: - Main language/framework: - Package manager: - Important directories: ## Commands - Install dependencies: - Start development server: - Run unit tests: - Run lint: - Run type check: - Build: Notes: - Use the package manager already used by this repo. - Prefer targeted tests for the package or files you changed. ## Code Style - Follow existing patterns in nearby files. - Reuse existing utilities/components before adding new ones. - Keep changes focused on the requested task. - Do not introduce new production dependencies without asking. - Do not modify generated files unless the task explicitly requires it. ## Safety Rules - Never print or commit secrets. - Do not modify `.env` files, deployment settings, or CI secrets unless explicitly requested. - Ask before changing database migrations, permission logic, payment logic, or data backfills. ## Verification Before finishing a coding task: - Run the smallest relevant test or check. - Report what command was run and whether it passed. - If verification was not run, explain why. ## Pull Request Notes When summarizing changes: - List the files changed. - Explain behavior changes. - Mention tests or checks run. - Call out any remaining risk.
写到这里，你的项目已经比很多项目更适合 Agent 工作了。
这里单独整理一下，因为很多同学会搞混。
先说结论：**AGENTS.md 正在变成越来越多 coding agent 的共同语言，但还没有统一到所有工具。**
截至我写这篇文章时，我按官方文档和公开资料整理如下：
| 工具 | 主要规则文件 | 是否直接支持 AGENTS.md | 说明 |
|---|---|---|---|
| OpenAI Codex | AGENTS.md / AGENTS.override.md | 是 | Codex 官方文档写明会在工作前读取 AGENTS.md，支持全局、项目、子目录叠加 |
| Cursor | Project Rules、User Rules、Team Rules、AGENTS.md | 是 | Cursor Rules 文档已经把 AGENTS.md 放进持久指令体系 |
| Windsurf / Cascade / Devin | AGENTS.md | 是 | 官方文档说明可用 AGENTS.md 提供目录级指令，并按文件位置自动应用 |
| Amp | AGENTS.md，历史上也出现过 AGENT.md | 是 | Amp 早期文章使用 AGENT.md，后来更新说明现在查找复数形式 AGENTS.md |
| OpenCode | AGENTS.md 等 rules | 是 | OpenCode 的 Rules 文档用于配置自定义指令 |
| Google Jules | AGENTS.md | 是 | Jules 生态也围绕仓库级 Agent 指令展开 |
| Claude Code | CLAUDE.md | 不是主入口 | Claude Code 官方 Memory 文档核心文件是 CLAUDE.md，建议保留适配 |
| Gemini CLI | GEMINI.md | 不是主入口 | Gemini CLI 文档中核心上下文文件是 GEMINI.md |
| GitHub Copilot | .github/copilot-instructions.md 等 | 部分场景支持/仍以 Copilot 指令为主 | GitHub 官方文档强调仓库自定义指令文件 |
| Aider | CONVENTIONS.md / –read 配置 | 不是默认主入口 | Aider 官方文档建议用 CONVENTIONS.md 并通过 /read 或配置读取 |
| Cline | .clinerules / .clinerules/*.md | 不是主入口 | Cline 有自己的 rules 文件体系 |
这里不要死记名字，记住一个原则就行：
AGENTS.md 做主入口，工具专属文件做适配。
比如你的项目可以这样放：
. ├── AGENTS.md ├── README.md ├── CLAUDE.md ├── GEMINI.md └── .github/ └── copilot-instructions.md
其中 CLAUDE.md、GEMINI.md、copilot-instructions.md 不需要再复制一大堆内容，可以写得很薄：
# CLAUDE.md Please follow the repository guidance in `AGENTS.md`.
或者：
# GEMINI.md Use `AGENTS.md` as the source of truth for repository conventions, commands, and safety rules.
这样做的好处是，团队只维护一份主规则，不同工具都能尽量对齐。
文档最怕两件事：
一是没人写。
二是写了没人维护。
AGENTS.md 也一样。
我建议注意这几个点。
不要一开始就写 300 行。
先把最容易让 Agent 犯错的 10 条规则写进去：
能用起来，比完整更重要。
不要写：
- Write high quality code.
这种话基本没用。
改成：
- Run `pnpm lint` after changing TypeScript files. - Add or update tests when changing business logic. - Do not change public API response fields unless requested.
规则越具体，Agent 越容易执行。
如果某个坑你已经踩过，就不要让 Agent 再踩一次。
例如：
## Known Pitfalls - `packages/api-client` is generated from OpenAPI schema. Do not edit it manually. - `legacy/order.ts` is still used by offline jobs. Do not remove exports without checking usages. - Payment callbacks must remain idempotent.
这部分对老项目特别有用。
很多项目的知识不是写在 README 里，而是写在老同事脑子里。
现在可以先搬一部分到 AGENTS.md。
如果你新增了测试命令、迁移了包管理器、调整了目录结构，就顺手更新 AGENTS.md。
可以把它当成一种轻量级工程资产。
就像改了 API 要更新接口文档，改了 Agent 工作规则也要更新 AGENTS.md。
都可以。
如果团队主要中文协作，可以中文写；如果你的 Agent、开源贡献者、外包团队混合使用，英文会更通用。
我个人更建议：标题和命令用英文，业务解释可以中文。
比如：
## Safety Rules - 不要修改支付回调逻辑，除非任务明确要求。 - Do not commit secrets.
Agent 能理解，人也能看懂。
不需要。
先在仓库根目录放一个就够了。
只有当某些目录规则明显不同，比如 services/payment、packages/ui、infra，再考虑加局部文件。
Codex 这类工具支持从全局、项目根目录一路叠加到当前目录，越靠近当前目录的规则越具体。
这对 monorepo 很有用。
不建议。
README 面向人，AGENTS 面向 Agent，读者不同，内容重点不同。
更好的做法是：
会，所以不要写敏感信息。
不要把 token、账号、内网地址、生产库连接串、客户隐私、真实密钥写进去。
可以写规则，不要写秘密。
例如可以写：
- Never print or commit secrets. - Ask before changing deployment configs.
不要写：
- Production database password is xxx.
这个不用解释，谁写谁背锅。
如果你现在已经开始在项目里用 AI 编码工具，我建议你今天就加一个 AGENTS.md。
不要等到它很完美。
先写清楚这几件事：
以前我们给新人准备 README，是为了让人更快进入项目。
现在我们给 AI Agent 准备 AGENTS.md，是为了让它别靠猜来改代码。
这件事不复杂，但很值得做。
如果你的代码库已经开始有第二个 Agent 进入，那 AGENTS.md 就不是“加分项”了，而是新的项目基础设施。
以上关于程序员必备AGENTS.md配置指南 规避AI编码修改乱象的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。
声明：本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权/违法违规/事实不符，请将相关资料发送至 admin@mybj123.com 进行投诉反馈，一经查实，立即处理！
重要：如软件存在付费、会员、充值等，均属软件开发者或所属公司行为，与本站无关，网友需自行判断
码云笔记 » 程序员必备AGENTS.md配置指南 规避AI编码修改乱象
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。