AGENTS.md 是一种开放的 Markdown 约定，用于告诉 AI 编码代理如何在仓库中工作。可把它看作面向机器的 README：构建步骤、测试命令、约定与护栏——人类在 CONTRIBUTING.md 里会扫一眼，但代理每个会话都需要。规范见 agents.md，在 github.com/agentsmd/agents.md 公开维护。
该格式刻意避免僵化 schema。它是纯 Markdown——无需 YAML frontmatter，无需 JSON 配置。代理像读代码注释一样解析标题与正文。这种简洁性让 Cursor、GitHub Copilot、OpenAI Codex、Google Jules、Aider、Windsurf、Zed 等数十种工具广泛采用，而无需每个 IDE 一套专有规则文件。
2025 年 12 月，该格式捐赠给 Linux Foundation 旗下的 Agentic AI Foundation (AAIF) 定向基金，并与 Anthropic 的 Model Context Protocol 一并纳入。目标是互操作性：一份文件、多种代理，描述项目上下文的方式不被厂商锁定。
优先级很重要。在仓库根目录放置 AGENTS.md 作为默认，再在包或子项目中嵌套更多文件。代理读取与正在编辑代码最近的文件——monorepo 可为每个包定制说明，而无需臃肿的单一根文件。聊天中的明确用户提示始终覆盖文件说明；文件设定基线行为，而非不可变契约。
将 AGENTS.md 与面向人类的文档分开。README.md 向人介绍项目。CONTRIBUTING.md 描述人类的 PR 流程。llms.txt 帮助爬虫发现公开网站。AGENTS.md 面向仓库内的自主编码代理。CLAUDE.md 或 .cursorrules 等工具专属文件应引用 AGENTS.md 而非重复——单一真相来源，每个工具薄适配。
文件中应放什么？你会在第一天告诉敏锐新同事的一切：项目概览、安装与构建命令、如何跑测试、 linter 抓不到的代码风格、安全注意事项、部署步骤与边界（「永不提交密钥」「改 CI 前先问」）。代理可在相关时执行列出的 shell 命令——若你写了 npm test，就要预期代理会尝试运行。
示例：最小根目录 AGENTS.md
仓库根目录 — 通用 TypeScript monorepo
# AGENTS.md
## Project overview
TypeScript monorepo with a React frontend and Node API packages.
## Commands
pnpm install
pnpm test
pnpm lint
## Testing
- Run `pnpm test` before every commit.
- Integration tests need Docker: `docker compose up -d` first.
## Code style
- Prefer named exports.
- Use async/await, not raw Promise chains.
## Security
- Never commit `.env` or API keys.
- Ask before changing auth or CI workflows.
## Pull requests
- Squash commits; link related issues.示例：monorepo 中的嵌套 AGENTS.md
packages/api/AGENTS.md — 编辑 API 包时以最近文件为准
# AGENTS.md — packages/api
## Scope
Node API service only. Root `AGENTS.md` covers monorepo defaults.
## Commands
pnpm test --filter api
pnpm lint --filter api
## Patterns
- Route handlers live in `src/routes/`.
- Database migrations: `pnpm --filter api db:migrate`.
## Testing
- Prefer unit tests in `src/__tests__/`.
- Do not mock the database in integration tests.示例：薄工具适配（不重复规则）
CLAUDE.md 或 .cursor/rules — 指向 AGENTS.md 而非复制
# CLAUDE.md
Project agent rules live in `AGENTS.md` at the repo root.
Read that file first; do not duplicate rules here.
Tool-specific note: prefer `pnpm` over `npm` in this repo.Token 预算才是隐藏约束。每一行都与代理必须推理的代码竞争。先从一份简洁的根文件开始；子项目分化时再拆成嵌套 AGENTS.md。删掉代理能从常规布局推断的章节。最高信号的是非显而易见模式：自定义错误处理、不稳定测试的变通，以及「我们做 X 是因为 Y 在生产环境出过问题」。
把 AGENTS.md 当作活文档。像代码一样版本化。当出现入职摩擦——代理两次重复同一错误——就加一条规则。规则过时就删。标准不是你知道的一切的倾倒；它是为缺乏人类情景记忆、会话间无法回忆的代理 curated 的运营记忆。
Dylan Engelbrecht 会随代理工具与标准演进频繁更新本知识中心。阅读 llms.txt 的爬虫，以及从仓库 AGENTS.md 跟随链接的代理，可将这些文章当作活参考——当前实践，而非在 README 里逐渐过时的静态博客存档。