文章目录AGENTS.md 简介一、核心理念二、官方示例AGENTS.md 简介AGENTS.md 是一个简单、开放的格式用于指导 AI 编码代理coding agents。可以把它理解为“给 AI 看的 README”。目前已被超过 6 万个开源项目采用。一、核心理念README.md 是给人看的快速开始、项目描述、贡献指南AGENTS.md 是给 AI 代理看的构建步骤、测试命令、编码规范等详细上下文分开放是为了保持 README 简洁同时给 AI 一个可预测的、固定的位置来获取指令应该放什么内容典型的 AGENTS.md 包含以下几个部分项目概述 — 项目是什么、做什么环境设置 / 构建命令 — 如 pnpm install、pnpm dev测试命令和说明 — 如何运行测试、测试通过的标准代码风格指南 — TypeScript strict mode、单引号/双引号、分号规则等PR / Commit 规范 — 提交信息格式、PR 标题格式安全注意事项 — 安全相关的特殊说明部署步骤 — 部署流程其他你会告诉新队友的事情 — 大数据集处理、特殊 gotcha 等不建议把密钥、账号、完整大段业务文档、自动生成文件或频繁变化的数据直接放进 AGENTS.md这些内容更适合放在受控配置、外部文档或按需读取的 docs 文件中。实际使用时第一版不需要追求完整先把 AI 最容易问错或做错的内容写进去项目启动方式、测试方式、目录边界、命名规则、禁止事项以及需要按需读取的文档入口。二、官方示例# Sample AGENTS.md file ## Dev environment tips - Use pnpm dlx turbo run where project_name to jump to a package instead of scanning with ls. - Run pnpm install --filter project_name to add the package to your workspace so Vite, ESLint, and TypeScript can see it. - Use pnpm create vitelatest project_name -- --template react-ts to spin up a new React Vite package with TypeScript checks ready. - Check the name field inside each packages package.json to confirm the right name—skip the top-level one. ## Testing instructions - Find the CI plan in the .github/workflows folder. - Run pnpm turbo run test --filter project_name to run every check defined for that package. - From the package root you can just call pnpm test. The commit should pass all tests before you merge. - To focus on one step, add the Vitest pattern: pnpm vitest run -t test name. - Fix any test or type errors until the whole suite is green. - After moving files or changing imports, run pnpm lint --filter project_name to be sure ESLint and TypeScript rules still pass. - Add or update tests for the code you change, even if nobody asked. ## PR instructions - Title format: [project_name] Title - Always run pnpm lint and pnpm test before committing.关键特性纯 Markdown没有必填字段用任何标题都行支持嵌套大型 monorepo 可以在每个子包里放独立的 AGENTS.mdAI 会读取离当前编辑文件最近的那个优先级最近的 AGENTS.md 优先用户的直接聊天指令覆盖一切跨工具兼容支持 OpenAI Codex、Google Jules、Cursor、Aider、GitHub Copilot、Windsurf、VS Code 等 20 种 AI 编码工具由 Linux Foundation 下的 Agentic AI Foundation 维护AGENTS.md 的优势在于它是跨工具的开放标准写一次就能被多种 AI 代理理解。额外场景AGENTS.md 的优势在于它是跨工具的开放标准写一次就能被多种 AI 代理理解。不过仍有一些工具并不直接支持这个规范部分适配方式可以在 AGENTS.md 文档的 FAQ 部分找到。Claude Code这里额外说明一下 Claude Code 工具的适配Claude Code 默认不会读取 AGENTS.md但会读取 CLAUDE.md 文件所以可以利用这一点达到目的。核心逻辑是在 AGENTS.md 文件的同级目录下创建一个 CLAUDE.md 文件内容只需要写上AGENTS.md这样 Claude Code 在读取 CLAUDE.md 时会继续读取 AGENTS.md 文件。可以在 Git 的 pre-commit 阶段添加脚本逻辑自动生成例如前端项目下# Sync AGENTS.md → CLAUDE.md# For every AGENTS.md in the repo, ensure a corresponding CLAUDE.md exists# with an AGENTS.md import. If missing, create it and stage it.REPO_ROOT$(gitrev-parse --show-toplevel)find$REPO_ROOT-nameAGENTS.md-not-path*/node_modules/*-not-path*/.git/*|whileread-ragents_file;dodir$(dirname$agents_file)claude_file$dir/CLAUDE.mdif[!-f$claude_file];thenechoAGENTS.md$claude_filegitadd$claude_fileecho[agents-sync] Created${claude_file#$REPO_ROOT/}fidone也可以在项目中的 AGENTS.md 或 skill 中添加更新逻辑。