AGENTS.md 实战：如何让 Agent 读懂代码仓库

一个陌生 Agent 进入仓库时，最浪费时间的动作往往不是写错代码，而是猜。

它猜入口文件在哪里，猜哪条脚本才能构建，猜生产环境和本地环境是否一样，猜某个看起来能删的目录是不是生成物。项目越复杂，这种猜测的代价越高。

AGENTS.md 的意义不是替 README 再写一遍，也不是给模型塞一万字公司制度。它应该是一个高信噪比的项目入口：让 Agent 在第一次进入仓库时就知道该先看什么、不能碰什么、怎样证明工作完成。

一、一个好入口只回答关键问题

根目录的 AGENTS.md 应尽量短，但必须回答：

  1. 项目解决什么问题，关键入口在哪里；
  2. 核心架构边界和不能破坏的契约；
  3. 安装、运行、测试、构建的标准命令；
  4. 哪些目录是源文件、生成物、运行数据或敏感配置；
  5. 哪些动作可自主执行，哪些必须先确认；
  6. 详细架构、决策和进度文档在哪里。

它的目标不是让 Agent 了解一切，而是让它在十分钟内建立正确的第一张地图。

二、一个可直接开始的模板

# Project overview

- 本项目用于：[一句话说明目标]。
- 主要入口：[目录或服务]。
- 源文件：[路径]；生成文件：[路径]；不要直接编辑生成文件。

## Architecture boundaries

- [模块 A] 只能通过 [接口] 访问 [模块 B]。
- 不改变：[公共 API、数据格式、兼容性约束]。
- 不读取或输出：[密钥、私有数据、运行时数据目录]。

## Standard commands

- Install: `[command]`
- Run: `[command]`
- Test: `[command]`
- Build: `[command]`
- Full validation: `[command]`

## Change rules

- 先检查现有改动；不要覆盖无关修改。
- 小步修改；完成后审查 diff。
- 需要新增依赖、修改部署或扩大范围时先说明影响。

## Safety and approvals

- 可自主：只读检查、本地修改、测试。
- 必须确认：发布、推送、删除、生产写入、外部消息和付费动作。

## Documentation map

- Architecture: `docs/architecture.md`
- Decisions: `docs/decisions/`
- Long-task state: `docs/agent/progress.md`
- Release workflow: `skills/release/SKILL.md`

不要照抄路径。真正有价值的是把你项目里最容易被误判的地方翻译成清晰边界。

三、文档要按需展开

最大的反模式，是把所有细节都塞进根规则。最后 Agent 每次改一行样式都要读部署、数据库和历史决策，重要信息反而被淹没。

更适合 Agent 的仓库像这样组织：

AGENTS.md
docs/
├── architecture.md       # 模块关系与数据流
├── conventions.md        # 编码与命名约定
├── decisions/            # ADR：关键决策及被放弃方案
└── agent/
    ├── project-memory.md # 已验证的稳定事实
    └── progress.md       # 长任务当前状态
skills/
├── debug/
└── release/
scripts/
└── validate.sh

根规则提供地图；具体任务再进入对应文档。这样既减少上下文噪声，也让规则能随着项目局部演进。

四、把“不要猜”变成可执行路径

假设 Agent 要修改一篇博客文章。一个差的项目入口可能只写着“使用 Hexo”。它仍不知道文章在哪、线上文件能不能改、发布会影响什么。

更可操作的说明是：

文章源码位于 source/_posts/。
不要直接修改 public/ 或线上 HTML，它们由构建产物覆盖。
修改前先检查 git status；发布前运行项目发布脚本。
部署配置、运行数据和环境变量不属于文章任务范围。

这几句话同时回答了入口、生成边界、验证和安全范围。它的价值远高于“请小心操作”。

五、让错误信息也成为导航

Agent-friendly 不只是写文档。脚本和错误信息也应告诉下一步。

不好的输出：

Build failed

更有用的输出：

Build failed: required environment variable BLOG_URL is missing.
For local preview, copy .env.example to .env and set a non-production value.
Do not print existing production values.

前者只报告失败；后者同时说明根因、恢复方向和安全边界。无论读者是人还是 Agent，都更容易做对下一步。

六、检查 AGENTS.md 是否真的有用

把仓库交给一个没有聊天历史的 Agent，让它只读根规则后回答：

  • 这个项目是什么，最常见任务的入口在哪里？
  • 哪条命令能验证改动？
  • 哪些文件不应该直接改？
  • 什么时候必须停下来请求确认？
  • 需要理解架构或历史决定时去哪里找？

如果它答不出来，说明不是 Agent 不够聪明，而是入口仍缺少信息。把这些问题变成回归检查；每次有人踩到新坑，就考虑是否应该补一条短规则或更清晰的脚本提示。

AI 实现摘要

  • 要解决的问题：为陌生 Agent 提供高信噪比仓库入口，减少错误定位、架构违规和危险操作。
  • 适用版本与前置条件：适用于任意使用版本控制的项目；推荐维护 Markdown 文档和稳定的 build/test 命令。
  • 输入、输出与验收标准：输入为项目结构、命令和安全边界；输出为根 AGENTS.md 与按需文档地图。新 Agent 应能定位入口、验证命令、禁止目录和审批条件。
  • 文件改动清单：根 AGENTS.md，可选 docs/architecture.md、docs/decisions/、docs/agent/、skills/ 与 scripts/。
  • 完整命令：使用项目自身命令；最低限度建议提供可重复的 install、run、test、build 和 validation 入口。
  • 测试步骤与预期结果：让无历史上下文的 Agent 按根规则完成一项只读定位或小修改任务；预期它不误改生成物，且能运行正确验证命令。
  • 常见错误、回滚方法与安全边界：不要将密钥、生产地址、个人数据或完整运行日志写入文档。规则更新应走版本控制；错误规则可通过回滚提交恢复。