AGENTS.md实战指南：让AI coding agent真正读懂你的代码库

到 2025 年底，AI 编程 agent 已经不再是玩具。Claude Code、Codex、Cursor、Copilot 和 opencode 如今在真实仓库里做着真实的工作——团队们发现，一个能提交干净 PR 的 agent 和一个会破坏构建的 agent 之间，只隔着一个文件：AGENTS.md。

如果你还没见过它：AGENTS.md 是一个 markdown 文件，放在仓库根目录，用来告诉 AI agent 你的仓库实际是怎么运作的。命令、约定、架构、坑点。Agent 在会话开始时读取它——在它接触任何文件之前。

这篇文章是一份实用、有观点的指南：该在这个文件里放什么、不该放什么，以及我在生产仓库里实际使用的模板。

Agent 没有直觉，只有上下文窗口。如果没有指引，一个进入全新仓库的 agent 会：

猜测你的测试命令（大概是 uv run pytest -m "not e2e"，而不是 pytest）

遵循某种与你的代码库完全不匹配的通用风格

通过删除加载了 bug 的代码来"修复"bug

提交生成的文件，或者运行会修改本地 DB 的命令

以上每一条都是上下文问题，不是能力问题。AGENTS.md 是最低成本的修复：一个文件，在每次会话开始时读取。

Anthropic 的 Claude Code、OpenAI 的 Codex、Cursor 和 GitHub Copilot 现在都能原生读取它。写一次，每个进入你仓库的 agent 都会带着你团队的实际知识启动。

有效的结构

为大量不同的仓库写过这些文件之后，我锁定了一个能经受真实代码库考验的结构：

一句话目的。用一句话说明这个仓库是什么。Agent 会搜索这个文件；所以第一行就要说出它们需要知道的东西。

命令——精确的五个。Setup、test（带精确的 filter 标志）、lint、typecheck、build。写实际的命令，不要写"运行测试"。光这一节就能防止大部分破坏。

工作流。"完成"意味着什么。"每个变更必须添加或更新测试。推送前运行完整套件。永远不要强制推送到 main。"这是你和 agent 之间的契约。

架构地图。重要东西在哪里，用 5-10 条子弹列出。不是完整的 README——是地图。"业务逻辑在 src/domain/，DB 访问只能通过 src/db/repo.py。"

样式规则。只有你们真正在意的两三条规则，不是 lint 规则清单。"新代码必须匹配周围文件的风格。没有充分理由不能在 PR 里加新依赖。"

坑点和禁忌。"永远不要在 prod 上运行 migrate。localhost:8080 是唯一的开发主机。data/ 目录被 gitignore 且由 make seed 重新生成。"

Kill List。Agent 不允许做的事。删除代码、"顺便"重构、手动编辑 lockfile——不管你们团队被什么坑过。

保持 300 行以内。如果更长，agent 会开始忽略文件末尾的内容。

不要放什么

最常见的错误是把 AGENTS.md 当作文档来写：

不要放长教程或架构论文。Agent 能读代码；它们需要的是指针，不是解释。

不要重复 README 的内容。README 是给人类看的，AGENTS.md 是给 agent 看的。职责不同。

不要放你没有强制执行的绝对规则。"永远写出完美代码"是噪音。Agent 无法据此行动，而且会让它认为你的文件只是装饰。

不要放秘密或内部 URL。这个文件会被提交。如果仓库最终公开或被分享，AGENTS.md 里的所有内容都是公开的。

这是我一直放在 agentsmd-kit 里的起始模板，免费的，MIT 许可：

# AGENTS.md

## Purpose
[One sentence: what this repo is and does]

## Commands
- Setup: [...]
- Test: [...]  (include exact filter flags)
- Lint: [...]
- Typecheck: [...]
- Build: [...]

## Workflow
- [...]
- [...]

## Architecture
- [...]
- [...]
- [...]

## Style
- [...]
- [...]

## Gotchas
- [...]
- [...]

## Don'ts
- [...]
- [...]

复制它，用你仓库的实际答案填满括号，提交。如果不知道某个答案，就去搞清楚——一份半真半假的 AGENTS.md 比没有更糟糕，因为 agent 会信任它。

40 点加固清单

一份好的 AGENTS.md 只是开始，不是结束。那些让 agent 大放异彩的仓库本身也是 agent 友好的：密封的测试命令、CI 门控、快速反馈循环、范围受限的权限。

如果你想要完整清单——我在允许 agent 进入仓库之前对仓库运行的 40 点审计——我把它放进了 Pro Pack（$29，一次性，即时交付）：18 个针对不同技术栈的模板（Python、TypeScript、Rust、Go、iOS、MCP 服务器、ML、monorepo……）、CLAUDE.md 和 Cursor-rules 伴侣、那份清单，以及常见 agent 任务的提示词模板。买一次，每个仓库都能用。

或者如果你不想自己维护，我可以为团队编写定制的 AGENTS.md + CLAUDE.md 套装——直接雇佣我。

AGENTS.md 是 2026 年使用 AI agent 的团队能获得的最便宜的生产力提升。就是一个文件。好好写一个下午就能完成。它能把你的 agent 从"打字快的想法家"变成遵守你约定的团队成员。

从免费模板开始，诚实填写，一周内你就会看到 agent 的 PR 破坏性大大降低。

我是 Arpit——我为团队构建 AGENTS.md 和 agent-gate 套装。获取免费套件或购买 Pro Pack。