Agent 工具使用笔记——AGENTS.md

AGENTS.md 是给 coding agent 看的项目说明文件，可以理解成 “README for agents”。它要解决的问题很朴素：这个仓库是什么、哪些命令可用、哪些地方能改、改完怎么验证。

它不适合写成教程，也不适合塞一堆个人偏好。越是常驻上下文，越应该短、准、稳定。

AGENTS.md 本质上就是普通 Markdown，没有固定 schema，也没有必填字段。标题叫什么不重要，关键是让 agent 少猜。

推荐结构

# AGENTS.md

## Project overview

This is a Hexo blog source repository using the Butterfly theme.

## Setup commands

- Build: `npm run build`
- Preview: `npm run server`

## Structure

- Posts: `source/_posts/`
- Theme config: `_config.butterfly.yml`
- Generated output: `public/`

## Editing

- Edit source files only.
- Do not edit generated files under `public/`.
- Preserve existing front matter style.
- Keep changes scoped to the requested file or feature.

## Validation

- Markdown-only edits usually do not require a full build.
- Config, theme, or layout changes should run the Hexo build.

## Security considerations

- Do not commit API keys, tokens, or private endpoint URLs.
- Do not edit deployment credentials.

写作原则

写项目事实，不写临时想法。
写可执行约束，不写抽象审美。
写稳定规则，不写一次性流程。
写 agent 需要知道的边界，不重复 README 里的完整背景。
能用命令表达的就写命令，不写“自己判断怎么测试”。
能用路径表达的就写路径，不写“相关文件都看一下”。

好的说明不是项目介绍，而是减少误操作。

常见章节

AGENTS.md 不强制章节名。下面这些只是常见写法：

Project overview：项目是什么，主要技术栈是什么。
Setup commands：安装依赖、启动开发环境、初始化本地数据。
Build and test commands：构建、测试、lint、类型检查。
Code style：格式化、命名、架构约定。
Testing instructions：改什么要跑什么测试，如何只跑相关测试。
Security considerations：凭据、隐私数据、危险目录、外部服务。
PR / commit instructions：标题格式、变更说明、合并前检查。

不需要硬套模板。小项目可以很短，大项目再拆局部 AGENTS.md。

适合写入

构建命令
测试命令
代码风格
目录边界
生成文件禁止修改
发布前检查要求
依赖管理方式
本地开发入口
常见生成物位置
需要避开的外部服务、凭据和发布文件

不要写入

API key
token
私有代理账号密码
大段教程
很少用到的复杂流程
模糊要求，例如“写得优雅”
已经过期的命令
和当前项目无关的个人偏好
需要实时联网确认的信息

内容边界

不适合放入 AGENTS.md 的内容，可以挪到别处：

多步骤 release 流程：放 skill 或专门文档。
个人偏好：放用户级配置。
代码规范长文：放 formatter / linter / style guide。
复杂排错手册：放 docs 或 skill。
工具专属开关：放对应工具自己的配置文件。

维护方式

命令变了就改，不要让 agent 学到旧命令。
新增生成目录时，及时写入禁止修改或清理规则。
如果某条规则总是被忽略，说明它可能太模糊，需要改成路径、命令或明确禁止项。
如果某段内容只在少数任务有用，就移出 AGENTS.md，避免污染常驻上下文。

参考

AGENTS.md