AGENTS.md 模板与示例：复制即用（2026）
七套可直接复制的 AGENTS.md 模板，覆盖 TypeScript、Python、Go、monorepo 与终端代理；还讲清了格式规则、嵌套作用域，以及哪些内容不该写进去。
你手上的每一个编码代理，都可以指向同一个文件：AGENTS.md。它就是普通 Markdown，没有任何必填字段。按维护这个格式的官方站 agents.md 的说法，它已经被「超过 6 万个开源项目」使用。如果你的代理还是无视你的测试命令、又装了一个重复的 HTTP 库、或者顺手改了你没让它碰的六个文件——要修的多半不是提示词，而是一条它在动手之前会读到的书面指令。
这篇就是一个模板库：一张表讲清格式规则，一张只收录「当天能在官方文档里查到」的支持矩阵，再加七套覆盖真实项目形态的可粘贴模板。
一分钟看完：AGENTS.md 的格式规则
| 问题 | 答案 |
|---|---|
| 它是什么 | 「一种引导编码代理的简单开放格式」——写给机器看的 README |
| 有必填字段吗 | 没有："AGENTS.md 就是标准 Markdown。想用什么标题都行，代理只是解析你写的文本" |
| 放哪儿 | 仓库根目录；大仓库再往每个包里放嵌套文件 |
| 冲突时听谁的 | "离被编辑文件最近的那个 AGENTS.md 生效；用户在对话里的明确指令覆盖一切" |
| 该写什么 | 项目概览、构建与测试命令、代码风格、测试说明、安全注意事项 |
| 谁能读 | Codex、Claude Code、Copilot CLI、Cursor、Devin Desktop、opencode、Warp 等，见下方矩阵 |
| 是否开放免费 | 是；"现由 Linux 基金会旗下的 Agentic AI Foundation 托管" |
到底哪些代理会读它
只列当天能拿出书面依据的工具，并且每一行引的是厂商自己的文档，而不是格式官网那张兼容名单。
| 工具 | 它自己的文档怎么写(2026 年 9 月) |
|---|---|
| OpenAI Codex | "Codex 会在动手之前读取 AGENTS.md。" 先读 ~/.codex 里的全局文件，再从仓库根一路读到当前工作目录 |
| Claude Code | 更新日志 2.1.277:"项目里没有 CLAUDE.md 时，Claude Code 转而读取 AGENTS.md"；开关在 /config 里 |
| GitHub Copilot CLI | 与 CLAUDE.md、GEMINI.md 一起被发现；/instructions 能看到实际加载了哪些文件 |
| Cursor | 四类规则之一："Cursor 支持项目根目录和子目录里的 AGENTS.md" |
| Devin Desktop(原 Windsurf) | 根目录文件"按 always-on 规则处理"；子目录文件变成作用于 <directory>/** 的 glob 规则；agents.md 也认 |
| opencode | "你可以通过创建 AGENTS.md 文件给 opencode 提供自定义指令。" /init 能生成一份 |
| Warp | 默认的项目规则文件；同目录下 WARP.md 仍然优先；"文件名必须全大写才会被识别" |
| Gemini CLI | 按 agents.md 记录的配置开启：{ "context": { "fileName": "AGENTS.md" } } 写进 .gemini/settings.json |
| Aider | 需要显式开：.aider.conf.yml 里写 read: AGENTS.md;Aider 官方文档把这个位置留给 CONVENTIONS.md |
| OpenClaw | 同名不同用途："AGENTS.md——操作指令……每个会话开始时加载"；其中 ## Tools 段"并不控制工具可用性，只是提示" |
agents.md 上还列了 Factory、goose、Zed、Devin、UiPath、Junie、Amp、RooCode、Kilo Code、Phoenix、Semgrep、Ona、Windsurf、Augment Code、Jules、VS Code 为兼容方，这里不再逐一展开。
文件放哪、谁覆盖谁
根目录是默认答案。大仓库里官方建议写得很直接："在每个包里再放一个 AGENTS.md。代理会自动读取目录树里离它最近的那份，因此最近的一份优先，每个子项目都能带上量身定制的指令。" agents.md 同时提到，OpenAI 主仓库里有 88 个 AGENTS.md 文件。
一旦开始嵌套，有三条机制必须知道：
- 是合并还是替换。 Codex 从根目录往下拼接到当前工作目录，所以嵌套文件是追加在根文件之后，靠"出现得更晚"来覆盖。Devin Desktop 则从位置推断激活方式：根目录=始终生效，子目录=按 glob 生效。
- 体积上限。 拼接后的指令达到
project_doc_max_bytes(官方写"默认 32 KiB")就不再加文件。官方给的解法是调高上限，或者把指令拆到嵌套目录里。 - 对话永远压过文件。 用户在对话里的明确指令覆盖一切；而只要你列了测试命令，代理"会尝试执行相关的程序化检查，并在收尾前修掉失败项"。
最小骨架
下面七套模板都是它的变体——能稳定起作用的最短版本。
# AGENTS.md
## Project
Next.js 15 app router 后台,Postgres。产品背景看 README.md。
## Commands
- 安装:pnpm install
- 开发:pnpm dev
- 静态检查:pnpm lint
- 测试:pnpm test
- 单个测试:pnpm test -- <path>
## Rules
- TypeScript 严格模式;没有 `// reason:` 注释不许写 `any`
- 优先改现有文件,而不是新建文件
- 绝不提交 .env 或任何像密钥的东西
七套可直接复制的 AGENTS.md 模板
抄之前先读两份真实的：agents.md 直接链了 openai/codex、apache/airflow、temporalio/sdk-java、PlutoLang/Pluto 里的线上文件，还给了 path:AGENTS.md 的 GitHub 代码搜索。下面这七套就是这些文件反复收敛出的形态。
1. TypeScript / React 应用
# AGENTS.md
## Stack
Vite + React 19 + TypeScript(严格)+ Tailwind。包管理器只用 pnpm。
## Commands, in order
1. `pnpm install --frozen-lockfile`
2. `pnpm typecheck`
3. `pnpm lint`
4. `pnpm test`
5. `pnpm build`
第一步失败就停下并汇报,不要继续往下跑。
## Conventions
- 组件:一个文件一个,用具名导出,不要 default export
- 取数逻辑放 `src/hooks/use-*.ts`,不要写在组件体里
- 公共类型放 `src/types/`;同一个 props 类型别在原地重复声明
- 要加新依赖:动手前先在总结里写出名字和体积
## Do not
- 不要顺手重构你没被要求触碰的 class 组件
- 不要加 `use client` 标记——这是 Vite SPA
2. Python 服务或 CLI
# AGENTS.md
## Environment
Python 3.12,用 uv 管理。装依赖用 `uv sync`,不要手敲 `pip install`。
## Commands
- 运行:`uv run python -m app.cli --help`
- 测试:`uv run pytest -q`
- 单个测试:`uv run pytest tests/test_orders.py::test_refund -q`
- 检查:`uv run ruff check . && uv run ruff format --check .`
- 类型:`uv run mypy app/`
## Conventions
- 所有公开函数带类型标注;签名里不许出现 `typing.Any`
- 异常统一从 `app/errors.py` 抛;库代码里不要 `print()`
- 用 `httpx` 而不是 `requests`;边界上用 Pydantic 模型
- 每个 bug 修复都要有回归测试;收尾前先跑一遍 pytest
3. Go 或 Rust 命令行工具
# AGENTS.md
## Go
- 构建:`go build ./...` 测试:`go test ./...`
- 检查:`gofmt -l .` 必须无输出,然后 `golangci-lint run`
- 错误:用 `fmt.Errorf("...: %w", err)` 包;库代码里绝不 panic
- 测试用表驱动:`name`、`input`、`want`,每个用例一个 `t.Run`
- 新增模块依赖前,先说清标准库为什么不够
## Rust equivalents
- `cargo fmt --check`、`cargo clippy -- -D warnings`、`cargo test`
- `src/` 里不要 `.unwrap()`;返回 `Result` 并用 `?`
4. Monorepo 根文件
# AGENTS.md
## Layout
- `packages/ui` —— 纯展示组件,不碰数据
- `packages/core` —— 领域逻辑,不依赖框架
- `apps/web`、`apps/api` —— 只做组装
## Working in this repo
- 一切走 turbo 过滤:`pnpm turbo run test --filter=<pkg>`
- 新加包之后:`pnpm install --filter <pkg>`,workspace 才看得见
- 跨包引用只走某个包的公开入口,不要写很深的内部路径
## Nested instructions
每个包都有自己的 AGENTS.md。读最近那份;本文件只是公共底线。
5. 严格门禁版(测试与 lint 是硬卡点)
# AGENTS.md
## Definition of done —— 四项必须按顺序通过
1. `pnpm typecheck`
2. `pnpm lint --max-warnings 0`
3. `pnpm test -- --coverage`(改动文件覆盖率 80%)
4. `pnpm build`
## Hard rules
- 检查没过就先去修,别继续写新代码。绝不留着红色测试收尾。
- 不要为了让 CI 变绿就削弱断言、删测试或加 skip——
把冲突报出来,而不是自己悄悄解决。
- 没被要求就不要动 `pnpm-lock.yaml`、迁移文件和生成物。
## 这些情况要问,不要猜
- 需要改表结构、加环境变量或引入新依赖
- 仓库里两条约定互相矛盾
6. 终端代理的全局文件(Codex 等)
全局指令放在工具自己的 home 目录里，这样每个仓库都能继承。Codex 对应的是 ~/.codex/AGENTS.md(同目录下的 AGENTS.override.md 会顶掉它，CODEX_HOME 可以换目录)。
# ~/.codex/AGENTS.md
## Working agreements
- 要改超过两个文件,先用三条要点说方案。
- 用 `rg` 找代码,别用 `ls` 一层层翻。
- 每批改动之后就跑一次仓库的测试命令,不要留到最后。
- 加生产依赖前先问。
## Never
- 不 `git push`、不 `--force`、不改不是你提交的 commit。
- 不提交生成物和任何像密钥的内容。
要验证而不是假设。Codex 官方给的检查看法是：codex --ask-for-approval never "Summarize the current instructions." 它应当按优先级顺序复述出全局与项目两层文件。
7. 分层架构 + 依赖方向约束
价值最高的 AGENTS.md，往往写的是代理光看文件名推不出来的架构约束。
# AGENTS.md
## Architecture
`core/`(基础设施)← `modules/`(业务逻辑)← `routes/`(HTTP)← `components/`(UI)。
引用只允许一个方向。任何模块都不许被别处 import 内部实现。
## Per-module shape
- `modules/<name>/service.ts` —— 纯函数,不 import 框架
- `routes/api/<name>.ts` —— 鉴权、解析入参、调 service、返回统一信封
- 响应统一 `{ code, message, data }`;错误也是同一个结构
## Forbidden
- service 文件之外出现 SQL
- 因为某个 handler"看着是内部的"就跳过鉴权
- 跨模块引用(有一个已记录的例外,先问再说)
什么值得写，什么会让代理变笨
值得写的是代码里看不见的东西：命令顺序、散落三处却从没落纸的约定、绝对不能碰的文件、以及它该停下来提问的边界。凡是能从仓库里自己推出来的，一律不写。
Devin Desktop 的文档把判断标准说得很直白——"具体的例子和明确的约定，比含糊的准则更有效"，并且拿 Use TypeScript strict mode 和 Write good code 做了对照。
上面这些工具都适用的经验：
| 值得写 | 噪音，删掉 |
|---|---|
| 带参数、按执行顺序写清的确切命令 | "跑一下常规检查" |
| 停止条件；什么时候该问而不是该猜 | 仓库其实并没有遵守的理想化风格 |
| 哪些是生成文件、不许编辑 | README.md 的复制品 |
| 忽略就会出事的依赖与目录规则 | 每个嵌套文件里重复抄一遍全局规则——文档说"子文件会继承父目录" |
| 一到两个示范代码片段 | 对着代码逐行解释代码自己已经说明的东西 |
保持简短。超出某个工具体积上限的指令文件不会大声报错——Codex 会截断，而最先被砍掉的是文件底部那几条。
常见问题
AGENTS.md 有强制格式或 schema 吗？ 没有。官方 FAQ 回答「有必填字段吗」时写的是："没有。AGENTS.md 就是标准 Markdown。想用什么标题都行，代理只是解析你写的文本。"分节是习惯，不是语法。
该写 AGENTS.md 还是 CLAUDE.md?
只要用不止一个代理，就写 AGENTS.md:它是跨工具的名字，而 Claude Code 在没有 CLAUDE.md 时会转去读它(更新日志 2.1.277)。Copilot CLI 会在同一轮发现里同时看 AGENTS.md、CLAUDE.md 和 GEMINI.md，所以一份公共文件就能覆盖三家。只有 Claude 专有设置才留在 CLAUDE.md。
Python、Go 项目能用吗，还是只适合 TypeScript?
能用，格式与语言无关。变的只有命令本身：模板 2 用 uv/ruff/mypy，模板 3 用 gofmt/golangci-lint。把确切调用写出来，因为代理没写在纸面上就会做错的就是这一步。
能当 Codex 的全局配置用吗？
可以。Codex 会先读 ~/.codex/AGENTS.md(或 AGENTS.override.md)，再读项目文件，所以可复用的工作约定放全局，仓库特有的留在仓库。project_doc_fallback_filenames 还能把 TEAM_GUIDE.md 这类历史文件名加进发现列表。
AGENTS.md 要提交进 git 吗？ 要——这正是别人机器上的代理拿到同一套指令的方式，opencode 文档也是这么建议的。例外是 OpenClaw 那类代理工作区用法：那里的 AGENTS.md 属于私人状态，官方文档建议把该工作区放进私有仓库。
为什么我的代理还是无视这个文件？
文档里能查到的原因有四个：附近有个 AGENTS.override.md(Codex)或同目录有 WARP.md(Warp)抢了优先级；拼接后超过体积上限；文件名大小写不对(Warp 要求全大写，不过 Devin Desktop 两种都认)；或者你对话里的指令本身优先级更高。Copilot CLI 的 /instructions 和 Codex 的指令复述探针，都能看到实际加载了什么。
相关阅读
- DeepSeek harness 搭建指南——AGENTS.md 里写的终端代理接线，从零到跑通
- OpenCode 教程——安装、
/init，以及用免费模型跑代理 - Claude Code Router 教程——
CLAUDE.md与AGENTS.md指向不同模型时怎么路由 - Antigravity YOLO 模式攻略——代理跳过审批门禁之后，哪些约定变得更重要
- Claude Code 做游戏开发——项目指令在真实工作流里的样子
- Claude Projects 模板——同一件"写一次、到处复用"的事，换到 Projects 里
一份范围合适的 AGENTS.md 大概一小时能写完，而且不像提示词那样很快过期。从骨架起步，加上你的代理最容易做错的两条命令，然后就可以收手了。