AGENTS.md：给 AI 写一份项目说明书

AGENTS.md 封面

问题

你有没有这种经历：每次让 AI 帮你写代码，它都用错缩进、选错框架、命名风格跟你项目格格不入？你纠正一次，下次对话它又忘了。

根本原因是：AI 没有你项目的上下文。它不知道你用 4 空格还是 Tab，不知道你的 commit message 用中文还是英文，不知道你的测试跑在 Jest 还是 Vitest 上。

AGENTS.md 就是解决这个问题的。

它是什么

AGENTS.md 是一个放在项目根目录的 Markdown 文件。AI 编码助手（QoderWork、Cursor、Claude Code、Codex 等）在开始工作前会自动读取它，把里面的内容当作项目规则来遵守。

你可以把它理解为：写给 AI 的 README。README 是给人看的，AGENTS.md 是给 AI 看的。

它不是某个工具的私有格式，而是一个正在形成共识的约定。不同工具可能叫不同名字（Cursor 用 .cursorrules，Claude Code 用 CLAUDE.md），但 AGENTS.md 正在成为跨工具的通用标准。

里面写什么

没有固定模板，但以下内容最常见：

项目概述：一两句话说清楚这是什么项目、用什么技术栈。

编码规范：缩进、命名、文件组织、import 顺序。你团队 code review 时反复提的那些东西。

工作流约定：分支策略、commit message 格式、PR 描述模板、测试要求。

架构边界：哪些模块不能动、哪些目录放什么、依赖方向是什么。

禁止事项：不要用的库、不要碰的文件、不要引入的模式。

常用命令：怎么跑测试、怎么构建、怎么部署。

一个真实例子

# AGENTS.md

## 项目概述
这是一个 Astro 5 静态博客，部署在 Cloudflare Pages。
纯静态输出，不使用任何客户端 JS 框架。

## 编码规范
- 使用 2 空格缩进
- 组件用 PascalCase，文件名用 kebab-case
- CSS 写在 .astro 文件的 <style> 标签里，不单独建文件
- 不使用 Tailwind，不使用 CSS-in-JS

## 内容规范
- 博文放在 src/content/blog/，格式为 Markdown
- frontmatter 必须包含 title、date（ISO 8601 带时间）、description
- 中英文之间加空格

## 工作流
- 每篇文章写完后执行 astro build 验证
- 部署命令：wrangler pages deploy dist --project-name ohmyself-blog
- commit message 用英文，格式：type: description

## 禁止
- 不要引入 React/Vue/Svelte 等客户端框架
- 不要使用 localStorage 或任何浏览器存储 API
- 不要修改 public/ 下已有的图片文件

就这么简单。AI 读到这个文件后，写出来的代码就会自动遵守这些规则。

怎么写好它

几条经验：

写规则，不写教程。 AI 不需要你解释什么是 Git，它需要你告诉它”commit message 用 conventional commits 格式”。

写例外，不写常识。 如果整个行业都用 ESLint，你不需要写”请使用 linter”。但如果你禁用了某条规则，那值得写。

写约束，不写偏好。 “不要用 any 类型”是约束。“我觉得 TypeScript 比 JavaScript 好”是偏好，AI 不需要知道。

保持更新。 项目演进后，AGENTS.md 也要跟着改。过时的规则比没有规则更危险——AI 会严格遵守它读到的每一条指令。

越短越好。 500 行以内的 AGENTS.md 效果最好。太长 AI 会”注意力分散”，关键规则反而被忽略。

和 README 的区别

README 面向人类开发者，语气是”欢迎贡献，这是项目介绍”。AGENTS.md 面向 AI，语气是”你必须这样做，不许那样做”。

README 可以有历史背景、设计理念、感谢名单。AGENTS.md 只要可执行的规则。

两者不冲突，可以共存。很多项目的 AGENTS.md 开头就写一句”项目介绍见 README.md”，然后只列规则。

进阶用法

分层放置。 根目录放全局规则，子目录放局部规则。比如 src/api/AGENTS.md 里写 API 层的特殊约定，AI 进入那个目录时会同时读取两份。

配合 CI 检查。 把 AGENTS.md 里的规则同步到 ESLint/Prettier 配置里。AI 遵守规则，CI 验证规则，双保险。

版本控制。 AGENTS.md 应该进 Git。它和代码一样是项目的一部分，改动应该有 review。

最后

AGENTS.md 的本质是一个认知对齐工具。它把你脑子里那些”理所当然但从来没写下来”的项目知识，变成 AI 能读懂的显式规则。

写一次，每次对话都生效。比每次重复交代背景高效一百倍。

如果你正在用任何 AI 编码工具，花十分钟写一个 AGENTS.md。这可能是你今年投入产出比最高的十分钟。

← back to posts