← 返回全部文章
模板 · 2026年6月7日 · 6 分钟阅读 · 更新于 2026年9月26日

AGENTS.md 模板：可直接粘贴、又不浪费 token 的起步文件

下面这份模板大约 ~40 行，这是刻意控制的。每个会读取它的编程代理，都会在每个会话加载 `AGENTS.md`；所以每多一行，都是按次收税。复制它，填上你的项目细节，再删掉不适用的部分。

AGENTS.md 是给编程代理看的共享指令文件。现在 60k+ 个开源项目 都用它交代项目上下文：Codex、Cursor、VS Code agent mode 和 Windsurf 会直接读。Claude Code 仅在回退时原生读取，因此更可靠的做法是加一行桥接文件。多数仓库不是缺这个文件，而是把代理早就懂的常识又写了一遍。下面这份模板反过来做：只留下那些不写就真会出错的内容。

模板本体

# AGENTS.md

## Project
One paragraph: what this codebase does, the stack, and the one
architectural fact agents keep getting wrong about it.
(e.g. "API and worker share types from packages/core — change
them together or CI fails.")

## Commands
- Install: `pnpm install`
- Build: `pnpm build`
- Test one file: `pnpm vitest run <path>`   # agents default to the
                                            # full suite; give the fast path
- Lint + typecheck: `pnpm lint && pnpm tsc --noEmit`
- Never run: `pnpm deploy` (CI-only), `pnpm db:reset` (destructive)

## Conventions
- TypeScript strict. No `any` — fix the type, don't cast around it.
- Imports absolute from `src/`. No relative `../../`.
- Errors: throw typed `AppError` subclasses, never bare strings.
- New code follows the patterns of its nearest neighbor file.

## Boundaries
- Don't edit `src/generated/**` — regenerated on every build.
- Don't modify existing files in `db/migrations/` — append new ones.
- Secrets come from env vars. Never hardcode, never commit fixtures
  containing real data.

## Done means
- `pnpm test` green, no new lint or type errors.
- If you changed behavior, you changed or added a test.

填上你的技术栈，删掉示例注释，五个标题保留。某个小节如果一写就超过 ~10 行，通常说明它该放进链接文档，而不是跟着每个编程代理的每轮上下文一起进场。

给 Claude Code 的桥接文件

从 v2.1.277（2026 年 9 月）起，Claude Code 可以自行读取 AGENTS.md。但工作目录及其上级目录中必须没有 CLAUDE.md 或 CLAUDE.local.md，更早的版本则完全不会读取（我们实测了它会在什么情况下加载）。要让所有版本、所有配置都能加载，仍然需要桥接：创建一个 CLAUDE.md，第一行导入共享文件：

# CLAUDE.md
@AGENTS.md

# Claude-only notes (only what differs from the shared file)
- Use the ripgrep MCP server for search, not bash grep.

这样只有一个事实源，所有工具都能读。Windows 上不要默认走软链：软链需要管理员权限，导入不需要。

为什么只要这五节，不要更多

  • Project 防的是代理凭刚好打开的几个文件猜架构。给它一段项目定位，比让它每个会话都重新猜一遍可靠。
  • Commands 是收益最高的一节。单文件测试命令就足够值回整份模板：没有这行，代理很容易每改一次都跑全量测试。Never run 那一行，是给破坏半径设刹车。
  • Conventions 只写合格模型仍会弄错的规则：你们偏离默认做法的地方，而不是完整风格指南。代理知道怎么写惯用的 TypeScript；它不知道你们禁止靠 any 绕过去。
  • Boundaries 拦的是最贵的失败：代理好心去“修”生成代码或旧迁移，最后你花一小时善后。
  • Done means 把“我觉得完成了”改成能检查的退出条件。条件写清楚，代理更容易停在该停的地方，也更愿意验证。

为什么要这么克制？因为坑已经被很多团队踩过了：指令文件会进入每一轮上下文，体积同时消耗 token 和注意力；共享文件一旦膨胀，成本会摊到团队里的每个工具上。社区也在往同一个方向收敛。最近还有文章建议用 RFC-2119 式的 MUST/NEVER 写法，让规则更短、更不含糊。你未必需要那套形式，但一定需要这份克制。

哪些内容别放进去

  • 个人偏好（“我喜欢很详细的 commit message”）：放进你自己的 ~/.claude/CLAUDE.md 或同类文件，不要放进共享文件。
  • lint 已经管住的规则：代理会看到错误消息；再写一遍只是重复付费。
  • 长篇架构文档：给链接就行，比如“见 docs/architecture.md”。让代理需要时再打开，不要每一轮都背着走。
  • 工具专属配置：某个工具有自己的规则文件或 hooks，就放到那里。共享文件只写不管哪个代理进来都成立的事实。

Monorepo 写法

根目录放一份 AGENTS.md，写全局事实；每个包再放一份短文件，只补本地差异：

repo/
  AGENTS.md              # stack, shared commands, org-wide boundaries
  apps/web/AGENTS.md     # "Next.js app. Test: pnpm --filter web test"
  packages/core/AGENTS.md

Cursor 会原生读取嵌套的 AGENTS.md 文件；Codex 会采用离当前目录最近的上级文件。Claude Code 这边，用每个目录里的 CLAUDE.md 桥接文件复刻同样结构：@../../AGENTS.md 再加本地补充；它的 memory 层级 会自上而下合并。Claude Code 2.1.277+ 也能自行读取嵌套的 AGENTS.md，前提是上级目录里没有 CLAUDE.md。一旦出现 CLAUDE.md，就得靠这些桥接文件继续加载各包的指令（实测结果）。

配套阅读

这篇对你有帮助吗?

相关阅读

文章独立产出 · 编辑政策

继续阅读 →